[p3t] Draft documents demonstrating standards layout

[Dave Morris]

Hiya,

We don't need to do anything special to describe the schema in the 
OpenAPI specification.

This single OpenAPI document describes a common data model used by three 
serializations, JSON, YAML and XML.
https://github.com/ivoa/Calycopis-broker/blob/main/openapi/ivoa/openapi-0.8.yaml

This section links the responses for the different content types to the 
schema.
https://github.com/ivoa/Calycopis-broker/blob/971eaecd3a290e43bed297cfcf415c79de0c94e6/openapi/ivoa/openapi-0.8.yaml#L76-L85

All three serializations use the same schema for an OfferSetResponse.
https://github.com/ivoa/Calycopis-broker/blob/971eaecd3a290e43bed297cfcf415c79de0c94e6/openapi/ivoa/openapi-0.8.yaml#L1190-L1249

Literally, that is it.

The resulting web service can handle requests and responses in JSON, 
YAML and XML using the content-type and accepts headers to select which 
serialization to use.

The Java/Spring generated classes work straight out of the box, no 
modification needed.

The Python/FastAPI generated classes need a bit more work to support it 
but not a huge amount.

All of this is standard OpenAPI. We have not had to do anything special 
to support multiple content types and serialization formats.

Hope this helps,
-- Dave


On 2024-08-29 14:45, Paul Harrison wrote:
>> On 26 Aug 2024, at 06:18, Dave Morris via p3t <p3t at ivoa.net> wrote:
>> 
>> We should try to avoid referring to the overall goal as the 'JSON 
>> network protocol' - that is what P3T should be trying to avoid. If we 
>> bind too strongly to JSON we are in danger of repeating the mistakes 
>> of 20 years ago when we bound our standards to XML, WSDL and SOAP.
> 
> Near the start of these conversations, I tried to point out that the
> IVOA already has a standard way of describing the “schema” part of
> these interface definitions - i.e VO-DML - if the data models
> associated with a service are described in VO-DML, then in another 20
> years time when some other serialisation format is fashionable, then
> the VO-DML tooling can just be altered to emit the schema for that
> serialisation, without having to re-author the data model source, and
> obviously the more data models there are the more advantageous this
> is.