Contract first, prompt second
A model may be capable of returning JSON and still be an unreliable API. It can add commentary, repeat keys, truncate values, invent fields, wrap output in Markdown, or produce a syntactically valid object that violates the domain rules.
The integration therefore starts with a schema and state machine, not a persuasive prompt. The contract defines required keys, allowed values, size limits, unknown-field policy, semantic invariants, and the version that downstream code understands. The prompt and fine-tuning target are then designed to satisfy it.
Parse narrowly and validate twice
The first validator answers a structural question: is this exactly one bounded object in the required encoding, with no prefix or suffix? The second answers the domain question: are all values allowed together, and do they match the request context? Both should reject unknown future forms rather than silently coercing them.
Never repair production model output by guessing. Removing prose, filling a missing field with a neutral value, or taking the first object from a longer response makes the parser a hidden second model. If a controlled remediation is genuinely required, version and evaluate it as a separate policy.
- Reject duplicate keys, trailing text, non-finite numbers, and unknown schema versions.
- Bound request and response sizes before parsing.
- Keep display formatting outside the semantic model response.
Fail closed at the consequential boundary
Failure does not always mean shutting down the entire product. It means refusing to cross the boundary that requires valid AI output. A capture can remain queued, an inspection can request operator review, a report can stay unavailable, or a deterministic fallback can provide a clearly labeled limited result.
The key is that malformed or missing output never becomes a partial success. State transitions should be atomic, retries idempotent, and retry lineage visible. That prevents duplicate actions and makes a restarted service able to distinguish unfinished work from completed evidence.
Retain evidence without widening exposure
For high-value debugging, retain the exact bounded model message with the private record, alongside model, contract, and request provenance. Do not place raw output into ordinary logs, URLs, analytics, or public reports. Private auditability and data minimization can coexist when retention has a defined purpose and location.
Metrics should distinguish transport failure, parser failure, schema failure, domain failure, timeout, and operator override. A single ‘AI error’ counter does not reveal whether the model, integration, or hardware needs attention.
Version the meaning, not only the shape
An additive field can still change downstream behavior. A threshold update can alter meaning without changing JSON at all. Version the semantic method, model, decision policy, and presentation rules separately where their lifecycles differ. Stored records should retain the interpretation under which they were created.
Compatibility tests need golden valid objects and a wide mutation set: deletion, insertion, reordering, unsupported versions, boundary values, duplicate fields, unexpected encodings, and interruption at every state transition.