JSON Schema Demystified: Dialects, Vocabularies and Metaschemas

Re:JSON Schema Demystified: Dialects, Vocabularies and Metas... by boricj on Friday November 28, 2025 @01:50PM (#46081552)

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.

[ Parent | on HN ]

Re:JSON Schema Demystified: Dialects, Vocabularies and Metas... by rollulus on Friday November 28, 2025 @02:57PM (#46082190)

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...

[ Parent | on HN ]

Re:JSON Schema Demystified: Dialects, Vocabularies and Metas... by ether_at_cpan on Friday November 28, 2025 @03:58PM (#46082714)

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).

[ Parent | on HN ]

Re:JSON Schema Demystified: Dialects, Vocabularies and Metas... by silverwind on Friday November 28, 2025 @06:47PM (#46083886)

> 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.

[ Parent | on HN ]

Re:JSON Schema Demystified: Dialects, Vocabularies and Metas... by Shorn on Friday November 28, 2025 @08:05PM (#46084353)

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.

[ Parent | on HN ]

Re:JSON Schema Demystified: Dialects, Vocabularies and Metas... by ether_at_cpan on Wednesday December 03, 2025 @02:45PM (#46139060)

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.

[ Parent | on HN ]