[p3t] 'contract first' and OpenAPI

[Paul Harrison]

Hi,

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.

This reminds me of some of the discussions around using XML schema to describe the registry data models – e.g. http://mail.ivoa.net/pipermail/registry/2003-November/003168.html . 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.

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.

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 https://www.oxlip-lang.org/doc/related.html – as there are lots of repetitive parts of the OpenAPI spec that can be expressed more concisely – see https://oxlip-lang.github.io/oxlip-playground/

Paul.



-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.ivoa.net/pipermail/p3t/attachments/20240229/2d59f138/attachment.htm>