From 9f71e25f2097afcd0a9e1734d86889ea8cef952b Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Fri, 9 May 2025 13:28:17 -0700 Subject: [PATCH 1/9] OpenAPI components for DALI query parameters --- openapi/dali-maxrec.yaml | 6 ++++++ openapi/dali-responseformat.yaml | 5 +++++ 2 files changed, 11 insertions(+) create mode 100644 openapi/dali-maxrec.yaml create mode 100644 openapi/dali-responseformat.yaml diff --git a/openapi/dali-maxrec.yaml b/openapi/dali-maxrec.yaml new file mode 100644 index 0000000..9260433 --- /dev/null +++ b/openapi/dali-maxrec.yaml @@ -0,0 +1,6 @@ +name: MAXREC +in: query +description: request a specific limit on number of rows to return +schema: + type: integer + format: int64 diff --git a/openapi/dali-responseformat.yaml b/openapi/dali-responseformat.yaml new file mode 100644 index 0000000..202eee4 --- /dev/null +++ b/openapi/dali-responseformat.yaml @@ -0,0 +1,5 @@ +name: RESPONSEFORMAT +in: query +description: select output table format +schema: + type: string From 65ef838d689b598f5a10508f73d5e985d967fd60 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Tue, 13 May 2025 10:26:58 -0700 Subject: [PATCH 2/9] add dali-upload openapi component --- openapi/dali-upload.yaml | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 openapi/dali-upload.yaml diff --git a/openapi/dali-upload.yaml b/openapi/dali-upload.yaml new file mode 100644 index 0000000..415518b --- /dev/null +++ b/openapi/dali-upload.yaml @@ -0,0 +1,7 @@ +name: UPLOAD +in: query +description: | + specify comma-separated name,location pair for a temporary table to be + uploaded and used in the request +schema: + type: string From ce56b4d0f9e5f4ff9e383554b1764acc171769c8 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Tue, 20 May 2025 12:24:13 -0700 Subject: [PATCH 3/9] add minimum value spec for maxrec param add simplistic {table name},{location} regex pattern for upload param --- openapi/dali-maxrec.yaml | 2 ++ openapi/dali-upload.yaml | 3 +++ 2 files changed, 5 insertions(+) diff --git a/openapi/dali-maxrec.yaml b/openapi/dali-maxrec.yaml index 9260433..954c925 100644 --- a/openapi/dali-maxrec.yaml +++ b/openapi/dali-maxrec.yaml @@ -4,3 +4,5 @@ description: request a specific limit on number of rows to return schema: type: integer format: int64 + minimum: 0 + exclusiveMinimum: false diff --git a/openapi/dali-upload.yaml b/openapi/dali-upload.yaml index 415518b..d747843 100644 --- a/openapi/dali-upload.yaml +++ b/openapi/dali-upload.yaml @@ -5,3 +5,6 @@ description: | uploaded and used in the request schema: type: string + # {table name},{location} + # pattern is {1+ word characters},{1+ non-whitespace characters} + pattern: '^\w+,\S+$' From 8223a6b34cc0d940c2e672d502b1f09fe1de971c Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Wed, 21 May 2025 08:41:52 -0700 Subject: [PATCH 4/9] tweak upload regex to fit current name rules --- openapi/dali-upload.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi/dali-upload.yaml b/openapi/dali-upload.yaml index d747843..2a64158 100644 --- a/openapi/dali-upload.yaml +++ b/openapi/dali-upload.yaml @@ -7,4 +7,4 @@ schema: type: string # {table name},{location} # pattern is {1+ word characters},{1+ non-whitespace characters} - pattern: '^\w+,\S+$' + pattern: '^[a-zA-Z]\w*,\S+$' From d78457ae895f56611faf876e68d9a1366647cff0 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Wed, 21 May 2025 08:59:34 -0700 Subject: [PATCH 5/9] add references to OpenAPI components in document --- DALI.tex | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/DALI.tex b/DALI.tex index b9e1011..5686537 100644 --- a/DALI.tex +++ b/DALI.tex @@ -1080,7 +1080,9 @@ \section{Parameters} \label{sec:parameters} A DAL job is defined by a set of parameter-value pairs. Some of these parameters have a standard meaning and are defined here, but most are defined by the -service specification or another related standard. +service specification or another related standard. Where indicated below, the +specification for individual parameters is provided as an OpenAPI component that +can be included in a concrete service specification. \subsection{Case Sensitivity} Parameter names are not case sensitive; a DAL service must treat @@ -1144,6 +1146,9 @@ \subsubsection{VERSION} \subsubsection{RESPONSEFORMAT} \label{sec:RESPONSEFORMAT} +OpenAPI component: dali-responseformat.yaml \todo{How to reference or include these +in the document in a way that works when they are large and more elaborate?} + The RESPONSEFORMAT parameter is used so the client can specify the format of the response (e.g. the output of the job). For DALI-sync requests, this is the content-type of the response. For DALI-async requests, this is the content-type @@ -1214,6 +1219,8 @@ \subsubsection{RESPONSEFORMAT} \subsubsection{MAXREC} \label{sec:MAXREC} +OpenAPI component: dali-maxrec.yaml + For resources performing discovery (querying for an arbitrary number of records), the resource must accept a MAXREC parameter specifying the maximum number of records to be returned. If MAXREC is not specified in a request, the @@ -1235,6 +1242,8 @@ \subsubsection{MAXREC} \subsubsection{UPLOAD} \label{sec:UPLOAD} +OpenAPI component: dali-upload.yaml + The UPLOAD parameter is used to reference read-only external resources (typically files) via their URI, to be uploaded for use as input resources to the query. The value of the UPLOAD parameter is a resource name-URI pair. For @@ -1616,6 +1625,7 @@ \subsection{PR-DALI-1.2} \item changed VOSI-capability so it is only required for registered services \item clarified use of VOTable serialisation for numbers and boolean \item clarified use of VOTable datatype and arraysize when used with xtype +\item add OpenAPI components for maxrec, responseformat, and upload params \end{itemize} \subsection{PR-DALI-1.1-20170412} From 35c23d8483946a40109f6c915142c0084f60bcb3 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Wed, 4 Jun 2025 15:57:20 -0700 Subject: [PATCH 6/9] update descriptions --- openapi/dali-maxrec.yaml | 3 ++- openapi/dali-upload.yaml | 6 ++---- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/openapi/dali-maxrec.yaml b/openapi/dali-maxrec.yaml index 954c925..39068c6 100644 --- a/openapi/dali-maxrec.yaml +++ b/openapi/dali-maxrec.yaml @@ -1,6 +1,7 @@ name: MAXREC in: query -description: request a specific limit on number of rows to return +description: | + request a specific limit on number of rows to return schema: type: integer format: int64 diff --git a/openapi/dali-upload.yaml b/openapi/dali-upload.yaml index 2a64158..ef9f018 100644 --- a/openapi/dali-upload.yaml +++ b/openapi/dali-upload.yaml @@ -1,10 +1,8 @@ name: UPLOAD in: query description: | - specify comma-separated name,location pair for a temporary table to be - uploaded and used in the request + specify a comma-separated name,location pair for a temporary + resource to be uploaded and used in the request schema: type: string - # {table name},{location} - # pattern is {1+ word characters},{1+ non-whitespace characters} pattern: '^[a-zA-Z]\w*,\S+$' From 05c087e74c7b1e291d345771d5ceda8ff9c917e9 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Wed, 4 Jun 2025 15:59:22 -0700 Subject: [PATCH 7/9] tweak maxrec description --- openapi/dali-maxrec.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi/dali-maxrec.yaml b/openapi/dali-maxrec.yaml index 39068c6..42d5ac7 100644 --- a/openapi/dali-maxrec.yaml +++ b/openapi/dali-maxrec.yaml @@ -1,7 +1,7 @@ name: MAXREC in: query description: | - request a specific limit on number of rows to return + request a specific limit on number of records to return schema: type: integer format: int64 From d3896dceabd9cbece9c09ca704491c68a2a28a79 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Fri, 19 Sep 2025 10:14:13 -0700 Subject: [PATCH 8/9] remove todo comment about openapi component files --- DALI.tex | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/DALI.tex b/DALI.tex index 6739ba0..f6bfa18 100644 --- a/DALI.tex +++ b/DALI.tex @@ -1149,8 +1149,7 @@ \subsubsection{VERSION} \subsubsection{RESPONSEFORMAT} \label{sec:RESPONSEFORMAT} -OpenAPI component: dali-responseformat.yaml \todo{How to reference or include these -in the document in a way that works when they are large and more elaborate?} +OpenAPI component: dali-responseformat.yaml The RESPONSEFORMAT parameter is used so the client can specify the format of the response (e.g. the output of the job). For DALI-sync requests, this is the From d7df0b66a67a46cb8525efb76b63a407ae3fb3f3 Mon Sep 17 00:00:00 2001 From: Patrick Dowler Date: Fri, 19 Sep 2025 10:30:20 -0700 Subject: [PATCH 9/9] update WD timestamp, include openapi in package --- Makefile | 4 ++-- ivoatex | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index cbaacb4..61e4554 100644 --- a/Makefile +++ b/Makefile @@ -9,7 +9,7 @@ DOCNAME = DALI DOCVERSION = 1.2 # Publication date, ISO format; update manually for "releases" -DOCDATE = 2023-07-12 +DOCDATE = 2025-09-19 # What is it you're writing: NOTE, WD, PR, or REC DOCTYPE = WD @@ -25,7 +25,7 @@ FIGURES = role_diagram.svg VECTORFIGURES = # Additional files to distribute (e.g., CSS, schema files, examples...) -AUX_FILES = +AUX_FILES = openapi -include ivoatex/Makefile diff --git a/ivoatex b/ivoatex index c7f0041..04d5819 160000 --- a/ivoatex +++ b/ivoatex @@ -1 +1 @@ -Subproject commit c7f00410483602c76aa7efbf09e57b6cebfb9613 +Subproject commit 04d5819ee835ed7a2f40e1faf757394d0ae9a4d6