<div dir="ltr"><div dir="ltr"><div class="gmail_default" style="font-family:monospace">Hi, fwd of an email from Joshua,<br></div></div><div><div class="gmail_default" style="font-family:monospace">lost in mailman mazes</div></div><div class="gmail_default" style="font-family:monospace"><br></div><div class="gmail_default" style="font-family:monospace"> Marco</div><br><div class="gmail_quote gmail_quote_container"><div dir="ltr" class="gmail_attr">Il giorno lun 24 nov 2025 alle ore 13:50 Paul Harrison via p3t <<a href="mailto:p3t@ivoa.net">p3t@ivoa.net</a>> ha scritto:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Hi,<br>
<br>
at the interop at the splinter session about UWS and OpenAPI <a href="https://yopad.eu/p/dal-splinter-interop-nov-2025" rel="noreferrer" target="_blank">https://yopad.eu/p/dal-splinter-interop-nov-2025</a><br>
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<br>
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<br>
<br>
In searching for tools, an “obvious” place to look is <a href="https://tools.openapis.org/categories/description-validators.html" rel="noreferrer" target="_blank">https://tools.openapis.org/categories/description-validators.html</a> - 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 <a href="https://openapi.tools/#description-validators" rel="noreferrer" target="_blank">https://openapi.tools/#description-validators</a> for which there is only one “winner” <a href="https://github.com/speakeasy-api/openapi" rel="noreferrer" target="_blank">https://github.com/speakeasy-api/openapi</a> - so I decided to do some experiments.<br>
<br>
The most comprehensive use of OpenAPI so far that I could find in IVOA related work is <a href="https://github.com/ivoa/Calycopis-schema" rel="noreferrer" target="_blank">https://github.com/ivoa/Calycopis-schema</a>, so I decided to do some experiments.<br>
<br>
% openapi spec validate Calycopis-broker.yaml <br>
Validating OpenAPI document: Calycopis-broker.yaml<br>
✅ OpenAPI document is valid - 0 errors<br>
<br>
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<br>
<br>
% openapi spec bundle Calycopis-broker.yaml bundled.yaml<br>
Processing OpenAPI document: Calycopis-broker.yaml<br>
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<br>
Usage:<br>
openapi spec bundle [input-file] [output-file] [flags]<br>
<br>
Flags:<br>
-h, --help help for bundle<br>
--naming string Naming strategy for bundled components (counter|filepath) (default "filepath")<br>
-w, --write Write bundled document back to input file<br>
<br>
Global Flags:<br>
-v, --verbose verbose output<br>
<br>
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<br>
<br>
<br>
Oh dear - despite declaring the file valid, the bundle has not worked - hence my call for some guidance.<br>
<br>
<br>
Paul.<br>
<br>
<br>
<br>
<br>
<br>
<br>
-- <br>
p3t mailing list<br>
<a href="mailto:p3t@ivoa.net" target="_blank">p3t@ivoa.net</a><br>
<a href="http://mail.ivoa.net/mailman/listinfo/p3t" rel="noreferrer" target="_blank">http://mail.ivoa.net/mailman/listinfo/p3t</a><br>
</blockquote></div><div><br clear="all"></div><div><br></div><span class="gmail_signature_prefix">-- </span><br><div dir="ltr" class="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div dir="ltr"><div><font face="monospace">Marco Molinaro</font></div><div><font face="monospace">INAF - Istituto Nazionale di AstroFisica</font></div><div><font face="monospace">Osservatorio Astronomico di Trieste</font></div><div><font face="monospace">email <a href="mailto:marco.molinaro@inaf.it" target="_blank">marco.molinaro@inaf.it</a></font></div><div><span style="font-family:monospace">tel. [+39] 333 33 20 564 [also Telegram]</span><br></div></div></div></div></div></div></div>