add create index API as an async job

openapi-linter

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+if [[ "$1" == "-it" ]]; then
+  docker run -it --rm -v $PWD:/work:ro dshanley/vacuum /bin/bash
+else
+  docker run --rm -v $PWD:/work:ro dshanley/vacuum lint --no-clip -d openapi.yaml
+fi
+

openapi-example.yaml → openapi.yaml

@@ -5,15 +5,29 @@ info:
   description: This is an example of using VOSI-1.2 components.
 servers:
 - url: /example
+
+tags:
+    - name: VOSI Capabilities
+    - name: VOSI Table Metadata
+    - name: VOSI Table Operations
+
 paths:
 # notes: this is how another service like TAP would include VOSI endpoints using 
 # a local copy; the commented out $ref to a standard location would also work
     /tables:
-        $ref: ./vosi-tableset.yaml
+        $ref: ./openapi/vosi/vosi-tableset.yaml
         #$ref: https://ivoa.net/std/VOSI/vosi-tableset.yaml
     /tables/{name}:
-        $ref: ./vosi-table.yaml
+        $ref: ./openapi/vosi/vosi-table.yaml
         #$ref: https://ivoa.net/std/VOSI/vosi-table.yaml
+
     /capabilities:
-        $ref: ./paths/vosi-capabilities.yaml
+        $ref: ./openapi/vosi/vosi-capabilities.yaml
         #$ref: https://ivoa.net/std/VOSI/vosi-capabilities.yaml
+
+    /table-ops:
+        $ref: ./openapi/vosi/vosi-table-ops.yaml
+    /table-ops/{jobID}:
+        $ref: ./openapi/vosi/vosi-table-ops-job.yaml
+    /table-ops/{jobID}/phase:
+        $ref: ./openapi/vosi/vosi-table-ops-job-phase.yaml

openapi/uws/uws-after-param.yaml

@@ -0,0 +1,8 @@
+name: AFTER
+in: query
+description: list jobs with creationTime after the specified value
+required: false
+schema:
+  type: string
+  format: date-time
+  example: "2017-07-21T17:32:28Z"

openapi/uws/uws-jobid-param.yaml

@@ -0,0 +1,7 @@
+name: jobID
+in: path
+description: unique job identifier generated by the server
+required: true
+schema:
+  type: string
+  example: a1b2c3

openapi/uws/uws-last-param.yaml

@@ -0,0 +1,11 @@
+name: LAST
+in: query
+description: |
+  limit the number of jobs listed to the specified value; use of LAST
+  also causes the server to return jobs in order of creationTime (descending)
+  with the most recent jobs first
+required: false
+schema:
+  type: integer
+  minimum: 0
+  example: 10

openapi/uws/uws-phase-change-param.yaml

@@ -0,0 +1,8 @@
+name: PHASE
+in: query
+description: attempt to change the phase
+required: true
+schema:
+  type: string
+  enum: [ABORT, RUN]
+  example: RUN

openapi/uws/uws-phase-param.yaml

@@ -0,0 +1,7 @@
+name: PHASE
+in: query
+description: list jobs in this execution phase
+required: false
+schema:
+  type: string
+  example: "EXECUTING"

openapi/uws/uws-responses.yaml

@@ -0,0 +1,61 @@
+# UWS create job response
+created:
+    description: standard UWS 1.1 redirect to the created job URL
+    headers:
+        location:
+            schema:
+                type: string
+                format: uri
+invalid-phase-change:
+    description: the requested phase change is invalid
+    content:
+        text/plain:
+            schema:
+                type: string
+job-listing:
+    description: list of jobs owned by the caller
+    content:
+        text/xml:
+            schema:
+                type: string
+                xml:
+                    name: jobs
+                    prefix: uws
+                    namespace: http://www.ivoa.net/xml/UWS/v1.0
+                example: |
+                    <uws:jobs xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1">
+                        <uws:jobref id="loqqxg8jlah0r8wp">
+                            <uws:phase>PENDING</uws:phase>
+                            <uws:runId>TEST</uws:runId>
+                            <uws:ownerId>somebody</uws:ownerId>
+                            <uws:creationTime>2024-07-16T16:38:33.090Z</uws:creationTime>
+                        </uws:jobref>
+                        ...
+                    </uws:jobs>
+
+job:
+    description: a single UWS Job
+    content:
+        text/xml:
+            schema:
+                type: string
+                xml:
+                    name: job
+                    prefix: uws
+                    namespace: http://www.ivoa.net/xml/UWS/v1.0
+                example: |
+                    <uws:job xmlns:uws="http://www.ivoa.net/xml/UWS/v1.0" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1">
+                        <uws:jobId>loqqxg8jlah0r8wp</uws:jobId>
+                        <uws:ownerId>somebody</uws:ownerId>
+                        <uws:phase>PENDING</uws:phase>
+                        <uws:quote>2024-07-17T16:38:33.089Z</uws:quote>
+                        <uws:creationTime>2024-07-16T16:38:33.090Z</uws:creationTime>
+                        <uws:startTime xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true" />
+                        <uws:endTime xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true" />
+                        <uws:executionDuration>28800</uws:executionDuration>
+                        <uws:destruction>2024-07-23T16:38:33.089Z</uws:destruction>
+                        <uws:parameters />
+                        <uws:results />
+                    </uws:job>
+
+

