If you've ever tried to do serious code generation from JSON Schema — or used OpenAPI tooling on a complex schema and watched it give up mid-object — you've felt the same frustration that drove Clemens Vasters to build something new.
Clemens is a principal architect at Microsoft working on Fabric, the messaging and real-time intelligence platform. He needs schemas that work as data definition languages: things you can generate code from, land in database columns, feed to LLMs with enough fidelity that the LLM can reason about the data correctly. JSON Schema is designed to validate documents. Those are not the same job.
I talked with him twice — in February and again this week — and came away with a clear picture of what JSON Structure is and why it matters. Here's the short version.
What's wrong with JSON Schema
JSON Schema's compositional constructs (anyOf, allOf, oneOf) are expressive but carry no semantic guarantees. The convention that you represent inheritance as an allOf with a base type is just a convention — no rule, no standard, no requirement that code generators interpret it consistently. Every tool hits a different wall at a different time.
The type system is anchored to JSON's native types: strings, numbers, booleans, arrays, objects. That's not enough for real data modeling. Datetimes, decimals, durations — you're working around the type system, not with it.
Dollar-ref can appear anywhere in a document and point to arbitrary external locations. Authentication, caching, relative vs. absolute paths — all of that is undefined. The spec hands you the construct and leaves every operational detail to you.
What JSON Structure fixes
Type system: A richer set of types that maps clearly to database columns and programming language primitives. Not "string with format." Actual types.
References: Dollar-ref is only legal in a defined reusable-types section. External references use an $import mechanism — import the whole document, optionally namespace it, then reference from the import. Two steps, no ambiguity.
Extensibility: The $uses clause declares exactly which extension specs a document depends on, expressed in the same language as everything else. Not a foreign vocabulary mechanism bolted on from outside.
Readability: The shape is familiar if you know JSON Schema. The spec is written so a normal developer can read it and understand it, not just metadata specialists.
The tooling
- SDK in 8 languages (C#, C++, Rust, Python, Perl, TypeScript, JavaScript) — validates schemas and validates documents against schemas — on all the standard package managers
- Avrotize code generator produces organized, compile-ready projects in C#, Java, Rust, Go, C++, TypeScript, JavaScript from a JSON Structure schema. Generated classes are self-serializing and understand conformant JSON. The C# implementation also handles CBOR, MessagePack, and XML.
- Spec is in the IETF as a draft — neutral, stable, no lock-in
Why it matters for AI
Clemens made the point directly: most Kafka/messaging systems work today because the publisher and consumer teams are in the same room. They operate on convention and out-of-band communication. An AI agent consuming a data stream doesn't have that room. It gets the schema and nothing else. Schema quality directly determines what the agent can do correctly.
Richer, more precise schemas are not a nice-to-have in the AI era. They're the difference between an agent that reasons correctly about your data and one that hallucinates field meanings.
The relationship to OpenAPI and AsyncAPI
The baseline use case looks exactly the same as JSON Schema — define request/response objects in an HTTP API. Clemens intentionally kept the surface familiar. If OpenAPI adopted JSON Structure, it would get a better type system and better-defined compositional semantics. That's an invitation, not a demand.
Start at jsonstructure.org. The spec, SDKs, and examples are all there. Community is still small enough to get direct answers from the author.
At Naftiko we're actively working through where JSON Structure sits alongside JSON Schema in our capabilities framework. More on that soon.
Top comments (0)