OpenAPI validators

[Paul Harrison]

Hi,

at the interop at the splinter session about UWS and OpenAPI https://yopad.eu/p/dal-splinter-interop-nov-2025
I asked about OpenAPI validation tooling and CI, and did not really get an answer - I feel that until we have an agreed-on set
of tools that we are going to use then there is not much point in producing the OpenAPI definitions - I will illustrate what I mean below, but the main point being is that the OpenAPI spec is large and there are potentially some corners that we do not want to use because they are poorly supported in the tooling - This was certainly the case when we started to use XML Schema as a data model/interface definition language, and we banned ourselves from using Substitution groups for instance as they were poorly supported by tooling - we also made several other stylistic choices in how to represent concepts - e.g. there are mainly ComplexType definitions rather than Element definitions at the top level

In searching for tools, an “obvious” place to look is https://tools.openapis.org/categories/description-validators.html - there are a lot of entries (71 in the description validation section) - not a good sign to me - no obvious “winners” (and probably a lot of 80% “solutions”). However, one filter that might indicate a commitment to producing a solid implementation is if they support the “latest” version (3.1 on this listing - though 3.2 is the recently published latest version in Sept 2025) - This reduces the number of possibilities down to 15, still rather too many to make a choice though - so I thought who is actually supporting 3.2 - and I found this list https://openapi.tools/#description-validators for which there is only one “winner” https://github.com/speakeasy-api/openapi - so I decided to do some experiments.

The most comprehensive use of OpenAPI so far that I could find in IVOA related work is https://github.com/ivoa/Calycopis-schema, so I decided to do some experiments.

% openapi spec validate Calycopis-broker.yaml   
Validating OpenAPI document: Calycopis-broker.yaml
✅ OpenAPI document is valid - 0 errors

Then, because my past experience of OpenAPI has been that most tools work best if everything is in a single document as the $ref does not work the way that most people naively expect, I decided to try the bundle functionality

% openapi spec bundle Calycopis-broker.yaml bundled.yaml
Processing OpenAPI document: Calycopis-broker.yaml
Error: failed to bundle document: failed to bundle item at /paths/~1offersets/post/requestBody/content/application~1json/schema: failed to bundle nested references in /Users/pharriso/Work/ivoa/Calycopis-schema/schema/components.yaml#/components/schemas/OfferSetRequest: failed to bundle item at /allOf/0: failed to resolve external schema reference /Users/pharriso/Work/ivoa/Calycopis-schema/schema/ExecutionComponents: open /Users/pharriso/Work/ivoa/Calycopis-schema/schema/ExecutionComponents: no such file or directory
Usage:
  openapi spec bundle [input-file] [output-file] [flags]

Flags:
  -h, --help            help for bundle
      --naming string   Naming strategy for bundled components (counter|filepath) (default "filepath")
  -w, --write           Write bundled document back to input file

Global Flags:
  -v, --verbose   verbose output

Error: failed to bundle document: failed to bundle item at /paths/~1offersets/post/requestBody/content/application~1json/schema: failed to bundle nested references in /Users/pharriso/Work/ivoa/Calycopis-schema/schema/components.yaml#/components/schemas/OfferSetRequest: failed to bundle item at /allOf/0: failed to resolve external schema reference /Users/pharriso/Work/ivoa/Calycopis-schema/schema/ExecutionComponents: open /Users/pharriso/Work/ivoa/Calycopis-schema/schema/ExecutionComponents: no such file or directory


Oh dear - despite declaring the file valid, the bundle has not worked - hence my call for some guidance.


Paul.