From 90ce7a529d6686b74d0cbaf346ab8aa2b3456c2c Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Fri, 9 May 2025 13:20:06 -0700 Subject: [PATCH 1/5] openapi spec for headers to convey table permissions the table description payload does not contain any notion of table ownership or permissions; this defines 3 headers that can be used to set and get minimum permissions without encumbering the table description document format(s) these headers are entirely optional and would only be applicable if a service wants to expose and allow modification of permissions via the API --- openapi/vosi-anon-read.yaml | 8 ++++++++ openapi/vosi-group-read.yaml | 7 +++++++ openapi/vosi-group-write.yaml | 7 +++++++ openapi/vosi-table.yaml | 22 ++++++++++++++++++++++ 4 files changed, 44 insertions(+) create mode 100644 openapi/vosi-anon-read.yaml create mode 100644 openapi/vosi-group-read.yaml create mode 100644 openapi/vosi-group-write.yaml diff --git a/openapi/vosi-anon-read.yaml b/openapi/vosi-anon-read.yaml new file mode 100644 index 0000000..da0201e --- /dev/null +++ b/openapi/vosi-anon-read.yaml @@ -0,0 +1,8 @@ +# request header +name: x-vosi-anon-read +in: header +description: flag indicating that the resource allows anonymous read +required: false +schema: + type: boolean + diff --git a/openapi/vosi-group-read.yaml b/openapi/vosi-group-read.yaml new file mode 100644 index 0000000..34c40b5 --- /dev/null +++ b/openapi/vosi-group-read.yaml @@ -0,0 +1,7 @@ +# request header +name: x-vosi-group-read +in: header +description: a GMS group identifier indicating a group with read permission +required: false +schema: + type: string diff --git a/openapi/vosi-group-write.yaml b/openapi/vosi-group-write.yaml new file mode 100644 index 0000000..3d112a2 --- /dev/null +++ b/openapi/vosi-group-write.yaml @@ -0,0 +1,7 @@ +# request header +name: x-vosi-group-write +in: header +description: a GMS group identifier indicating a group with write permission +required: false +schema: + type: string diff --git a/openapi/vosi-table.yaml b/openapi/vosi-table.yaml index 0589c17..54551b4 100644 --- a/openapi/vosi-table.yaml +++ b/openapi/vosi-table.yaml @@ -33,6 +33,9 @@ post: required: true schema: type: string + - $ref: ./vosi-anon-read.yaml + - $ref: ./vosi-group-read.yaml + - $ref: ./vosi-group-write.yaml requestBody: description: a table description $ref: '#/components/schemas/tableDoc' @@ -62,6 +65,9 @@ put: required: true schema: type: string + - $ref: ./vosi-anon-read.yaml + - $ref: ./vosi-group-read.yaml + - $ref: ./vosi-group-write.yaml requestBody: description: a table description $ref: '#/components/schemas/tableDoc' @@ -107,6 +113,22 @@ components: schemas: tableDoc: description: metadata for the specified schema or table + headers: + x-vosi-anon-read: + description: flag indicating that the resource allows anonymous read + required: false + schema: + type: boolean + x-vosi-group-read: + description: a GMS group identifier indicating a group with read permission + required: false + schema: + type: string + x-vosi-group-write: + description: a GMS group identifier indicating a group with write permission + required: false + schema: + type: string content: text/xml: schema: From 6a6ade35dad2375ab8f2826fe3efdad2f5b77941 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Mon, 12 May 2025 09:00:51 -0700 Subject: [PATCH 2/5] update build workflow to v3 --- .github/workflows/build.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 7f015bf..d30fe10 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -21,7 +21,7 @@ jobs: steps: - name: Checkout the repository - uses: actions/checkout@v1 + uses: actions/checkout@v3 with: submodules: true From c1b27870560d89661e9989135cd10e5c8fd100dc Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Mon, 12 May 2025 10:15:11 -0700 Subject: [PATCH 3/5] finish draft text for user managed tables and add some TODOs --- VOSI.tex | 39 ++++++++++++++++++++++++++------- openapi/vosi-std-responses.yaml | 7 ++++++ openapi/vosi-table.yaml | 4 ++++ 3 files changed, 42 insertions(+), 8 deletions(-) diff --git a/VOSI.tex b/VOSI.tex index 526c7a4..5e5fe40 100644 --- a/VOSI.tex +++ b/VOSI.tex @@ -305,7 +305,7 @@ \subsection{Table metadata} specification (see ???). Here we give a brief summary of the main use and some examples but defer to the OpenAPI documents as the definitive specification. -\subsubsection{Tables} +\subsubsection{TableSet} The TableSet metadata is a hierarchical web resource with two levels of detail. Maximum detail (max) is the complete metadata including all details of the table structure (columns and foreign keys). Minimum detail (min) includes the full @@ -337,6 +337,7 @@ \subsubsection{Tables} respond with a usable TableSet document that has the maximum level of detail so may wish to always respond with the minimum level of detail. +\subsubsection{Table} The REST endpoint must also support a child resource for each table described in the TableSet document. The child resource must be named as it appears in the name of the corresponding child Table element. For @@ -345,8 +346,7 @@ \subsubsection{Tables} \begin{verbatim} GET http://example.net/srv/tables/ivoa.ObsCore \end{verbatim} - -would return a Table document describing the ivoa.ObsCore table in full +\noindent would return a Table document describing the ivoa.ObsCore table in full detail, starting: \begin{verbatim} @@ -355,6 +355,7 @@ \subsubsection{Tables} ... ... + \end{verbatim} The above \xmlel{vosi:table} document is the default response format; clients @@ -366,7 +367,7 @@ \subsubsection{User-managed Tables} of such tables and the authentication and authorization requirements for using this feature are an implementation detail that may vary from one service to another. At one extreme, users may be able to create tables anonymously and the table will persist for a short -perioid of time (days or weeks) before being removed. At the other extreme, users would +period of time (days or weeks) before being removed. At the other extreme, users would have to authenticate, have permission to create tables in a specific schema, and the tables would persist forever. @@ -377,24 +378,43 @@ \subsubsection{User-managed Tables} visible to and usable by other users (e.g. included in tables endpoint output and added to the \verb|tap_schema| of a TAP service). +The additional actions to allow users to manage tables are optional. The OpenAPI specification +says that a tables endpoint that does not support these actions must respond with an HTTP +405 status code; we expect that current services already respond this way. \todo{Do we need a +registry extension for VOSI-tables? just listing http verbs would be enough to avoid probing +for a 405 aka try and see if it works} + To create a new table: \begin{verbatim} PUT http://example.net/srv/tables/schema1.table1 \end{verbatim} -\noindent where the \verb|| payload can be either a VOSI-table or VOTable document. +\noindent where the \verb|| payload can be either a VOSI-table or VOTable document. For +a VOTable payload, the table may contain rows and those rows would be inserted into the created +table. To update table metadata: \begin{verbatim} POST http://example.net/srv/tables/schema1.table1 \end{verbatim} \noindent where only some of the table metadata can me modified (see below). In addition, if -the VOTable format is used for updating metadata, the VOTable must not contain any rows. +the VOTable format is used for updating metadata, the VOTable would not contain any rows (but +see below). To delete a table: \begin{verbatim} DELETE http://example.net/srv/tables/schema1.table1 \end{verbatim} +Some services may allow the caller to append additional rows to a table. This could be +implemented by accepting a table update that carries additional rows: +\begin{verbatim} +POST http://example.net/srv/tables/schema1.table1 +\end{verbatim} +\noindent where some metadata may be updated and rows in the input VOTable are appended +to the existing table. Other tabular data formats that are not sufficient for create may be +supported for appending rows: csv, tsv, fits, etc. \todo{Service should advertise the +list of acceptable formats} + \subsubsection{Mutable Table Metadata} Metadata that can be updated: \begin{itemize} @@ -402,14 +422,17 @@ \subsubsection{Mutable Table Metadata} \item column metadata that can be updated: utype, ucd, unit, description \end{itemize} -Column metadata where update would imply an structural change to the table (e.g. an SQL +Column metadata where update would imply a structural change to the table (e.g. an SQL alter table statement): \begin{itemize} \item column datatype, arraysize, xtype: alter column datatype? \item input table description has fewer columns: drop column? \item input table description has more columns: add column? +\item rename table +\item rename column(s) \end{itemize} -\noindent These are probably too fraught with pain in the details. +\noindent These are probably too fraught with pain in the details. \todo{Some CADC users have +asked for table and column renaming, which should be easy enough to implement} \subsection{Non-service metadata (non-normative)} diff --git a/openapi/vosi-std-responses.yaml b/openapi/vosi-std-responses.yaml index 040e498..853a6b6 100644 --- a/openapi/vosi-std-responses.yaml +++ b/openapi/vosi-std-responses.yaml @@ -40,3 +40,10 @@ not-implemented: text/plain: schema: type: string + +too-large: + description: the request content exceeds a server-side limitation on size + content: + text/plain: + schema: + type: string diff --git a/openapi/vosi-table.yaml b/openapi/vosi-table.yaml index 54551b4..cd1808b 100644 --- a/openapi/vosi-table.yaml +++ b/openapi/vosi-table.yaml @@ -52,6 +52,8 @@ post: $ref: ./vosi-std-responses.yaml#/not-found 405: $ref: ./vosi-std-responses.yaml#/not-implemented + 413: + $ref: ./vosi-std-responses.yaml#/too-large put: operationId: create-table tags: @@ -84,6 +86,8 @@ put: $ref: ./vosi-std-responses.yaml#/not-found 405: $ref: ./vosi-std-responses.yaml#/not-implemented + 413: + $ref: ./vosi-std-responses.yaml#/too-large delete: operationId: delete-table tags: From e79b959e4c599d557fa109570004b84c47f693d1 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Wed, 6 May 2026 14:16:27 -0700 Subject: [PATCH 4/5] fix example indentation --- openapi/vosi/vosi-table.yaml | 29 +++++++++++++---------------- openapi/vosi/vosi-tableset.yaml | 13 ++++++------- 2 files changed, 19 insertions(+), 23 deletions(-) diff --git a/openapi/vosi/vosi-table.yaml b/openapi/vosi/vosi-table.yaml index d78b3e0..820a365 100644 --- a/openapi/vosi/vosi-table.yaml +++ b/openapi/vosi/vosi-table.yaml @@ -137,12 +137,12 @@ components: content: text/xml: schema: - type: object - xml: - name: table - prefix: vosi - namespace: http://www.ivoa.net/xml/VOSITables/v1.0 - example: | + type: string + xml: + name: table + prefix: vosi + namespace: http://www.ivoa.net/xml/VOSITables/v1.0 + example: | recommended sort order when listing schemas int - + application/x-votable+xml: schema: - type: object - xml: - name: VOTABLE - namespace: http://www.ivoa.net/xml/VOTable/v1.3 - example: | + type: string + xml: + name: VOTABLE + namespace: http://www.ivoa.net/xml/VOTable/v1.3 + example: | - +
schema name for reference to tap_schema.schemas @@ -194,9 +194,6 @@ components: recommended sort order when listing schemas -
- - diff --git a/openapi/vosi/vosi-tableset.yaml b/openapi/vosi/vosi-tableset.yaml index be950cc..7a85064 100644 --- a/openapi/vosi/vosi-tableset.yaml +++ b/openapi/vosi/vosi-tableset.yaml @@ -29,12 +29,12 @@ components: content: text/xml: schema: - type: string - xml: - name: tableset - prefix: vosi - namespace: http://www.ivoa.net/xml/VOSITables/v1.0 - example: | + type: string + xml: + name: tableset + prefix: vosi + namespace: http://www.ivoa.net/xml/VOSITables/v1.0 + example: | description of foreign key columns in this tableset - ... From d16a62e3a39c4f59eb6acc6ce5fe73f218906459 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Wed, 6 May 2026 14:42:24 -0700 Subject: [PATCH 5/5] add x-vosi-owner output header --- openapi/vosi/vosi-table.yaml | 35 ++++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/openapi/vosi/vosi-table.yaml b/openapi/vosi/vosi-table.yaml index 820a365..b39dbfb 100644 --- a/openapi/vosi/vosi-table.yaml +++ b/openapi/vosi/vosi-table.yaml @@ -119,21 +119,26 @@ components: tableDoc: description: metadata for the specified schema or table headers: - x-vosi-anon-read: - description: flag indicating that the resource allows anonymous read - required: false - schema: - type: boolean - x-vosi-group-read: - description: a GMS group identifier indicating a group with read permission - required: false - schema: - type: string - x-vosi-group-write: - description: a GMS group identifier indicating a group with write permission - required: false - schema: - type: string + x-vosi-owner: + description: identifier for the owner of the schema or table + required: false + schema: + type: string + x-vosi-anon-read: + description: flag indicating that the resource allows anonymous read + required: false + schema: + type: boolean + x-vosi-group-read: + description: a GMS group identifier indicating a group with read permission + required: false + schema: + type: string + x-vosi-group-write: + description: a GMS group identifier indicating a group with write permission + required: false + schema: + type: string content: text/xml: schema: