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

[Jason Desrosiers <[e-mail]>]

Hi Christoph,

Even if/when OpenAPI allows you to use something other than JSON Schema, I
think you still have a serious problem. The problem with "do one thing and
do it well" in this case is that you end up with a lot of duplication. I
don't want to have to maintain separate and almost identical sets of
schemas for code generation, validation, documentation, etc. Ideally, you
would start with a simple and flexible core that other specifications can
build off of to progressively enhance the core. That's what we're trying to
enable with JSON Schema vocabularies.

I believe it's possible to define a JSON Schema vocabulary for code
generation that progressively enhances standard JSON Schema so only one
schema needs to be maintained. I say that with all due humility and
willingness to wrong. I have never attempted to implement a JSON Schema
based code generator, but I have written other tooling with this kind of
thing in mind. In our Github Issue, I'll share more details about how I
think the problems you identified could be solved without breaking JSON
Schema validation.

Full disclosure: I am a member of the JSON Schema core team, so I should be
considered even more biased than Darrel :-). But, even if you decide not to
align with JSON Schema, I'd be happy to share lessons we've learned from
developing JSON Schema that might apply to TypeSchema as well.

Jason Desrosiers

On Sun, Jan 17, 2021 at 3:46 AM Christoph Kappestein <
[e-mail]> wrote:

> 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
>>
>>
>> --
> httpapi mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/httpapi
>