Treat the schema as a system contract, not a prompt appendix
Enterprise AI frequently extracts data from email, support conversations, quotations, maintenance records, or uploaded documents, then passes the result to a CRM, ERP, ticketing system, database, or workflow engine. The failure mode is not limited to malformed JSON. More often, a model omits a required field, changes a number into descriptive text, invents a new enum value, uses an unexpected date format, or adds fields that the receiving system does not understand. These variations may look harmless to a person but can corrupt records, misroute work, or break an API call.
Design the schema backward from the consumer. Decide which fields are required, which may be null, which use controlled vocabularies, and how changes will remain compatible. An empty string should not carry every form of uncertainty. “Not present in the source” and “present but ambiguous” may require different status or reason fields. Store an amount separately from its currency, specify date formats and time zones, and represent identifiers as strings so that leading zeroes and long values survive movement between systems.
Use JSON Schema, function calling, tool calling, or constrained decoding when the selected platform supports them. They reduce the model’s freedom and eliminate many formatting errors, but they are not a complete guarantee. Providers support different subsets of keywords, and enforcement of format, pattern, oneOf, or conditional rules can vary. Confirm the behavior of the exact model and API configuration, then keep validation in the application boundary.
Build three defenses: generation, schema validation, and business validation
The first defense constrains generation: provide a precise field description, disallow additional properties, use controlled enums where appropriate, and avoid unnecessary sampling. The second parses the response and validates required fields, types, lengths, enums, and nested structures against a pinned schema version. The third applies domain rules that a structural schema cannot fully express. An end time must not precede its start time; a calculated total should agree with line items; a customer code may need to exist in master data.
Make the following decisions explicit in the contract and its tests, rather than leaving them only in prompt prose:
- Missing-value semantics: distinguish null, an empty string, an empty array, and an unknown status so downstream systems do not have to guess.
- Controlled vocabulary: use enums for values that drive routing or automation, while keeping unrestricted explanations in a separate text field.
- Numbers and units: separate numeric values, currencies, percentage bases, and measurement units instead of accepting mixed phrases such as “about one hundred thousand.”
- Source evidence: attach a source span, page reference, or message identifier to important fields when traceability matters. Do not treat a model-generated quotation as original evidence.
- Confidence and review state: avoid making a self-reported confidence score the sole control. Combine observable validation signals, missing-field lists, and an explicit human-review state.
Repair in layers, with a strict stopping point
When validation fails, begin with deterministic normalization. Safe examples include removing a known Markdown wrapper, normalizing a date that has an unambiguous interpretation, or mapping an approved alias to a canonical enum value. Automatic repair should be limited to transformations that preserve meaning. Coercing arbitrary prose into a number or guessing a missing account identifier may create a more dangerous record than rejecting the input.
A model-assisted repair pass can handle failures that require contextual rewriting. Send it the original output, the schema, and a concise list of validation errors. Ask it to correct only the invalid portions rather than reinterpret the complete source. Validate the repaired object from the beginning and enforce a small, explicit retry limit. If it still fails, route it to a quarantine queue, human review, or a defined fallback. Never continue retrying until something happens to validate.
Schema compliance also does not make an action safe. Data that can initiate payments, delete records, change permissions, or notify an external party should pass additional authorization and approval checks. The model should propose the structured action; a deterministic policy layer should decide whether the action is permitted.
Avoid silent repair. Record the original response, validation errors, repair operations, repaired object, schema version, model version, and final disposition. That evidence makes production issues diagnosable. If the content includes personal or commercially sensitive information, redact protected fields and apply an appropriate retention policy instead of logging complete payloads indefinitely.
Maintain reliability with adversarial examples and version governance
Structured output is not a one-time configuration. Model releases, prompts, source formats, and business requirements all change. A useful evaluation set includes incomplete documents, broken tables, mixed languages, duplicated labels, negated statements, conflicting evidence, and inputs where the correct result is explicitly unknown. Tests should verify semantic field accuracy as well as whether the JSON parses. A perfectly valid object containing the wrong customer, date, or amount is still a production failure.
Version the schema as deliberately as an API. Adding an optional field is usually less disruptive than renaming a field, changing its type, or narrowing an enum. For incompatible changes, expose a version identifier and allow producers and consumers to support old and new contracts during a controlled migration. Contract tests should exercise every receiving CRM, ERP, warehouse job, and workflow before the older version is retired.
Production monitoring should group validation failures by field and rule, track repair attempts and review outcomes, and identify compatibility problems by schema version. When one field repeatedly fails, the best fix is often a clearer contract, better source normalization, or a revised business rule—not a longer prompt. For integrations spanning several enterprise platforms, schema ownership should be shared by the AI and integration engineers who understand both model behavior and downstream consequences.