Connect JSON Schema

Your JSON Schema Answers One Question. You Keep Asking It Four.

The review comment that starts the trouble is always polite. *"Quick question — is this `customer_id` the same one the warehouse calls `customer_key`?"* The pull request adds two properties to a JSON Schema file. The author is fairly sure the answer is yes. Nobody can prove it from what is on the screen, because what is on the screen is a validator, and validators do not carry that kind of knowledge. The reviewer approves. The question stays open, and the next person to ask it will be an on-call engineer at an inconvenient hour.

The Week a Schema Change Stopped Being a Project

Add one property. That is the entire request: sales needs `preferredChannel` on the customer record, three allowed values, by Friday.

Recipe: First schema import — living example · Validation gateway — your model is the validator

The Second Import Is Where Trust Is Won

Anyone can survive the first import. You feed a JSON Schema into a tool, something appears on the other side, and it looks broadly right. The interesting moment is the second — six weeks later, when the schema has changed, other people depend on the model, and a quiet alteration would propagate into a warehouse table, a partner contract, and a validation rule before anybody noticed.

Recipe: GitHub sync round trip

Count the JSON Schemas You Used Today Without Noticing

Before lunch you probably touched five of them. The request body in an API definition is JSON Schema. The configuration file that failed CI with a helpful message was validated against JSON Schema. If your team runs a schema registry, some of the subjects in it are JSON Schema rather than Avro. If you asked a model for structured output, the shape you asked for was JSON Schema. And if you used an AI assistant with tools, every one of those tool contracts — the argument names, the types, the required list — was JSON Schema too.

The Wrong Schema an Agent Writes Looks Exactly Like the Right One

Here is the failure mode that costs teams real time. You ask an assistant to draft a JSON Schema for the customer object it is about to integrate against, and it produces something clean: sensible property names, a tidy `required` array, an `enum` on the status field, `format: "date-time"` where a timestamp belongs. It looks like something your team would have written. It goes into a pull request and gets approved.

Recipe: Agent schema access over MCP

One Call, Three Answers: Your First JSON Schema Transform

Every transform call in CoreModels returns three things, and the third one is the reason we built it this way. You get the converted schema. You get the plan that produced it. And you get a ledger of everything the conversion could not carry across exactly — written in English, with a path pointing at the construct it happened to.

Recipe: Blank JSON Schema project · First schema import — living example

Four Routes and a Round Trip: JSON Schema Over HTTP

A couple of format keys in the CoreModels transform surface are honest about being one-way. `odm` decodes only, because entity documentation is authored, not generated. `synapse` encodes only, and says so out loud when you try the other direction: *"'synapse' is encode-only: a Synapse schema is plain draft-07 JSON Schema — decode it with the 'jsonschema' format."*

Give an Agent a JSON Schema and a Target: transform_schema Over MCP

An agent working on your repository will find a `.schema.json` file long before it finds your conversion documentation. What happens next depends entirely on the tools it can reach. Without one, it writes a converter, or worse, writes the target schema from scratch and presents its guesses with the same confidence as facts.

Recipe: Agent schema access over MCP

Same Plan, Same Bytes: Automating JSON Schema Conversion

A generator you cannot re-run and get identical output from is not a build step. It is a rumor with a timestamp. That is the practical objection to putting schema conversion in a pipeline: if today's run can differ from yesterday's for reasons nobody logged, then the generated Avro, the generated DDL, and the generated proto files are all provisional, and reviewing them is theater.

Recipe: GitHub sync round trip

The Fidelity Contract: JSON Schema to IR and Back, Construct by Construct

Every format coder in CoreModels has to answer the same awkward question: what do you do with the parts of a document you do not model? There are three bad answers — drop them, guess at them, or refuse the document — and one good one, which is to carry them untouched and be explicit about the handful of cases where carrying them is not enough.

Recipe: Import profile walkthrough