Using JSON Schema to Document, Test, and Debug APIs

Re:Using JSON Schema to Document, Test, and Debug APIs by acemarke on Sunday April 14, 2019 @05:30PM (#19661820)

Some searching turns up some articles on incompatibilities between OpenAPI and JSON Schema [0] [1], and it's not immediately clear if they fit together well at this point.

We've got some JSON Schema APIs in our services already and are using libs like the Python `json-schema` package to do validation with those. I also briefly experimented with Quicktype [2] to generate some TS types as a proof-of-concept.

We're getting ready to do a pretty big rework of a lot of our services, and I'm interested in any info folks can provide on pros and cons of using OpenAPI vs JSON Schema for API definitions, and tooling around request validation and TS interface / client generation.

[0] https://philsturgeon.uk/api/2018/04/13/openapi-and-json-sche...

[1] https://github.com/OAI/OpenAPI-Specification/issues/1532

[2] https://quicktype.io/typescript/

[ Parent | on HN ]

Re:Using JSON Schema to Document, Test, and Debug APIs by yxhuvud on Monday April 15, 2019 @04:53AM (#19664027)

The choice to fork[1] the schema standard instead of simply using it as is or with purely additive extensions) is so incredibly damaging. Yes, I get that it makes it a lot simpler to generate code for languages that have bad and static type systems. Meanwhile, the standard is still not powerful enough to describe everything JSON:API thinks is best practice due to not having any way to describe nested properties in queries.

[1] They don't want to call it a fork, but when they invent totally new extensions to support things that already is solved by parts of the standard that they don't want to support, then it is a fork.

[ Parent | on HN ]

Re:Using JSON Schema to Document, Test, and Debug APIs by handrews on Tuesday April 16, 2019 @01:27PM (#19675512)

Hi- I'm one of the main editors of the JSON Schema specification, and we and the OpenAPI Technical Steering Committee are actively working together to re-converge the specifications.

OpenAPI 3 was developed while JSON Schema progress was stalled due to the prior editors leaving and a new group of us (eventually) picking it up.

OpenAPI 3.1 will most likely include a keyword to allow using standard JSON Schema as an alternative to their customized syntax, and hopefully we can achieve full integration on OpenAPI 4. There are also some other ideas being explored for improved compatibility in 3.x.

Standards work is hard, but the relationship between the OpenAPI TSC and the JSON Schema editors is quite healthy and we are making good progress.

[ Parent | on HN ]