diff --git a/DALI.tex b/DALI.tex index 5af9c5f..32149cf 100644 --- a/DALI.tex +++ b/DALI.tex @@ -1094,7 +1094,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 @@ -1158,6 +1160,8 @@ \subsubsection{VERSION} \subsubsection{RESPONSEFORMAT} \label{sec:RESPONSEFORMAT} +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 content-type of the response. For DALI-async requests, this is the content-type @@ -1228,6 +1232,8 @@ \subsubsection{RESPONSEFORMAT} \subsubsection{MAXREC} \label{sec:MAXREC} +OpenAPI component: dali-maxrec.yaml + For services performing discovery (querying for an arbitrary number of records), the query endpoints must accept MAXREC parameters specifying the maximum number of records to be returned. If MAXREC is not specified in a request, the @@ -1249,6 +1255,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 data to the query. The value of the UPLOAD parameter is a name-URI pair. For @@ -1632,6 +1640,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 \item changing terminology: What so far was mostly ``web resource'' is now ``endpoint''. \end{itemize} 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 diff --git a/openapi/dali-maxrec.yaml b/openapi/dali-maxrec.yaml new file mode 100644 index 0000000..42d5ac7 --- /dev/null +++ b/openapi/dali-maxrec.yaml @@ -0,0 +1,9 @@ +name: MAXREC +in: query +description: | + request a specific limit on number of records to return +schema: + type: integer + format: int64 + minimum: 0 + exclusiveMinimum: false 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 diff --git a/openapi/dali-upload.yaml b/openapi/dali-upload.yaml new file mode 100644 index 0000000..ef9f018 --- /dev/null +++ b/openapi/dali-upload.yaml @@ -0,0 +1,8 @@ +name: UPLOAD +in: query +description: | + specify a comma-separated name,location pair for a temporary + resource to be uploaded and used in the request +schema: + type: string + pattern: '^[a-zA-Z]\w*,\S+$'