21–30 of 40 posts
JSON Schema could get more traction if its homepage was oriented more towards users instead of implementors.
The metaschemas are useful but not strict enough. They don't set `additionalProperties: false`, which is great if you wanna extend the schema with your own properties, but it won't catch simple typos. For example, the following issues pass under the metaschema. {"foo": {"bar": { ... }}} # wrong {"foo": {"type": "object", "properties": {"bar": { ... }}}} # correct {"additional_properties": false} # wrong {"additionalP…
This is intentional because unknown keywords are permitted with JSON Schema 2020-12 and prior. We are changing this with the upcoming version, which means we'll be updating the meta-schema to enforce it as well.
Earlier quoted context omitted.
I used to believe that I was working with JSON schema through OpenAPI 3.0, but then I learned a hard lesson that it uses an “extended subset” of it. And what does that mean? It “means that some keywords are supported and some are not, some keywords have slightly different usage than in JSON Schema, and additional keywords are introduced.” [1]. Yes, that’s a bonkers way to say “this is not JSON schema although it look…
OpenAPI 3.1 replaced the not-a-superset-or-subset of JSON Schema with the actual JSON Schema (latest version) over five years ago. No one should be using 3.0.x anymore. And 3.2 came out a few months ago, containing lots of features that have been in high demand (support for arbitrary HTTP methods, full expression of multipart and streaming messages, etc).
Many users are stuck at 3.0 or even Swagger 2.0 because the libraries they use refuse to support recent versions. Also OpenAPI is still not a strict superset because things like `discriminator` are still missing in JSON schema.
Earlier quoted context omitted.
OpenAPI 3.1 replaced the not-a-superset-or-subset of JSON Schema with the actual JSON Schema (latest version) over five years ago. No one should be using 3.0.x anymore. And 3.2 came out a few months ago, containing lots of features that have been in high demand (support for arbitrary HTTP methods, full expression of multipart and streaming messages, etc).
> No one should be using 3.0.x anymore Many users are stuck at 3.0 or even Swagger 2.0 because the libraries they use refuse to support recent versions. Also OpenAPI is still not a strict superset because things like `discriminator` are still missing in JSON schema.
If you're building a brand new, multi-language, multi-platform system that uses advanced open-api features - you will get bitten by lack of support in 3.1 versions of tooling for features that already existed and work fine right now in 3.0 tool versions. Especially if you're using a schema-first workflow (which you should be). For example, $ref's to files across windows/linux/macos across multiple different language tools - java, .net, typescript, etc.
If you need (or just want) maximum compatibility across tools, platforms and languages - open-api 3.1 is still not viable, and isn't looking like it will be anytime soon.
However, we already had an XMLSpy license, so decided to just stick with designing XSDs in XMLSpy and then just translate that to JSON Schema.
If you make some small decisions, like value with attributes becomes an object, you can get a fairy decent subset of XSD to map 1:1 onto JSON Schema 2020-12.
As a nice side effect of writing the XSD to JSON Schema converter, it's trivial for us to support reading XMLs and convert that to JSON. Great for the customers who have programs that doesn't speak JSON.
I think the post is generally pretty good. There are some things that I would have stated differently. "Unfortunately, [the terms] leaked into the documentation that everyone reads" - We did this on purpose to align everyone's terms. It makes things so much easier when the people asking and answering questions are using the same language. "The official JSON Schema website has a validator you can try: https://www.json…
I'm not really sure why you'd say that OpenAPI isn't a JSON Schema document: there are published JSON Schema files on the official OpenAPI website. See for example:
One using the draft-04 of JSON schema: https://spec.openapis.org/oas/3.0/schema/2024-10-18.html One using the 2020-12 version of JSON schema: https://spec.openapis.org/oas/3.2/schema/2025-09-17.html
I think the post is generally pretty good. There are some things that I would have stated differently. "Unfortunately, [the terms] leaked into the documentation that everyone reads" - We did this on purpose to align everyone's terms. It makes things so much easier when the people asking and answering questions are using the same language. "The official JSON Schema website has a validator you can try: https://www.json…
author here: I'm not really sure why you'd say that OpenAPI isn't a JSON Schema document: there are published JSON Schema files on the official OpenAPI website. See for example: One using the draft-04 of JSON schema: https://spec.openapis.org/oas/3.0/schema/2024-10-18.html One using the 2020-12 version of JSON schema: https://spec.openapis.org/oas/3.2/schema/2025-09-17.html
OpenAPI descriptions are not themselves JSON Schema. They _use_ JSON Schema.
There _are_ JSON Schemas that describe OpenAPI documents as well, but that's just because OpenAPI can be described in JSON.
JSON schema was nice when it was simple. Now it feels like writing a validator is extremely complicated. IMO, the built-in vocabularies were enough, and keeping it simple would provide more value. JSON as a format didn't win because it supported binary number encoding or could be extended with custom data types -- but rather because it couldn't.
Good introduction, sad that it's needed. I've written hundreds of schemas and massive meta schemas and used most of the 2020-12 spec. I still struggle to navigate and use json-schema.org documentation to look up simple information. JSON Schema could get more traction if its homepage was oriented more towards users instead of implementors.