<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=Windows-1252">
<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:Aptos;
panose-1:2 11 0 4 2 2 2 2 2 4;}
@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:0cm;
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:0cm;
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;}
.MsoChpDefault
{mso-style-type:export-only;
font-size:10.0pt;
mso-ligatures:none;}
@page WordSection1
{size:612.0pt 792.0pt;
margin:72.0pt 72.0pt 72.0pt 72.0pt;}
div.WordSection1
{page:WordSection1;}
--></style>
</head>
<body lang="EN-GB" link="blue" vlink="purple" style="word-wrap:break-word">
<div class="WordSection1">
<p class="MsoNormal"><span style="font-size:11.0pt;mso-fareast-language:EN-US">Hi,<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;mso-fareast-language:EN-US"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;mso-fareast-language:EN-US">It is of course entirely possible to create an OpenAPI description of the current UWS 1.1 REST API with no changes to the API at all– but I think that this group is wanting to do
more and update the API. However, this does illustrate the point that just “producing an OpenAPI description” is not a sufficient goal in itself – there will be a desired “style” of the description.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;mso-fareast-language:EN-US"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;mso-fareast-language:EN-US">This reminds me of some of the discussions around using XML schema to describe the registry data models – e.g.
<a href="http://mail.ivoa.net/pipermail/registry/2003-November/003168.html">http://mail.ivoa.net/pipermail/registry/2003-November/003168.html</a> . It turned out that there were parts of XML schema that were poorly supported by various tooling – however, there
was a “style” of registry schema – i.e. heavily using “types” rather than “elements” that was much better supported. At the time there was an agreement in the registry WG to follow the “types” style – however, we did not have any formal linters for that style,
we just relied on people testing their schema against various code generation tools to ensure that they did sensible things with instance documents.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;mso-fareast-language:EN-US"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;mso-fareast-language:EN-US">Subsequently, in the slightly more general field of data models the IVOA came up with VO-DML as a description language for data models that did not depend on the particular capabilities
of XML schema, UML or indeed JSON schema. I am suggesting that we use VO-DML as the source for the “schema” part of the OpenAPI definition. Incidentally, JSON “language” is less expressive than XML schema in that there is no concept built-in of a “identifiers”
(XML-ID) or the ability to add a type property to a node to make explicit what that type is – there has to be a “convention” adopted to express these concepts – another reason not to use JSON as the source.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;mso-fareast-language:EN-US"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;mso-fareast-language:EN-US">I am not suggesting that the p3t try to create a VO-DML equivalent for the source code for the “interface” part of the OpenAPI spec, but we could adopt someone else’s DSL – e.g.oxlip
and see the comparison with some other approaches <a href="https://www.oxlip-lang.org/doc/related.html">
https://www.oxlip-lang.org/doc/related.html</a> – as there are lots of repetitive parts of the OpenAPI spec that can be expressed more concisely – see
<a href="https://oxlip-lang.github.io/oxlip-playground/">https://oxlip-lang.github.io/oxlip-playground/</a><o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;mso-fareast-language:EN-US"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;mso-fareast-language:EN-US">Paul.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;mso-fareast-language:EN-US"><o:p> </o:p></span></p>
<div id="mail-editor-reference-message-container">
<div>
<pre><span style="font-size:12.0pt;font-family:"Arial",sans-serif"><o:p> </o:p></span></pre>
</div>
</div>
</div>
</body>
</html>