ODCS Is Not Competing With Your Schema Format

A question we get early in most conversations: "If we adopt ODCS, do we stop using JSON Schema?"

It is a category error, and a revealing one. The Open Data Contract Standard is not another way to describe fields and types. It is a layer above that, describing the agreement that a set of fields and types participates in — and it happens to include a schema section because an agreement about data has to say which data. Asking whether ODCS replaces Avro is like asking whether a lease replaces a floor plan.

Understanding where the standard sits makes the tooling decisions obvious, so let us draw the map.

The corner of the map that was empty

Structural formats cluster tightly. JSON Schema, Avro, Protobuf, SQL DDL, ShEx — each is excellent at saying what exists and what type it is, and each is close to silent on everything around that. Who owns this data? What quality bar has it promised? Which servers does it live on? What happens when it is late? Who do you call? Those questions lived in wikis, tickets, and institutional memory.

ODCS, developed by the Bitol project under the Linux Foundation, moved into that corner. A contract is a single document — kind: DataContract, the only kind the specification allows — that binds the schema to its agreement. Around the schema objects and their properties sit a description block stating purpose, limitations, and usage; quality checks with metrics and severities; classification and encryption markers on individual fields; physical names and types that bind the logical schema to a real platform; business names and granularity descriptions; relationships between objects; and whole sections for servers, team, roles, SLA, support, and pricing.

It is also a standard with mileage. The published apiVersion enum still spans the v2.2 line alongside the current v3 releases, and fields get deprecated with care rather than deleted — dataProduct, for instance, is deprecated as of v3.1.0 rather than removed. That is what a spec looks like when real contracts already depend on it.

Which is exactly why it needs neutral plumbing

A contract is a boundary object. Producers, consumers, platform engineers, and governance functions all read the same file for different reasons — and they typically work in different tools, departments, sometimes different companies.

It also means an implementation that respects only the parts it cares about breaks the artifact's purpose. If the tool a producer uses drops the SLA section on round trip, the consumer's copy and the producer's copy are no longer the same contract, and the standard's central value — one document both sides can trust — is gone.

In CoreModels, ODCS is one format key, odcs, among the thirteen format names our transform engine dispatches: JSON Schema (alias sia), Avro, Protobuf (alias proto), SQL DDL across Postgres, MySQL and SQL Server dialects, JSON-LD, OWL, ShEx, LinkML, Apache Ossie semantic models in YAML or in the JSON serialization dbt ingests, MACH ODM entity documents, and the Sage Bionetworks Synapse draft-07 subset. Two are one-directional by nature and say so: ODM decodes only, being authored documentation rather than a generated artifact; Synapse encodes only, its output being plain draft-07 JSON Schema that re-imports through the jsonschema key.

Every format decodes into the same governed model and encodes back out of it. There are no pairwise converters, which means ODCS composes with all of the others without anyone writing an ODCS-to-Avro adapter and so on down the matrix. The same governed model is what our warehouse and transformation-tool integrations read and write, so a contract's structure and an estate's actual tables end up described in one place rather than two.

The three shapes adoption takes

Contract-first. The ODCS document is the source of truth. It imports once, and the DDL, the API schema, and the streaming schema are generated from the resulting model — each with its own ledger of what that narrower format could not carry.

Model-first. The organization already governs a model and needs to issue a contract. It exports as ODCS with the standard's required head minted where the model has no contract history of its own, producing a document that conforms without anyone reading the specification.

Neither. A contract needs to become an Avro schema this afternoon, with no project, no import, and no adoption decision. The stateless path converts it in one call and writes nothing.

Most real estates do all three at once for different datasets, which is the argument for a neutral model in the middle.

Implementing a standard is not annexing it

We implement the ODCS specification; we do not steward it, extend it, or dialect it.

Concretely: our encoder is pinned to the published v3.1.0 JSON schema in the standard's own repository, and our tests check emitted contracts against that schema's key constraints — the required top-level fields, the valid apiVersion and kind values, schema objects carrying names, and property logical types drawn from the spec's own enum of nine. Where our model holds something the standard cannot express, we record honest lossiness rather than inventing a key that would make our output "ODCS plus a little extra."

Input gets the same treatment. Documents from the v2 era are accepted, decoded with v3 semantics, and told about it. Unknown keys — including extensions from other vendors' tooling — are preserved untouched rather than stripped, because a key we do not recognize is not a key we are entitled to delete.

Why neutrality is the load-bearing wall

That posture is closer to self-interest than modesty, honestly stated.

An agreement mediated by a format only works if no single vendor controls the format's meaning. The moment a tool's "ODCS" is quietly its own dialect, contracts stop being portable between the parties that signed them, and the standard degrades into a file format with a nice name. Interoperability standards rarely die of neglect; they die of embrace-and-extend.

Neutrality also makes adoption reversible, and reversibility makes adoption safe. Because our support is bidirectional and conformant, the exit is a first-class operation: export your contracts and walk away with standard documents any conforming tool reads. We would rather be re-chosen every quarter than retain anyone by making their contracts hard to take with them.

The wider landscape is still moving — contract standards, semantic layers, and catalog formats keep converging on overlapping ground. Our bet is structural rather than partisan: a neutral model in the middle, honest translation at every edge, and each standard implemented the way its authors published it.

For the full list of formats a contract can travel to and from, see the schema transform documentation in the CoreModels docs.