<html xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Generator" content="Microsoft Word 15 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
@font-face
{font-family:Aptos;
panose-1:2 11 0 4 2 2 2 2 2 4;}
@font-face
{font-family:"Apple Color Emoji";
panose-1:0 0 0 0 0 0 0 0 0 0;}
@font-face
{font-family:Consolas;
panose-1:2 11 6 9 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
font-size:12.0pt;
font-family:"Aptos",sans-serif;}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
pre
{mso-style-priority:99;
mso-style-link:"HTML Preformatted Char";
margin:0in;
margin-bottom:.0001pt;
font-size:10.0pt;
font-family:"Courier New";}
span.HTMLPreformattedChar
{mso-style-name:"HTML Preformatted Char";
mso-style-priority:99;
mso-style-link:"HTML Preformatted";
font-family:"Consolas",serif;}
span.EmailStyle20
{mso-style-type:personal-reply;
font-family:"Calibri",sans-serif;
color:windowtext;}
.MsoChpDefault
{mso-style-type:export-only;
font-size:10.0pt;
mso-ligatures:none;}
@page WordSection1
{size:8.5in 11.0in;
margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
{page:WordSection1;}
--></style>
</head>
<body lang="EN-US" link="blue" vlink="purple" style="word-wrap:break-word">
<div class="WordSection1">
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif">Hi Gregory,
<br>
<br>
I replied to Paul that afternoon, but it didn’t seem to have bounced off the mailing list correctly. I’m copy-pasting the message here so hopefully everyone gets it. CC’ing also the original p3t mailing list<br>
<br>
---<br>
<br>
</span><span style="color:black">Hi Paul,<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:black"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="color:black">I think you’ve raised some very good points regarding the value of identifying a handful of tools the IVOA can informally recommend, or at least highlight, as useful for editors working with OpenAPI documents.
As more editors gain experience with OpenAPI in their respective environments, I expect we’ll naturally build up a shared understanding of “this works well if you’re on Ubuntu with editor X” or “this validator integrates nicely with workflow Y.” We’re already
seeing the beginnings of that with the work Pat and Dave have been doing.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:black"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="color:black">Where I’m more hesitant is in the IVOA formally prescribing a specific toolchain, or proscribing others, at the standards process level. In practice that tends to create more problems than it solves: tools evolve
or fall behind, people work in environments where some tools simply don't work, and we would risk taking on responsibility for maintaining or endorsing tooling that can quickly become outdated. I'm tempted to think of the TeX documents that are published,
we don't care so much which of the many TeX distributions folks use (and there are many <a href="https://www.tug.org/interest.html#free" title="https://www.tug.org/interest.html#free">https://www.tug.org/interest.html#free</a>): what matters is that the output
compiles and renders correctly, less so what editor the author uses to create it.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:black"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="color:black">You also noted that many of the tools you surveyed claim support for 3.2. That’s encouraging, but given that 3.2 was only published in September, I’d expect the ecosystem to be in a transitional state for a while.
Our uptake curve for even minor IVOA spec updates tends to be much slower than two months, so I’m not surprised we’re seeing uneven support right now. I don't think the IVOA is really any different in this regard. Consider how many now unsupported, or one-off,
tools are floating around the IVOA ecosystem for working with our various standards. <o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:black"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="color:black">Regarding the Calycopis/Execution Broker example: If I recall, Dave mentioned during Interop that he’s using non-standard pre-processing and assembly tooling in that repository. The YAML files there are no doubt
intermediate inputs, and not the final OpenAPI document he plans to publish as part of the standard. Given that, I wouldn’t draw strong conclusions from the bundling issue you hit. My assumption is that the final published document will be compiled in some
form (perphaps still in separate files with 'proper/working' $ref links) that can be validated by a broad set of OpenAPI tools, regardless of how the pieces are managed internally in his repo.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:black"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="color:black">One area where I do think we might find consensus is on the validation step itself. It may be reasonable for the IVOA to agree on a single validator, perhaps integrated via GitHub Actions or another CI mechanism,
that defines the bar for what “valid for publication” means. Editors could work however they prefer internally, but the document they submit would need to pass that agreed-upon validator in CI. It would also be much easier for us at some further date to say,
'This validator has reached end-of-life, we're moving on to this one' for a single tool rather than a suite of them. We’d also want to ensure that reviewers are comfortable with the technical aspects, such as suggesting when an editor should $ref a shared
component (e.g., MAXREC) rather than redefining it yet again.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:black"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="color:black">I think Pat and Dave will no doubt have some good feedback on what they've found as reliable sets of tooling.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:black"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="color:black">Kindly,<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:black">Joshua<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri",sans-serif"><o:p> </o:p></span></p>
<div style="border:none;border-top:solid #B5C4DF 1.0pt;padding:3.0pt 0in 0in 0in">
<p class="MsoNormal"><b><span style="font-family:"Calibri",sans-serif;color:black">From:
</span></b><span style="font-family:"Calibri",sans-serif;color:black">Grégory Mantelet <gregory.mantelet@astro.unistra.fr><br>
<b>Date: </b>Thursday, December 11, 2025 at 4:44 AM<br>
<b>To: </b>Joshua Fraustro <jfraustro@stsci.edu>, Patrick Dowler <pdowler.cadc@gmail.com>, Russ Allbery <eagle@eyrie.org>, Paul Harrison <paul.harrison@manchester.ac.uk><br>
<b>Cc: </b>"Molinaro, Marco" <marco.molinaro@inaf.it><br>
<b>Subject: </b>Fwd: [p3t] OpenAPI validators<o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div style="border:solid #9C6500 1.0pt;padding:2.0pt 2.0pt 2.0pt 2.0pt">
<p class="MsoNormal" align="center" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;text-align:center;line-height:12.0pt;background:#FFEB9C">
<span style="font-size:10.0pt;color:black">External Email - Use Caution</span><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">Hi Joshua, Pat, Russ,<br>
<br>
I feel I am not competent to answer to the request from Paul, as I have not yet<br>
any practical experience with OpenAPI.<br>
<br>
Does any of you has some guidance for him about how to use OpenAPI in practice<br>
(especially with the $ref)?<br>
<br>
Thank you for your help,<br>
Grégory M.<br>
<br>
PS: @Paul, sorry to answer so late...I was very busy since the interop meeting.<o:p></o:p></p>
<div>
<p class="MsoNormal"><br>
<br>
-------- Forwarded Message -------- <o:p></o:p></p>
<table class="MsoNormalTable" border="0" cellspacing="0" cellpadding="0">
<tbody>
<tr>
<td nowrap="" valign="top" style="padding:0in 0in 0in 0in">
<p class="MsoNormal" align="right" style="text-align:right"><b>Subject: <o:p></o:p></b></p>
</td>
<td style="padding:0in 0in 0in 0in">
<p class="MsoNormal">[p3t] OpenAPI validators<o:p></o:p></p>
</td>
</tr>
<tr>
<td nowrap="" valign="top" style="padding:0in 0in 0in 0in">
<p class="MsoNormal" align="right" style="text-align:right"><b>Date: <o:p></o:p></b></p>
</td>
<td style="padding:0in 0in 0in 0in">
<p class="MsoNormal">Mon, 24 Nov 2025 12:50:34 +0000<o:p></o:p></p>
</td>
</tr>
<tr>
<td nowrap="" valign="top" style="padding:0in 0in 0in 0in">
<p class="MsoNormal" align="right" style="text-align:right"><b>From: <o:p></o:p></b></p>
</td>
<td style="padding:0in 0in 0in 0in">
<p class="MsoNormal">Paul Harrison via p3t <a href="mailto:p3t@ivoa.net"><p3t@ivoa.net></a><o:p></o:p></p>
</td>
</tr>
<tr>
<td nowrap="" valign="top" style="padding:0in 0in 0in 0in">
<p class="MsoNormal" align="right" style="text-align:right"><b>Reply-To: <o:p></o:p></b></p>
</td>
<td style="padding:0in 0in 0in 0in">
<p class="MsoNormal">Paul Harrison <a href="mailto:paul.harrison@manchester.ac.uk">
<paul.harrison@manchester.ac.uk></a><o:p></o:p></p>
</td>
</tr>
<tr>
<td nowrap="" valign="top" style="padding:0in 0in 0in 0in">
<p class="MsoNormal" align="right" style="text-align:right"><b>To: <o:p></o:p></b></p>
</td>
<td style="padding:0in 0in 0in 0in">
<p class="MsoNormal">Russ Allbery via p3t <a href="mailto:P3t@ivoa.net"><P3t@ivoa.net></a><o:p></o:p></p>
</td>
</tr>
<tr>
<td nowrap="" valign="top" style="padding:0in 0in 0in 0in">
<p class="MsoNormal" align="right" style="text-align:right"><b>CC: <o:p></o:p></b></p>
</td>
<td style="padding:0in 0in 0in 0in">
<p class="MsoNormal"><a href="mailto:stdproc@ivoa.net">stdproc@ivoa.net</a><o:p></o:p></p>
</td>
</tr>
</tbody>
</table>
<p class="MsoNormal" style="margin-bottom:12.0pt"><br>
<br>
Hi,<br>
<br>
at the interop at the splinter session about UWS and OpenAPI <a href="https://urldefense.com/v3/__https:/yopad.eu/p/dal-splinter-interop-nov-2025__;!!CrWY41Z8OgsX0i-WU-0LuAcUu2o!0RdE6rMwVAV4vhplXXv90T3fvSQyDwu1V0OdhXrUBhuhCxf_5g_Fz_LwPh2rskQT25BkXoyQOL6ia_ehruCluox2HVuRbIbpqHRk$">
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://urldefense.com/v3/__https:/tools.openapis.org/categories/description-validators.html__;!!CrWY41Z8OgsX0i-WU-0LuAcUu2o!0RdE6rMwVAV4vhplXXv90T3fvSQyDwu1V0OdhXrUBhuhCxf_5g_Fz_LwPh2rskQT25BkXoyQOL6ia_ehruCluox2HVuRbFH7L0gU$">
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://urldefense.com/v3/__https:/openapi.tools/*description-validators__;Iw!!CrWY41Z8OgsX0i-WU-0LuAcUu2o!0RdE6rMwVAV4vhplXXv90T3fvSQyDwu1V0OdhXrUBhuhCxf_5g_Fz_LwPh2rskQT25BkXoyQOL6ia_ehruCluox2HVuRbF7bRXAy$">
https://openapi.tools/#description-validators</a> for which there is only one “winner”
<a href="https://urldefense.com/v3/__https:/github.com/speakeasy-api/openapi__;!!CrWY41Z8OgsX0i-WU-0LuAcUu2o!0RdE6rMwVAV4vhplXXv90T3fvSQyDwu1V0OdhXrUBhuhCxf_5g_Fz_LwPh2rskQT25BkXoyQOL6ia_ehruCluox2HVuRbNl2FcKU$">
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://urldefense.com/v3/__https:/github.com/ivoa/Calycopis-schema__;!!CrWY41Z8OgsX0i-WU-0LuAcUu2o!0RdE6rMwVAV4vhplXXv90T3fvSQyDwu1V0OdhXrUBhuhCxf_5g_Fz_LwPh2rskQT25BkXoyQOL6ia_ehruCluox2HVuRbPmHKVtp$">
https://github.com/ivoa/Calycopis-schema</a>, so I decided to do some experiments.<br>
<br>
% openapi spec validate Calycopis-broker.yaml Validating OpenAPI document: Calycopis-broker.yaml<br>
<span style="font-family:"Apple Color Emoji"">✅</span> 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>
<o:p></o:p></p>
<pre>-- <o:p></o:p></pre>
<pre>p3t mailing list<o:p></o:p></pre>
<pre><a href="mailto:p3t@ivoa.net">p3t@ivoa.net</a><o:p></o:p></pre>
<pre><a href="https://urldefense.com/v3/__http:/mail.ivoa.net/mailman/listinfo/p3t__;!!CrWY41Z8OgsX0i-WU-0LuAcUu2o!0RdE6rMwVAV4vhplXXv90T3fvSQyDwu1V0OdhXrUBhuhCxf_5g_Fz_LwPh2rskQT25BkXoyQOL6ia_ehruCluox2HVuRbF6OK7X7$">http://mail.ivoa.net/mailman/listinfo/p3t</a><o:p></o:p></pre>
<pre><o:p> </o:p></pre>
<pre><o:p> </o:p></pre>
<pre><o:p> </o:p></pre>
<pre><o:p> </o:p></pre>
</div>
</div>
</div>
</body>
</html>