[p3t] OpenAPI validators

[Molinaro, Marco]

Hi, fwd of an email from Joshua,
lost in mailman mazes

    Marco

Il giorno lun 24 nov 2025 alle ore 13:50 Paul Harrison via p3t <p3t at ivoa.net>
ha scritto:

> 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.
>
>
>
>
>
>
> --
> p3t mailing list
> p3t at ivoa.net
> http://mail.ivoa.net/mailman/listinfo/p3t
>


-- 
Marco Molinaro
INAF - Istituto Nazionale di AstroFisica
Osservatorio Astronomico di Trieste
email marco.molinaro at inaf.it
tel. [+39] 333 33 20 564 [also Telegram]
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.ivoa.net/pipermail/stdproc/attachments/20251124/87b1a3d6/attachment-0001.htm>