VOSICapabilities / TAPRegExt / VOResource (#25)

Addition of VOSI Capabilities, TAPRegExt and VOResource standards

README.md

@@ -18,6 +18,7 @@ The following IVOA protocols are currently supported:
 - **VOSI (IVOA Support Interfaces) version 1.1**
   - VOSI Availability
   - VOSI Tables
+  - VOSI Capabilities
 - **VODataService version 1.2 (limited)**
   - DataType
   - FKColumn
@@ -26,6 +27,9 @@ The following IVOA protocols are currently supported:
   - TableParam
   - TableSchema
   - TableSet
+  - others
+- **VOResource version 1.1**
+- **TAPRegExt version 1.0**
 
 You can read more about using these models in our documentation: https://vo-models.readthedocs.io/
 

docs/source/pages/api/index.rst

@@ -1,6 +1,6 @@
 .. _api:
 
-Developer Documentation
+API Reference
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 This section contains documentation on the package's modules and classes.
@@ -11,4 +11,5 @@ This section contains documentation on the package's modules and classes.
     uws_api
     vosi_api
     voresource_api
-    vodataservice_api
+    vodataservice_api
+    tapregext_api

docs/source/pages/api/tapregext_api.rst

@@ -0,0 +1,12 @@
+.. _tapregext_api:
+
+TAPRegExt API
+--------------
+
+Models
+^^^^^^
+
+.. automodule:: vo_models.tapregext.models
+    :members:
+    :no-inherited-members:
+    :exclude-members: model_config, model_fields

docs/source/pages/api/voresource_api.rst

@@ -3,6 +3,14 @@
 VOResource API
 --------------
 
+Models
+^^^^^^
+
+.. automodule:: vo_models.voresource.models
+    :members:
+    :no-inherited-members:
+    :exclude-members: model_config, model_fields
+
 Simple Types
 ^^^^^^^^^^^^
 .. automodule:: vo_models.voresource.types

docs/source/pages/api/vosi_api.rst

@@ -15,6 +15,14 @@ Tables
 ^^^^^^
 
 .. automodule:: vo_models.vosi.tables.models
+   :members:
+   :no-inherited-members:
+   :exclude-members: model_config, model_fields,
+
+Capabilities
+^^^^^^^^^^^^
+
+.. automodule:: vo_models.vosi.capabilities.models
    :members:
    :no-inherited-members:
    :exclude-members: model_config, model_fields,

docs/source/pages/protocols/index.rst

@@ -3,11 +3,13 @@
 Supported Protocols
 ~~~~~~~~~~~~~~~~~~~
 
-The following IVOA protocols are currently supported:
+The pages below contain some examples for each supported protocol. For a full list of all models, see the :ref:`api`.
 
 .. toctree::
     :maxdepth: 3
 
     uws
     vosi
-    vodataservice
+    vodataservice
+    voresource
+    tapregext

docs/source/pages/protocols/tapregext.rst

@@ -0,0 +1,36 @@
+.. _tapregext:
+
+TAPRegExt
+----------
+
+TAPRegExt is an IVOA XML encoding standard for describing TAP service metadata. It is used by the TAP standard to describe the capabilities of a TAP service.
+
+`vo-models` currently supports the full TAPRegExt v1.0 standard. The key model is the ``TableAccess`` model, which represents the capabilities of a TAP server:
+
+Models
+^^^^^^
+
+TableAccess
+***********
+
+This model represents the capabilities of a TAP server, used as part of the VOSI Capabilities standard.
+
+.. grid:: 2
+    :gutter: 2
+
+    .. grid-item-card:: Model
+
+        .. literalinclude:: ../../../../examples/snippets/tapregext/tapregext.py
+            :language: python
+            :start-after: TableAccess-model-start
+            :end-before: TableAccess-model-end
+
+    .. grid-item-card:: XML Output
+
+            .. literalinclude:: ../../../../examples/snippets/tapregext/tapregext.py
+                :language: xml
+                :lines: 2-
+                :start-after: TableAccess-xml-start
+                :end-before: TableAccess-xml-end
+
+See the :ref:`tapregext_api` documentation for more information on the models and types available.

docs/source/pages/protocols/voresource.rst

@@ -0,0 +1,105 @@
+.. _voresource:
+
+VOResource
+----------
+
+VOResource is an IVOA XML encoding standard for describing resource metadata. It is used by various IVOA standards, such as VODataService, VOSI, and TAPRegExt to describe resources and the services that provide access to them.
+
+`vo-models` currently supports the full VOResource v1.1 standard. Some of the key elements include:
+
+Models
+^^^^^^
+
+Resource
+********
+
+Any entity or component of a VO application that is describable and identifiable by an IVOA Identifier.
+
+.. grid:: 2
+    :gutter: 2
+
+    .. grid-item-card:: Model
+
+        .. literalinclude:: ../../../../examples/snippets/voresource/voresource.py
+            :language: python
+            :start-after: Resource-model-start
+            :end-before: Resource-model-end
+
+    .. grid-item-card:: XML Output
+
+        .. literalinclude:: ../../../../examples/snippets/voresource/voresource.py
+            :language: xml
+            :lines: 2-
+            :start-after: Resource-xml-start
+            :end-before: Resource-xml-end
+
+Service
+*******
+
+A resource that can be invoked by a client to perform some action on its behalf.
+
+.. grid:: 2
+    :gutter: 2
+
+    .. grid-item-card:: Model
+
+        .. literalinclude:: ../../../../examples/snippets/voresource/voresource.py
+            :language: python
+            :start-after: Service-model-start
+            :end-before: Service-model-end
+
+    .. grid-item-card:: XML Output
+
+        .. literalinclude:: ../../../../examples/snippets/voresource/voresource.py
+            :language: xml
+            :lines: 2-
+            :start-after: Service-xml-start
+            :end-before: Service-xml-end
+
+Capability
+**********
+
+A description of what the service does (in terms of context-specific behavior), and how to use it (in terms of an interface).
+
+.. grid:: 2
+    :gutter: 2
+
+    .. grid-item-card:: Model
+
+        .. literalinclude:: ../../../../examples/snippets/voresource/voresource.py
+            :language: python
+            :start-after: Capability-model-start
+            :end-before: Capability-model-end
+
+    .. grid-item-card:: XML Output
+
+        .. literalinclude:: ../../../../examples/snippets/voresource/voresource.py
+            :language: xml
+            :lines: 2-
+            :start-after: Capability-xml-start
+            :end-before: Capability-xml-end
+
+Interface
+*********
+
+A description of a service interface.
+
+.. grid:: 2
+    :gutter: 2
+
+    .. grid-item-card:: Model
+
+        .. literalinclude:: ../../../../examples/snippets/voresource/voresource.py
+            :language: python
+            :start-after: Interface-model-start
+            :end-before: Interface-model-end
+
+    .. grid-item-card:: XML Output
+
+        .. literalinclude:: ../../../../examples/snippets/voresource/voresource.py
+            :language: xml
+            :lines: 2-
+            :start-after: Interface-xml-start
+            :end-before: Interface-xml-end
+
+See the :ref:`voresource_api` documentation for more information on the available models and types.

docs/source/pages/protocols/vosi.rst

@@ -8,7 +8,7 @@ VOSI (VO Support Interface)
 Availability
 ^^^^^^^^^^^^
 
-The Availability model is used to represent the response given by a UWS service to a
+The Availability model is used to represent the response given by a service to a
 ``GET /availability`` request.
 
 .. grid:: 2
@@ -81,4 +81,28 @@ For requests to the ``GET /tables`` endpoint, you can use the ``TableSet`` model
             :language: xml
             :lines: 2-
             :start-after: tableset-xml-start
-            :end-before: tableset-xml-end
+            :end-before: tableset-xml-end
+
+Capabilities
+^^^^^^^^^^^^
+
+The VOSICapabilities model is used to represent the response given by a service to a
+``GET /capabilities`` request. Below is a relatively full example of a VOSI capabilities document for a TAP service.
+
+.. grid:: 2
+    :gutter: 2
+
+    .. grid-item-card:: Model
+
+        .. literalinclude:: ../../../../examples/snippets/vosi/capabilities.py
+            :language: python
+            :start-after: capabilities-model-start
+            :end-before: capabilities-model-end
+
+    .. grid-item-card:: XML Output
+
+            .. literalinclude:: ../../../../examples/snippets/vosi/capabilities.py
+                :language: xml
+                :lines: 2-
+                :start-after: capabilities-xml-start
+                :end-before: capabilities-xml-end

examples/snippets/tapregext/tapregext.py

@@ -0,0 +1,81 @@
+"""Snippets for TAPRegExt models and XML serialization."""
+from vo_models.tapregext.models import (
+    DataLimits,
+    DataModelType,
+    Language,
+    LanguageFeature,
+    LanguageFeatureList,
+    OutputFormat,
+    TableAccess,
+    TimeLimits,
+    Version,
+)
+
+# pylint: disable=invalid-name
+
+# [TableAccess-model-start]
+table_access_model = TableAccess(
+    data_model=[DataModelType(value="VOTable", ivo_id="ivo://ivoa.net/std/VOTable")],
+    language=[
+        Language(
+            name="ADQL",
+            version=[Version(value="2.0", ivo_id="ivo://ivoa.net/std/ADQL-2.0")],
+            description="Astronomical Data Query Language",
+            language_features=[
+                LanguageFeatureList(
+                    feature=[
+                        LanguageFeature(form="Formal notation", description="A description"),
+                        LanguageFeature(form="Informal notation", description="Another description"),
+                    ],
+                    type="adql-some-feature",
+                )
+            ],
+        )
+    ],
+    output_format=[
+        OutputFormat(
+            mime="application/x-votable+xml",
+            alias=["VOTABLE"],
+        )
+    ],
+    retention_period=TimeLimits(default=10, hard=100),
+    output_limit=DataLimits(
+        default={"value": 10, "unit": "row"},
+        hard={"value": 100, "unit": "row"},
+    ),
+)
+# [TableAccess-model-end]
+
+# [TableAccess-xml-start]
+table_access_xml = """
+<capability standardID="ivo://ivoa.net/std/TAP">
+        <dataModel ivo-id='ivo://ivoa.net/std/VOTable'>VOTable</dataModel>
+        <language>
+                <name>ADQL</name>
+                <version ivo-id="ivo://ivoa.net/std/ADQL-2.0">2.0</version>
+                <description>Astronomical Data Query Language</description>
+                <languageFeatures type="adql-some-feature">
+                        <feature>
+                                <form>Formal notation</form>
+                                <description>A description</description>
+                        </feature>
+                        <feature>
+                                <form>Informal notation</form>
+                                <description>Another description</description>
+                        </feature>
+                </languageFeatures>
+        </language>
+        <outputFormat>
+                <mime>application/x-votable+xml</mime>
+                <alias>VOTABLE</alias>
+        </outputFormat>
+        <retentionPeriod>
+                <default>10</default>
+                <hard>100</hard>
+        </retentionPeriod>
+        <outputLimit>
+                <default unit="row">10</default>
+                <hard unit="row">100</hard>
+        </outputLimit>
+</capability>
+"""  # [TableAccess-xml-end]