OpenAPI spec for TAP-1.1 compatible API for WD-TAP-1.2

[pdowler]

This describes a TAP-1.1 compatible API modulo changes in the upstream dependencies:

• no VOSI availability going forward
• enhanced VOSI tables endpoint

The openapi dir holds the components that TAP specifies.

The openapi.yaml (example) refers to components laid out in a sub-directory like

openapi/{std}/{component}

which is not the openapi here. This openapi dir here is the source from some parts but not external standards with their own openapi (dali and vosi). Some components that describe UWS pattern are currently included in vosi.

---

Since no openapi components are fully standardised yet, there is a script that uses rsync to pull in dali and vosi components from local clones of this ivoa-std repos.

The openapi-linter script runs a docker image with a suite of OpenAPI tools; this has been used to find and fix a range of errors and warnings. The tools can also assemble one large openapi document from the components if necessary (not for the standard, but for using other tools that don't like external $ref).

[pdowler]

recent update: I have decided to write some of the UWS OpenAPI components and include them here. UWS is a self-proclaimed "pattern" that services can follow and while it is incomplete these components do enable the TAP spec to use the UWS pattern.

Whether we can/do complete the UWS part is TBD. Whether we keep it here or move it to the UWS standard is TBD.

[pdowler]

It turns out that the uws components for job and job-phase need to contain unique operationId values and distinct tags, so in a spec like WD-TAP-1.2 with two UWS endpoints:

• TAP-async defined here
• VOSI table operations defined in VOSI

one must provide two different copies of essentially the same components.

In VOSI ivoa-std/VOSI#9 I have included the reusable UWS components (final location TBD) and now sync those in to validate, so there are now $ref to those new things... of course, it is currently quite complicated to manage and validate when two standards are evolving together and one includes the other.