Schema drift: why structured extraction fails quietly, and how to make it fail loudly

Structured extraction rarely fails the way you prepare for. You expect malformed JSON and a parse error. What you get is well-formed JSON with a field renamed, a number arriving as a string, or a key that was not there yesterday — and everything downstream accepting it without complaint.

1. What schema drift actually is

Drift is not one event. It is the gap that opens between the shape you assumed and the shape that arrives, from either side:

• From the model. A new version phrases the same answer differently, or starts wrapping the result in one more object.
• From the prompt. Someone adds a sentence, and the output gains a field nobody asked for.
• From the source. The API you extract from renames a key or changes a type.
• From the consumer. Your own code starts needing a field the extractor was never asked to produce.

2. What it looks like in a visual flow

In a canvas, the contract between two steps is a field mapping made by hand on the day it was built. When drift happens, that mapping does not error — it resolves to empty. Three shapes recur:

3. Make the shape explicit, then refuse surprises

The first move costs almost nothing: declare the shape, and say that anything else is an error. Strictness is opt-in, so opt in.

{
  "type": "object",
  "additionalProperties": false,
  "required": ["sku", "cantidad", "precio_unitario"],
  "properties": {
    "sku":              { "type": "string", "minLength": 1 },
    "cantidad":         { "type": "integer", "minimum": 1 },
    "precio_unitario":  { "type": "number", "exclusiveMinimum": 0 }
  }
}

Note what the types are doing. integer rather than number for a quantity; a minimum that rules out zero and negatives; a price that cannot be zero. A type that accepts anything catches nothing — most of the value of a schema is in the constraints, not in the field names.

4. Validation gates, and what happens after one fails

A schema tells you the payload is wrong. It does not tell you what to do about it, and that decision is where systems differ:

1. Reject at the boundary. Validation runs before anything acts on the data. A bad payload never reaches the code that would have used it.
2. Repair once, with the error in hand. Give the model back the validation message — which field, what was expected — and ask again. This is worth doing because it is a *different* attempt, not the same one.
3. Escalate, don't loop. If the second attempt fails the same way, stop. A third identical try is not error handling; it is the same gamble, paid again.
4. Fall back to something deterministic. Answer from a template, or hand to a human. An answer you cannot back is worse than no answer.

5. Contract tests: the part people skip

A schema protects you at runtime. What protects you at build time is a set of golden fixtures: real payloads you have actually seen, checked against the current schema on every commit.

fixtures/
  01-normal.json              el caso feliz
  02-campo-renombrado.json    lo que llegó el día que se rompió
  03-numero-como-texto.json   idem
  04-envuelto-de-más.json     idem
  05-campo-extra.json         idem

The discipline is simple and it is the whole method: when something drifts in production, the fix is not complete until the payload that broke it is a fixture. Otherwise you will fix the same drift twice.

6. What to measure

We are not going to quote you our numbers here, because a resilience figure without the method behind it is decoration. What is useful is knowing which four to watch, and what each one tells you when it moves:

7. Hardening checklist

1. Every extraction has a declared schema, with additionalProperties: false.
2. Constraints, not just types: ranges, lengths, enums where the set is known.
3. Validation runs before anything acts on the data, not after.
4. One repair attempt, fed the validation error. Never a blind retry.
5. A deterministic fallback for when repair fails — template or human, but decided in advance.
6. Golden fixtures in version control, including every payload that has broken you.
7. Rejection and repair rates on a dashboard someone actually looks at.

Where the schema behaviour comes from

The default behaviour quoted above is from the JSON Schema documentation itself.

• object — By default, «providing additional properties is valid»: a schema accepts fields it never declared. Setting additionalProperties to false is what stops that — strict validation is something you ASK for, not something you get.

Checked on 2026-09-29.