minor updates to basic openapi descriptions

openapi-example.yaml

@@ -1,8 +1,8 @@
 openapi: 3.1.0
 info:
   title: VOSI endpoints
-  version: "1.1"
-  description: This is more or less the current VOSAI-1.1 standard.
+  version: "1.2"
+  description: This is an example of using VOSI-1.2 components.
 servers:
 - url: /example
 paths:
@@ -14,10 +14,6 @@ paths:
     /tables/{name}:
         $ref: ./vosi-table.yaml
         #$ref: https://ivoa.net/std/VOSI/vosi-table.yaml
-
-    /availability:
-        $ref: ./paths/vosi-availability.yaml
-        #$ref: https://ivoa.net/std/VOSI/vosi-availability.yaml
     /capabilities:
         $ref: ./paths/vosi-capabilities.yaml
         #$ref: https://ivoa.net/std/VOSI/vosi-capabilities.yaml

openapi/vosi-capabilities.yaml → openapi/vosi/vosi-capabilities.yaml

@@ -10,11 +10,11 @@ head:
         applicable header information. SSO-next: clients use this operation to probe
         for available authentication methods.
     responses:
-        200:
+        '200':
             $ref: ./vosi-std-responses.yaml#/authenticated
-        401:
+        '401':
             $ref: ./vosi-std-responses.yaml#/not-authenticated
-        403:
+        '403':
             $ref: ./vosi-std-responses.yaml#/permission-denied
 get:
     operationId: read-capabilities
@@ -23,11 +23,11 @@ get:
     summary: VOSI Capabilities with SSO-next prototype
     description: Get the set of VOResource capability descriptions for this service.
     responses:
-        200:
+        '200':
           $ref: '#/components/schemas/capabilities'
-        401:
+        '401':
             $ref: ./vosi-std-responses.yaml#/not-authenticated
-        403:
+        '403':
             $ref: ./vosi-std-responses.yaml#/permission-denied
 
 components:
@@ -42,3 +42,15 @@ components:
                             name: capabilities
                             prefix: vosi
                             namespace: http://www.ivoa.net/xml/VOSICapabilities/v1.0
+                    example: |
+                        <vosi:capabilities xmlns:vosi="http://www.ivoa.net/xml/VOSICapabilities/v1.0"
+                                xmlns:vr="http://www.ivoa.net/xml/VOResource/v1.0"
+                                xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.1"
+                                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+                            <capability standardID="ivo://ivoa.net/std/VOSI#capabilities">
+                                <interface xsi:type="vs:ParamHTTP" role="std">
+                                    <accessURL use="full">https://example.net/tap-service/capabilities</accessURL>
+                                </interface>
+                            </capability>
+                            ...
+                        </vosi:capabilities>

openapi/vosi/vosi-table-11.yaml

@@ -0,0 +1,94 @@
+# this is the read-only /tables/{tableName} endpoint from VOSI-1.1
+get:
+    operationId: read-table-metadata
+    tags: 
+      - VOSI Table Metadata
+    summary: get metadata for the specified table
+    description: provides the table metadata for a single schema or table
+    parameters:
+      - in: path
+        name: name
+        description: a single schema name or table name as provided in tap_schema
+        required: true
+        schema:
+          type: string
+    responses:
+        '200':
+            $ref: '#/components/schemas/tableDoc'
+        '401':
+            $ref: ./vosi-std-responses.yaml#/not-authenticated
+        '403':
+            $ref: ./vosi-std-responses.yaml#/permission-denied
+        '404':
+            $ref: ./vosi-std-responses.yaml#/not-found
+
+components:
+    schemas:
+        tableDoc:
+            description: metadata for the specified schema or table
+            content:
+                text/xml:
+                    schema:
+                        type: object
+                        xml:
+                            name: table
+                            prefix: vosi
+                            namespace: http://www.ivoa.net/xml/VOSITables/v1.0
+                    example: |
+                        <vosi:table xmlns:vosi="http://www.ivoa.net/xml/VOSITables/v1.0"
+                                xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.1"
+                                xmlns:vte="http://www.opencadc.org/xml/VOSITables-ext/v0.1"
+                                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" type="output">
+                            <name>tap_schema.schemas</name>
+                            <description>description of schemas in this tableset</description>
+                            <column>
+                              <name>schema_name</name>
+                              <description>schema name for reference to tap_schema.schemas</description>
+                              <dataType xsi:type="vs:VOTableType" arraysize="64*">char</dataType>
+                              <flag>indexed</flag>
+                            </column>
+                            <column>
+                              <name>utype</name>
+                              <description>lists the utypes of schemas in the tableset</description>
+                              <dataType xsi:type="vs:VOTableType" arraysize="512*">char</dataType>
+                            </column>
+                            <column>
+                              <name>description</name>
+                              <description>describes schemas in the tableset</description>
+                              <dataType xsi:type="vs:VOTableType" arraysize="512*">char</dataType>
+                            </column>
+                            <column>
+                              <name>schema_index</name>
+                              <description>recommended sort order when listing schemas</description>
+                              <dataType xsi:type="vs:VOTableType">int</dataType>
+                            </column>
+                          </vosi:table>
+
+                application/x-votable+xml:
+                    schema:
+                        type: object
+                        xml:
+                            name: VOTABLE
+                            namespace: http://www.ivoa.net/xml/VOTable/v1.3
+                    example: |
+                        <VOTABLE xmlns="http://www.ivoa.net/xml/VOTable/v1.3"
+                                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.4">
+                            <RESOURCE type="results">
+                                <TABLE>
+                                <FIELD name="schema_name" datatype="char" arraysize="64*">
+                                    <DESCRIPTION>schema name for reference to tap_schema.schemas</DESCRIPTION>
+                                </FIELD>
+                                <FIELD name="utype" datatype="char" arraysize="512*">
+                                    <DESCRIPTION>lists the utypes of schemas in the tableset</DESCRIPTION>
+                                </FIELD>
+                                <FIELD name="description" datatype="char" arraysize="512*">
+                                    <DESCRIPTION>describes schemas in the tableset</DESCRIPTION>
+                                </FIELD>
+                                <FIELD name="schema_index" datatype="int">
+                                    <DESCRIPTION>recommended sort order when listing schemas</DESCRIPTION>
+                                </FIELD>
+                                <!--data goes here-->
+                              </TABLE>
+                            </RESOURCE>
+                        </VOTABLE>
+