Schema Versions
Freeze a model's schema into a numbered snapshot, and pin a deployment to it.
A model's schema is a draft: editing a column changes what the next extraction sees. A schema version is that draft frozen — an immutable, numbered snapshot of the model's tables and columns together with the extraction configuration in force when it was taken.
Cutting one costs nothing and changes nothing on its own. A version only starts serving traffic when a deployment is pinned to it.
What a version holds
| Field | Description |
|---|---|
number | Counts from 1 within its model, one higher on every cut |
label | An optional short name, such as Q3 invoices |
notes | Optional free text describing what the cut is for |
definition | Every table and column, each addressed by its slug and its ID |
config | The extraction settings — instructions, model, reasoning level, example settings and the rest |
Nothing in a version can be edited afterwards. To change what a version says, cut another one.
Two things have to be true of the model before a version can be cut: it needs a primary table, and every table and column needs a slug. The slug is what makes a snapshot readable years later — an ID says which column, a slug says which column it was.
Pinning
A deployment either tracks the draft or is pinned to one version of its own model.
- Tracking the draft. Every schema edit reaches the next document through that deployment. This is the right setting while a model is being built, and for a
stagingdeployment that should always show the newest work. - Pinned. The deployment serves the frozen version and ignores draft edits entirely. You can keep editing the model with no effect on what that deployment extracts.
Pinning and re-pinning leave the deployment's ID untouched, so moving a production deployment from v2 to v3 — or back to v2 — is one action on the deployment and none on the integration calling it. Rolling back is re-pinning to the earlier version; there is no separate operation for it.
A deployment can only be pinned to a version of the model it points at.
Deleting a column a version describes
A deployment pinned to a version whose columns no longer exist cannot extract. So deleting a column or table that a retained version still describes is refused, and so is replacing a model's whole schema while the model has retained versions. Nothing is removed.
Two routes lead out of that refusal:
- Retire the column or table. It leaves the draft — no new extraction sees it — and not one extracted value is touched. The retained versions still describe it, so a deployment pinned to one of them keeps extracting exactly as before. This is the route that costs nothing.
- Purge it. The column or table goes, along with every cell and row ever extracted for it, and every retained version that describes it is marked
INVALIDATED. Purging is refused outright while an active deployment is pinned to one of those versions, and otherwise takes an explicit confirmation naming the versions it will invalidate.
Replacing a model's schema wholesale recreates every table, so it needs those tables purged first — at the cost of every row and cell they hold.
An invalidated version is not deleted, but it no longer serves: it cannot be pinned, and a paused deployment cannot be resumed while the version it is pinned to is invalidated.
Cut versions at the points you are willing to keep: a version is a commitment to the shape it captured, and retiring is how you move on from a column without breaking that commitment.
Reading the stamps
Every document records the version it was extracted against as schemaVersionId, alongside the viaDeploymentId it arrived through. A document processed through a deployment that tracks the draft has schemaVersionId: null — there was no frozen version to record. Both stamps ride on webhook payloads, which is how an integration tells apart two documents extracted by the same model under different versions.
Where versions live
In the dashboard you release into a deployment rather than cutting and pinning versions by hand. Each release is numbered per deployment and shows the schema version it serves; a release reuses an existing version when the schema matches one and cuts a new version otherwise, and rolling back is releasing an earlier release again. The API consumes the result: address a deployment by its ID and the version pinned to it decides the schema, and read schemaVersionId off the events you receive to know which one served.