openapi/uws/uws-wait-param.yaml

@@ -0,0 +1,8 @@
+name: WAIT
+in: query
+description: wait for the specified time in seconds or until the phase changes
+required: false
+schema:
+  type: integer
+  example: 60
+

openapi/vosi/vosi-capabilities.yaml

@@ -37,13 +37,13 @@ components:
             content:
                 text/xml:
                     schema:
-                        type: object
+                        type: string
                         xml:
                             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"
+                        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">
@@ -53,4 +53,4 @@ components:
                                 </interface>
                             </capability>
                             ...
-                        </vosi:capabilities>
+                            </vosi:capabilities>

openapi/vosi/vosi-table-ops-job-phase.yaml

@@ -0,0 +1,38 @@
+get:
+    operationId: vosi-table-ops-job-phase-get
+    tags:
+        - VOSI Table Operations 
+    summary: get a UWS job phase
+    description: job phase resource
+    parameters:
+        - $ref: ../uws/uws-jobid-param.yaml
+    responses:
+        '200':
+          description: the current phase
+          content:
+              text/plain:
+                  schema:
+                      type: string
+                      example: "PENDING"
+
+post:
+    operationId: vosi-table-ops-job-phase-update
+    tags:
+        - VOSI Table Operations
+    summary: change a UWS job phase
+    description: update job
+    parameters:
+        - $ref: ../uws/uws-jobid-param.yaml
+        - $ref: ../uws/uws-phase-change-param.yaml 
+    responses:
+        '200':
+            description: phase change successful
+        '400':
+            $ref: ../uws/uws-responses.yaml#/invalid-phase-change
+        '401':
+            $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated
+        '403':
+            $ref: ../vosi/vosi-std-responses.yaml#/permission-denied
+        '404':
+            $ref: ../vosi/vosi-std-responses.yaml#/not-found
+

openapi/vosi/vosi-table-ops-job.yaml

@@ -0,0 +1,18 @@
+get:
+    operationId: vosi-table-ops-job-get
+    tags:
+        - VOSI Table Operations
+    summary: get a UWS job description
+    description: job resource
+    parameters:
+        - $ref: ../uws/uws-jobid-param.yaml
+        - $ref: ../uws/uws-wait-param.yaml
+    responses:
+        '200':
+            $ref: ../uws/uws-responses.yaml#/job
+        '401':
+            $ref: ../vosi/vosi-std-responses.yaml#/not-authenticated
+        '403':
+            $ref: ../vosi/vosi-std-responses.yaml#/permission-denied
+        '404':
+            $ref: ../vosi/vosi-std-responses.yaml#/not-found

openapi/vosi/vosi-table-ops.yaml

@@ -0,0 +1,67 @@
+get:
+    operationId: vosi-table-ops-job-list
+    tags:
+      - VOSI Table Operations
+    summary: list async table update jobs
+    description: async job listing
+    parameters:
+        - $ref: ../uws/uws-phase-param.yaml
+        - $ref: ../uws/uws-after-param.yaml
+        - $ref: ../uws/uws-last-param.yaml
+    responses:
+        '200':
+            $ref: ../uws/uws-responses.yaml#/job-listing
+        '401':
+            $ref: ./vosi-std-responses.yaml#/not-authenticated
+        '403':
+            $ref: ./vosi-std-responses.yaml#/permission-denied
+        '404':
+            $ref: ./vosi-std-responses.yaml#/not-found
+post:
+    operationId: vosi-table-ops-job-create
+    tags:
+      - VOSI Table Operations
+    summary: create async table update job 
+    description: TAP asynchronous table update (create UWS Job)
+    parameters:
+        - name: TABLE
+          in: query
+          description: a single table name as provided in tap_schema
+          required: true
+          explode: false
+          schema:
+              type: string
+        - name: INDEX
+          in: query
+          description: |
+            create index operation; value is a column name in the table
+            or a comma-separated list of columns; order matters
+          required: true
+          schema:
+            type: string
+            #pattern: ??
+        - name: INDEX_TYPE
+          in: query
+          description: |
+            qualifier to create a specialised index: a value of long-lat 
+            requires 2 numeric columns which are used as longitude,latitude
+            pairs (spherical coordinates); a value of x-y requires 2 numeric
+            columns which are used as x,y pairs (cartesian coordinates); 
+          required: false
+          # style: form (default), explode: true, and type: array
+          # means the normal zero or more param=value
+          explode: true
+          schema:
+            type: array
+            items:
+              type: string
+              enum: [long-lat,x-y,unique]
+    responses:
+        '303':
+            $ref: ../uws/uws-responses.yaml#/created
+        '401':
+            $ref: ./vosi-std-responses.yaml#/not-authenticated
+        '403':
+            $ref: ./vosi-std-responses.yaml#/permission-denied
+        '404':
+            $ref: ./vosi-std-responses.yaml#/not-found

openapi/vosi/vosi-tableset.yaml

@@ -29,7 +29,7 @@ components:
             content:
                 text/xml:
                     schema:
-                        type: object
+                        type: string
                         xml:
                             name: tableset
                             prefix: vosi