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

[Christoph Kappestein <[e-mail]>]

Hi Darrel,

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.

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. If I remember
correctly the RAML specification solved this also in a similar way. This
approach would be also great for the OpenAPI since they do not have to
force a different schema spec but the users can decide which is the optimal
solution.

Thanks to the link of the API report, I was not aware of it and it looks
really interesting. Regarding the OpenAPI spec, for me it would be really
interesting to know whether there is such a plan to make the schema
description part more JSON schema independent?

best regards
Christoph


Am Sa., 16. Jan. 2021 um 23:12 Uhr schrieb Darrel Miller <
[e-mail]>:

> Hi Christoph,
>
> *From:* httpapi <[e-mail]> on behalf of Christoph
> Kappestein <[e-mail]>
>
> I would like to gauge whether there is some interest in discussing ways to
> describe JSON payloads with a focus on code generation on this WG. Also it
> would be interesting to gather feedback from other developers who have
> experiences in this space.
>
>
> As an editor of the OpenAPI spec, that relies heavily on JSON Schema,
> consider my perspective to be heavily biased here. But I do agree
> wholeheartedly that JSON Schema has challenges when it comes to describing
> types for code generation.  However, I would be reluctant to go down a path
> of defining a new specification for describing types.
>
> The recent Postman developer survey https://www.postman.com/state-of-api/ found
> that in their 13,000 respondents, 75% of them claimed to be users of JSON
> Schema.  Convincing developers to move to a different format is going to
> require a compelling alternative.
>
> What would be awesome to see is if a community could form around creating
> a new JSON Schema vocabulary that targets type description.  JSON Schema
> itself is now defined by a set of vocabularies, one of which is the
> validation vocabulary.  I know the JSON Schema core team have been looking
> for someone to spearhead this effort.
> https://github.com/json-schema-org/json-schema-vocabularies
>
> By taking this approach, the existing JSON Schema specifications and
> artifacts can be leveraged, and the new type definition keywords could be
> used alongside the validation keywords.
>
> Darrel
>
>
>