The Schema-Driven Development Manifesto

If you've ever written the schema so your agent could generate everything around it, you're already doing this. Schema-driven development is the name for treating that decision as the durable standard — and moving meaning into its own layer.

The standard<br>Six principles

Embed+

Drop the six on your site<br>HTML<br>React

principles.html<br>copy

Principles.jsx<br>copy

Renders the six, each linked to its page. Append ?theme=dark or<br>?theme=light to the src to pin the theme; tune height to taste.

01

Define a shape once — Every shape that crosses a boundary is declared exactly once.

02

Reuse before you define — Resolve a shared definition before writing your own.

03

Define before you generate — Declare the shape first; then write the code to use it.

04

Version definitions like code — Schemas change through proposals and semver — reviewed, diffed, attributable.

05

Separate shape from meaning — The author declares what data is; what it means is added by everyone who uses it.

06

Derive everything — Everything that carries the data — storage, APIs, validation, forms, docs, agent context — is derived from its definition.

Scope<br>Where this applies

Schema-Driven Development is for the data shapes that cross a boundary — between services, storage, the UI, and your agents. A throwaway script's local struct doesn't need a schema; the User five systems share does.

It begins where disagreement becomes expensive.

Not a schema registry, a serialization-format war, Big Design Up Front, or a replacement for specs and tests — a set of principles for deciding and sharing the shapes that matter.

The asymmetry<br>We version our code. We reinvent our data shapes.

We spent decades making code shareable: version control, packages, semver, review, dependency graphs. We version it, review it, publish it, depend on it.<br>Data shapes never grew the same habit. The formats exist — but none became the shared commons for data that packages are for code. User, Order, Address, Invoice — the structures every system runs on — get reinvented inside each codebase, a little differently every time. The one thing every system has to agree on is the one thing we never learned to share. Not the records — the shapes. What a User is , not who your users are.

Code can be rewritten. A disagreement about what a User is cannot be patched around forever — that isn't bad code, it's broken software.

Decide what things are. Generate the rest.

This debt was always there; agents just made it impossible to ignore. They generate almost everything now — so the only lasting leverage is what you decide the data actually is.

Agent-built systems do not fail at syntax. They fail at agreement. Your agents have no shared memory across sessions and your team has no shared context window. A schema is the single place where that agreement can live, be versioned, and be deterministically verified.

Nobody wants a schema registry. Everyone wants their next change to not silently contradict the last one.

“Your codebase has five definitions of User. Your agent wrote four of them.”

The practice<br>Schema-Driven Development

It's the practice of deciding data shapes before generating code. In the agent era, that practice needs a second layer: shared, typed context around what those shapes mean.

A practice in the TDD / DDD lineage.<br>Schemas before code.<br>Pin down the nouns; let agents write the verbs.

What we value<br>We value

a resolved definition<br>over<br>a convenient local copy

deciding the shape<br>over<br>writing the code<br>(the code is cheap now)

one shape, many authors of its meaning<br>over<br>one owner of both

versioned disagreement<br>over<br>silent drift

There is value on the right — speed, autonomy, a single owner. We value the left more, because the left compounds and the right doesn't.

The economics<br>What one schema removes

Agents make every undecided data shape cheap to create and expensive to live with.

Point your codebases and its agents at one referenceable schema, and a whole category of busywork stops being generated in the first place:

Duplicate forms and validators for a shape that was already defined once

Hand-written mapping layers between services, storage, and agents that each read the shape a little differently

Storage drift, and the migrations that come to mop it up

Re-explaining the same field to every fresh agent session and every new teammate

The generation is cheap. The coordination and translation work is what compounds.

Objections<br>What people might push back on

Questions that people may have who are unfamiliar with schema-driven development.

Isn't this just advocating for a schema registry?

A registry answers one question: is this payload the right shape? That's table stakes, and it's decades old: it validates, versions, stores. What it doesn't carry is the thing that actually drifts — what a field means once it crosses a boundary, who decided that, whether you should trust them. Two teams can both pass the same...