Skip to content

OpenAPI components for common DALI parameters #58

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
Oct 7, 2025
Merged

OpenAPI components for common DALI parameters #58

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
9f71e25
OpenAPI components for DALI query parameters
pdowler May 9, 2025
8e90d20
Merge branch 'main' into openapi
pdowler May 13, 2025
65ef838
add dali-upload openapi component
pdowler May 13, 2025
ce56b4d
add minimum value spec for maxrec param
pdowler May 20, 2025
8223a6b
tweak upload regex to fit current name rules
pdowler May 21, 2025
d78457a
add references to OpenAPI components in document
pdowler May 21, 2025
35c23d8
update descriptions
pdowler Jun 4, 2025
05c087e
tweak maxrec description
pdowler Jun 4, 2025
4051c90
Merge branch 'main' into openapi
pdowler Sep 19, 2025
6b112d5
Merge branch 'openapi' of https://github.com/pdowler/DALI into openapi
pdowler Sep 19, 2025
d3896dc
remove todo comment about openapi component files
pdowler Sep 19, 2025
d7df0b6
update WD timestamp, include openapi in package
pdowler Sep 19, 2025
591f7fa
Merge branch 'main' into openapi
pdowler Sep 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion DALI.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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}
Expand Down
4 changes: 2 additions & 2 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand Down
2 changes: 1 addition & 1 deletion ivoatex
Open in desktop
Submodule ivoatex updated 12 files
+17 −5 Makefile
+1 −1 Makefile.template
+4 −3 archdiag-full.xml
+66 −0 docrepo.bib
+2 −2 fetch_from_ads.py
+1 −0 github_workflow_build.yml.template
+11 −4 github_workflow_preview.yml.template
+12 −1 ivoa.cls
+27 −3 regressiontest/run-regression.py
+2 −2 stdrec-template.xml
+13 −2 tthdefs.tex
+89 −0 update-stdrec.py
9 changes: 9 additions & 0 deletions openapi/dali-maxrec.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
5 changes: 5 additions & 0 deletions openapi/dali-responseformat.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
name: RESPONSEFORMAT
in: query
description: select output table format
schema:
type: string
8 changes: 8 additions & 0 deletions openapi/dali-upload.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pattern: might also be useful here to enforce some simple regex for the comma separation.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, minimal pattern added (I did not try to handle the complexity of the location part of that param). The openapi linter I use thought it was OK, but swagger doesn't render anything so it's a little hard to verify and my regex-fu doesn't extend to ECMA-script so I hope those predefined character classes are standard.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did a quick check with regex101.com and it seems okay to me. \w covers [a-zA-Z0-9_], but not - as a character, if that's acceptable.

I agree with not tackling the location path.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think \w is roughly correct for valid table names... although it does not capture the fact that the name must start with an letter. I should fix that.

That regex101.com site is great - thnx for that pointer!

pattern: '^[a-zA-Z]\w*,\S+$'