If you've ever tried to generate code from a JSON Schema and watched your tooling quietly give up halfway through, you're not alone. It's a frustration that Clemens Vasters, Principal Architect for Messaging and Real-Time Intelligence Services at Microsoft, knows intimately — and it's the frustration that led him to create something new.
On the recent episode of the Nafitko Capabilities podcast, Clemens introduced JSON Structure, a new schema specification designed to do what JSON Schema was never quite built for: serve as a true data definition language.
The Problem with the Status Quo
JSON Schema has become the de facto standard for describing JSON documents. It's everywhere — baked into OpenAPI, used across countless validation pipelines, and familiar to virtually every developer working with JSON. But familiarity doesn't mean fitness for purpose.
As Clemens explained, JSON Schema is fundamentally a validation language. It's good at answering the question "does this document match this shape?" But when you need to go further — generating code across multiple programming languages, modeling type inheritance, or driving real-time data pipelines — the cracks start to show quickly.
The composition constructs like allOf, anyOf, and oneOf seem powerful on paper, but in practice they create structures that no code generator can reliably translate into compilable output. Inheritance patterns rely on unwritten conventions rather than formal rules. And the type system, constrained by JSON's own limited primitives, can't natively express everyday data types like datetimes or decimals without leaning on string formats as a workaround.
Clemens didn't arrive at this conclusion lightly. His team at Microsoft explored the landscape thoroughly, including Apache Avro, which brings its own strengths — tight scoping, namespacing, extensibility — but also its own set of limitations. Avro's type system is bound to its binary serializer, it can't model complex type relationships like inheritance, and its JSON serialization model is, in Clemens' words, "terrifying." He even tried contributing improvements to the Avro project, but found little appetite for the kind of sweeping changes that would be needed.
Enter JSON Structure
Rather than fighting uphill battles with existing specs, Clemens started fresh — but deliberately. JSON Structure keeps the familiar shape that developers already know from JSON Schema. If you've ever written a type: object with a properties map, you'll feel right at home. The goal was to preserve what works and strip away what doesn't.
What got cut? The unconstrained $ref mechanism that lets you drag in fragments from anywhere. The conditional composition constructs that produce schemas no code generator can handle. The ambiguity that has led to an ecosystem where every tool breaks at a different, unpredictable point.
What got added? A proper type system. Datetimes, decimals, and other data types that real-world applications depend on daily are first-class citizens. The spec also introduces well-defined semantics for type relationships, so inheritance and reuse aren't just conventions — they're part of the language.
The core design principle is that JSON Structure should function as a "hinge" — a central format that can faithfully capture the semantics of other schema languages. If your data is described in XML Schema, you should be able to translate that into JSON Structure without losing information or fidelity, and then translate it onward to whatever target you need. No silent data loss, no semantic drift.
Why This Matters Now
Clemens made a point that resonated throughout the conversation: metadata matters more than ever in the age of AI. When LLMs are writing code, interpreting data, and answering questions, the quality of the context you provide directly shapes the quality of the output. A schema language that can carry rich semantic information — descriptions, type relationships, structural constraints — isn't just a developer convenience anymore. It's infrastructure for how AI systems understand data.
This isn't theoretical. At Microsoft, the practical driver is Fabric's real-time data pipelines. Data flows in from publishers, moves through messaging-based pipelines, and ultimately needs to land in database tables or data lakes with proper column-and-row structures. That translation from document to table requires a schema language that can describe data precisely enough for query engines — and eventually for Copilot — to understand. JSON Schema's validation-oriented approach simply wasn't cutting it.
The Tooling Is Already Here
A spec without tooling is just a document. Clemens clearly understands this, and he built the ecosystem alongside the specification rather than treating it as an afterthought.
The JSON Structure SDK is available today across eight languages — C#, C++, Rust, Python, TypeScript, JavaScript, Perl, and more — distributed through their respective package managers. The SDK handles the two most fundamental operations: validating schemas and validating documents against schemas. It understands both the core spec and its extensions.
Then there's Avrotize, a Python-based tool that handles schema translation and code generation. Feed it a JSON Structure schema and it produces not just code files, but complete, compilable projects — organized, documented, with README files and inline comments drawn from your schema's descriptions. The generated objects are self-serializing, understanding how to read and write conformant JSON documents. In C# (currently the most capable target), they can also handle CBOR, MessagePack, XML, and Protobuf, effectively turning a single generated class into a translation layer across serialization formats.
And here's the part that speaks to the current moment: Clemens noted that building the SDK would have taken six months two years ago. With AI coding assistants and a clear, well-written spec, it took two weeks. The spec's clarity didn't just help human developers — it made the AI tools dramatically more effective at generating correct implementations.
What's Next
This podcast episode covered the foundations — the origin story, the core spec, and the tooling landscape. A follow-up episode will dive into governance, extensibility, and Clemens' broader vision for where JSON Structure fits in the evolving standards landscape.
For developers, platform architects, and anyone who has ever wrestled with the gap between what JSON Schema promises and what it delivers, JSON Structure is worth a serious look.
JSON Structure Website: https://json-structure.org/
