JSON Schema Demystified: Dialects, Vocabularies and Metaschemas | Hacker News Reader

JSON Schema Demystified: Dialects, Vocabularies and Metaschemas

iankduncan.com

89 pointsnavigate831037 comments

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.jsonschemavalidator.net/" - Would have been better to point to the actual official JSON Schema website's tools page (https://json-schema.org/tools) that lists many online validators.

There are some interesting conceptions of OpenAPI in here as well. Specifically, OpenAPI isn't a JSON Schema document. It's its own kind of document that has JSON Schemas embedded in it.

Still, it's a decent high-level summary. If you're interested in diving a bit deeper, definitely come visit us in Slack (https://json-schema.org/slack).

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

JSON Schema editor (and fairly involved with OpenAPI as well) here:

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.

This and schema support for JSON will always be an ill fitting afterthought. If you really, really need the strictness and correctness (and you most probably don't) XML has you covered.

To me schemas are absolutely essential for high quality software, I have a hard time imagining a project where I wouldn't want to use them.

I also often make heavy use of schema based editors to auto-generate UI.

Perhaps I'd feel differently if I ever had to write a validator myself, but they seem to exist in all the popular languages as is.

I'm currently rebuilding my implementation JsonSchema.Net from the ground up. I completed 95% of it in a weekend, and it already supports all the published versions Draft 6 and later, including the more complex keywords. Granted, I have a particularly deep understanding of the spec already, but it doesn't feel overly burdensome.

Right now JSON tech has become more complicated than old-school XML tech.

I'm working with JSON schema through OpenAPI specifications at work. I think it's a bit of a double-edged sword: it's very nice to write things in, but it's a little bit too flexible when it comes to writing tools that don't involve validating JSON documents.

I'm in the process of writing a toolchain of sorts, with the OpenAPI document as an abstract syntax tree that goes through various passes (parsing, validation, aggregation, analysis, transformation, serialization...). My immediate use-case is generating C++ type/class headers from component schemas, with the intent to eventually auto-generate as much code as I can from a single source of truth specification (like binding these generated C++ data classes with serializers/deserializers, generating a command-line interface...).

JSON schema is so flexible that I have several passes to normalize/canonicalize the component schemas of an OpenAPI document into something that I can then project into the C++ language. It works, but this was significantly trickier to accomplish than I anticipated.

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 looks similar enough to deceive you”. This word game and engineering choice is so bizarre that it’s almost funny.

[1]: https://swagger.io/docs/specification/v3_0/data-models/keywo...

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.

This.

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.

The solution here is to demand support for the most recent specification version from your tooling vendors. We (the OpenAPI TSC) sometimes hear from vendors "we're not moving quickly to support the latest version because our users aren't asking for it." So it's a catch-22 unless you make your needs known.

I think JSON Schema made the same fallacy as eg. OWL did: The assumption of an open world. 99% percent of the time you want to express "This message should look like this and everything else is wrong". Instead JSON-S went the way to make everything possible at the price of rendering the default unwieldy.

There's a way to express that though: by adding `"unevaluatedProperties": false` underneath your properties list.

I like JSON schema, but I haven't found any good tools to designing them. Or at least not a few years ago when I was looking.

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.

Yes, I've been searching for a long time for a good solution to allow non-coding people to visually design JSON Schemas. The closest thing I found is the schema editor in the amazing Stoplight service, but that is sadly not open source.

Heck, I'm a coder and I get lost when just dealing with the raw JSON Schema.

It's not a problem for a dozen properties, but we have several hundreds in our larger schemas, even accounting for them being fairly normalized w.r.t. types. And five or more levels of nesting turns into an effective ten plus levels in the schema.

One underutilised feature of JSON Schema is referencing external schemas and reusing them in multiple places, rather than copying them over and over again. The main hurdle to a better use of this feature is the lack of a good standard for schema repositories; I've been working on addressing this, but it's difficult to find the time. :/

> One underutilised feature of JSON Schema is referencing external schemas and reusing them in multiple places

Yeah, though while it does make each subschema somewhat more readable and contained, you still don't get a good overview. If you're reading the spec for a given object, do you don't easily see where it's being used in the schema.

For now I've just supplied the JSON Schema as a self-contained thing, and deferred other parties to the XSD to get an overview. The self-contained makes it trivial to load into a validator and such.

So while it helps for knowing what to fill into that exact object, it doesn't help for getting a feel for the overall schema. This is where the visual view of tools such as XMLSpy really helps.

> lack of a good standard for schema repositories

Interesting, do you have something public to show? For our large ones I feel they'd be entirely custom anyway, but perhaps I can see standard sub-schemas useful for other tasks. Would be interesting to have a look.

> you still don't get a good overview

True, when focusing only on the schemas as code. But good tooling could provide links and similar.

> do you have something public to show

Just a very early PoC [0]. I'm slowly working my way through a very long to-do list of improvements, but I'm lacking time and resources to do it more efficiently.

[0] https://schematalog.com/

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
    {"additionalProperties": false} # correct

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.

Will the new meta-schema still have any mechanism for things like the special keywords that editor UIs often need?

Excellent!

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.

The JSON Schema community would LOVE some more detailed feedback on this. We would ideally like to do that in our slack or via a GitHub Discussion. Can you reach either of those OK? Please ping/mention me, same username.

JSON schema is nice overall* but every software only supports ancient versions like draft 4

*even if I would prefer more transformation/conversion features that would bring it to more more a parser rather than only a validator

Not really true? There are lots of validators supporting the most recent version: https://json-schema.org/tools?query=&sortBy=name&sortOrder=a...

I might be wrong but that list is mostly libraries I think?

I agree that it is easy to implement a recent version in your own code, what I meant is that a lot of the tools/software you might want to use JSON Schema with (eg mongodb validation) only support old versions

The deeper principle here: "stop lying about where truth lives."

I've been exploring how this generalizes beyond side effects. Every React state library creates a JavaScript copy of state that must sync with the DOM. This is the original sin. Two truths = lies.

The solution isn't better syncing, it's refusing to duplicate. The DOM is already a perfectly good state container. All you have to do is read it.

Releasing a paper (DATAOS) and React implementation (stateless, <1KB) soon. It's the architecture behind multicardz (hyper-performing kanban on steroids, rows AND columns, 1M+ cards, sub second searches, perfect lighthouse scores, zero state sync bugs). Because there's no state to sync.

Sounds interesting, do you have any links to these projects? Could not find multicardz when searching

I am dark at the moment.

I am doing final testing, packaging, integrating strip, etc. My target was before end of month. If I work hard I just might make it.

I'm releasing a bunch of things at once: 1. multicardz.com 2. a paper on using DOM as single source of user state dataos.software 3. an OSS repo of hyper performant implementation of that for React (stateless.software) 4. an OSS repo that might best be described as Tailwind for frontend behavior. (genX.software)

they are all somewhat interconnected

https://news.ycombinator.com/item?id=45812308

Yep!

Highly recommended

Reply on news.ycombinator.com