Re: [httpapi] Discussion about JSON payloads and code generation

[Darrel Miller <[e-mail]>]

Christoph,

From: Christoph Kappestein <[e-mail]>

Thank you for the feedback. I understand that it is not easy possible to change the schema specification but I had the hope that the OpenAPI spec will be in future versions more JSON schema independent. I.e. that a user could use XSD, JTD, Protobuf or any other specification to describe the request/response payload, also for payloads in the future which are not JSON. So that a user is not forced to use JSON schema and that an alternative could emerge.
There is a proposal for supporting an "Alternative Schema" https://github.com/OAI/OpenAPI-Specification/blob/master/proposals/001_Alternative%20Schema%20Proposal.md

Implementation feedback was that that the current proposal is too complex to implement, so we likely will be revisiting it once OpenAPI 3.1 is released.

A core editor from the JSON schema spec has already approached me regarding a vocabulary, but from my point of view I think that those vocabularies inherit many properties from JSON schema which are not ideal for code generation. In the spirit of "do one thing and do it well" we could have different specifications for specific use cases, which would be a much more flexible framework than forcing every schema to be a vocabulary. A generator could then support only specific schema types.

Speaking purely as an individual, I think extending JSON Schema would be a better first step.  Getting traction in this space is hard, and successfully mapping to the type systems of multiple platforms is a problem that people have been failing at for decades, no matter how focused the effort was.

Having said that.  I wonder if this working group would be the right place to create a specification that describes an extended set of primitive data types and corresponding text-based wire representations.  JSON Schema completely punts on anything beyond what JSON defines for type, and format is left as implementation dependent.

I could imagine this kind of standardization would be helpful for query parameter values, header values as well as a range of media types used as payloads.

I'm thinking of a single RFC that describes a set of serializations used in HTTP APIs. Things like date-time, times, durations, currency, coordinates, language identifiers, etc. It could also provide a standardized type identifier to use in complex type definition/validation specifications

I think it would be useful when writing specifications to be able to reference a single spec and say primitive values are serialized as per RFCXXXX.   Looking at the structured headers spec, they have done this work for a few core data types that are common in headers.  https://httpwg.org/http-extensions/draft-ietf-httpbis-header-structure.html#section-4.1.3.1

So, bringing this back to TypeSchema.  Do you think that it would be useful for TypeSchema if there existed a standardized rich set of primitive data types for HTTP APIs that were platform independent and optimized for wire representations?

I'm pretty sure the JSON Schema folks would be delighted if there were some well known values that could be used with format keyword.  The OpenAPI specification defines a few formats (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#data-types) and we continue to get requests for more, but I'm not convinced the OpenAPI specification is the right place to do that. OData defines a bunch of their own https://docs.oasis-open.org/odata/odata-csdl-json/v4.01/odata-csdl-json-v4.01.html#_Toc38466396

The feels like something that if properly scoped and standardized could make life easier for a bunch of different efforts.

Thoughts?

Darrel