Merge pull request #58 from pdowler/openapi

OpenAPI components for common DALI parameters

Author: pdowler

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}

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
 

ivoatex

@@ -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

openapi/dali-maxrec.yaml

@@ -0,0 +1,5 @@
+name: RESPONSEFORMAT
+in: query
+description: select output table format
+schema:
+    type: string

openapi/dali-responseformat.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+$'