<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body style="overflow-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;">
<div dir="auto" style="overflow-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;">
<div><br>
<blockquote type="cite">
<div>On 30 Aug 2024, at 15:19, Kim Gillies <kgillies@tmt.org> wrote:</div>
</blockquote>
<br>
<blockquote type="cite">
<div><span style="font-family: revert; font-size: revert; font-style: revert; font-variant-caps: revert; letter-spacing: revert; orphans: revert; text-indent: revert; text-transform: revert; white-space: revert; widows: revert; word-spacing: revert; -webkit-text-decorations-in-effect: revert; -webkit-text-fill-color: revert; -webkit-text-stroke-color: revert; -webkit-text-stroke-width: revert; background-color: rgb(208, 216, 220); text-decoration: revert;">Hi
All,</span></div>
<div>
<div style="caret-color: rgb(0, 0, 0); font-family: Helvetica; font-size: 15px; font-style: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none;">
<br>
</div>
<div style="caret-color: rgb(0, 0, 0); font-family: Helvetica; font-size: 15px; font-style: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none;">
There is “Smithy”, which is a <a href="https://urldefense.com/v3/__https://smithy.io/2.0/index.html__;!!PDiH4ENfjr2_Jw!C8KVmhtjHHOtHWVc6jVIK_X0IH2Jo1vI3jK0WQqnL7yxUAjled2P4rIhjtyIEOlVD8G0EO3RvOGUDrtvcbsWC_TZeg$">https://smithy.io/2.0/index.html [smithy.io]</a>,
which is similar to what is being discussed. I do not have direct experience with it, and maybe it was discussed and rejected, but it is open source, mature, and supports many programming languages, etc. The following is from: <a href="https://urldefense.com/v3/__https://smithy.io/2.0/guides/model-translations/converting-to-openapi.html__;!!PDiH4ENfjr2_Jw!C8KVmhtjHHOtHWVc6jVIK_X0IH2Jo1vI3jK0WQqnL7yxUAjled2P4rIhjtyIEOlVD8G0EO3RvOGUDrtvcbtYFmyymQ$">https://smithy.io/2.0/guides/model-translations/converting-to-openapi.html
[smithy.io]</a></div>
<div style="caret-color: rgb(0, 0, 0); font-family: Helvetica; font-size: 15px; font-style: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none;">
<br>
</div>
<div style="caret-color: rgb(0, 0, 0); font-family: Helvetica; font-size: 15px; font-style: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none;">
Kim</div>
<div style="caret-color: rgb(0, 0, 0); font-family: Helvetica; font-size: 15px; font-style: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none;">
<br>
</div>
</div>
</blockquote>
<div><br>
</div>
<div><br>
</div>
<div>I think that Smithy looks pretty good- indeed it was amongst the alternatives suggested by the author of the <span style="text-wrap-mode: wrap; background-color: rgb(255, 255, 255);">oxlip </span>interface definition DSL that I had mentioned when I was
trying to advocate having something other than openAPI and the interface definition source. <a href="http://mail.ivoa.net/pipermail/p3t/2024-February/000031.html">http://mail.ivoa.net/pipermail/p3t/2024-February/000031.html</a></div>
<div>
<div><br>
</div>
<div>It is the sort of “fully featured, and flexible” interface definition languages that Russ was first talking about..<br>
<div><br>
</div>
<div>The only problems are; </div>
<div><br>
</div>
<div>* The IVOA does not “own” it, so long-term is subject to the same sort of arguments against it that started this sub-thread looking for alternatives to OpenAPI</div>
<div>* I am not entirely sure how to fit VO-DML (which we already have) into the picture with an external definition system like that. (It is easier to see how to use VO-DML to generate the schema part of OpenAPI)</div>
<div><br>
</div>
<div>Although back in February, I was not advocating writing our own interface DSL, I am now more inclined to think that it might the the best route as the argument is that we do not need something quite so sophisticated/flexible as a fully featured interface
language if we have some IVOA conventions “built-in” as assumptions in our interface definition language.<br id="lineBreakAtBeginningOfMessage">
</div>
</div>
<div><br>
</div>
</div>
<div>Paul</div>
<br>
<blockquote type="cite">
<div>
<div style="caret-color: rgb(0, 0, 0); font-family: Helvetica; font-size: 15px; font-style: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none;">
<h2>Differences between Smithy and OpenAPI</h2>
<span style="font-family: -webkit-standard; font-size: medium;">Smithy and OpenAPI take very different approaches to modeling APIs. Smithy is </span><em>protocol agnostic</em><span style="font-family: -webkit-standard; font-size: medium;">, which means it focuses
on the interfaces and abstractions that are provided to end-users rather than how the data is sent over the wire. While Smithy can define RESTful APIs, RPC APIs, pub/sub APIs, and more, OpenAPI </span><em>only</em><span style="font-family: -webkit-standard; font-size: medium;"> defines
RESTful APIs. Both approaches have their own strengths and weaknesses. For example, while Smithy can define a much broader set of functionality, services, and client behaviors, it requires abstractions that have their own underlying complexity. OpenAPI is
more permissive in the kinds of services it can describe, making it easier to adapt to existing web services, but at the same time making it easier to author APIs that provide a poor customer experience when using clients in strongly-typed languages.</span><br id="lineBreakAtBeginningOfMessage">
<div><br>
<blockquote type="cite">
<div>On Aug 30, 2024, at 4:04 AM, Paul Harrison via p3t <<a href="mailto:p3t@ivoa.net">p3t@ivoa.net</a>> wrote:</div>
<br class="Apple-interchange-newline">
<div>
<div style="overflow-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;">
<br id="lineBreakAtBeginningOfMessage">
<div><br>
<blockquote type="cite">
<div>On 29 Aug 2024, at 18:59, Russ Allbery <eagle@eyrie.org> wrote:</div>
<br class="Apple-interchange-newline">
<div>
<pre style="caret-color: rgb(0, 0, 0); font-size: 15px; font-style: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none; font-family: sans-serif; white-space: pre-wrap; overflow-wrap: break-word;">My larger concern is that I am dubious that OpenAPI will prove to be
resilient against future changes to prevailing protocols and definition
languages any more than XML schemas were. gRPC does not use OpenAPI, for
example; it uses protobuf as its API definition language. I fear that
OpenAPI is a specification language for this one particular moment in
time, and in the future people will use something else, similar to how XML
schemas used to be common and now, although they still exist, they're less
widely used.
That said, designing a specification language is an immense amount of
work, and I don't want us to write our own either. We should use OpenAPI
today because that's what people use today. But I would like to have some
sort of semantic language specific to the IVOA, ideally one with a minimum
amount of additional formality so that it's easy to read and easy to
write, that nails down all the things that OpenAPI may leave ambiguous and
provides enough additional information that we can adapt our data types to
some new language that comes along later.
</pre>
<br class="Apple-interchange-newline">
</div>
</blockquote>
</div>
<br>
<div>Designing a general purpose specification language is a lot of work - however, all we *need* is a language to describe</div>
<div>interfaces that follow IVOA patterns, so that it does not have to be that extensive. So for example when the </div>
<div>hypothetical IVOA interface language says for example “return error” it can be transformed into the IVOA pattern in OpenAPI that</div>
<div>expresses the way to return an error. So that a lot of the “detail” that makes OpenAPI complex is removed by having conventions.</div>
<div><br>
</div>
<div>Paul.</div>
<div><br>
</div>
</div>
--<span class="Apple-converted-space"> </span><br>
p3t mailing list<br>
p3t@ivoa.net<br>
<a href="https://urldefense.com/v3/__http://mail.ivoa.net/mailman/listinfo/p3t__;!!PDiH4ENfjr2_Jw!C8KVmhtjHHOtHWVc6jVIK_X0IH2Jo1vI3jK0WQqnL7yxUAjled2P4rIhjtyIEOlVD8G0EO3RvOGUDrtvcbuhP8tH-Q$">http://mail.ivoa.net/mailman/listinfo/p3t [mail.ivoa.net]</a></div>
</blockquote>
</div>
</div>
</div>
</blockquote>
</div>
<br>
</div>
</body>
</html>