Write a structured-output contract for an LLM task

“Return JSON” specifies a serialization format, not the business contract. A useful output definition states required fields, allowed values, bounds, evidence relationships and what to emit when the task cannot be supported.

Define the contract first

The offline foundations lab creates a small decision schema.

from foundation_cases import structured_contract_case

result = structured_contract_case()
assert result["valid"] is True
assert result["output"]["decision"] == "abstain"
assert result["output"]["evidence_ids"] == []
print(result["contract"])

The contract requires exactly decision, evidence_ids, confidence and reason. Decision must be approve, reject or abstain; confidence stays between zero and one. The fixture abstains with no evidence and explains why. This is local validation, not a model output.

Add semantic relationships

Syntax and field types are the first layer. Business rules might require:

• approve or reject must include at least one valid evidence ID;
• abstain must include a reason and no invented evidence;
• confidence cannot override a missing mandatory document;
• evidence IDs must belong to the authorized retrieval result;
• unknown fields are rejected or versioned deliberately.

Use an explicit schema version. Decide how clients handle additive fields, renamed fields and new enum values. A consumer that treats an unknown decision as approval is a dangerous compatibility failure.

Design errors for recovery

Return machine-readable validation failures with the field, violated rule and retry policy. Some format failures may justify one bounded repair attempt. Missing evidence or failed authorization should route to abstention or human review rather than repeated generation.

Test empty strings, nulls, extra properties, out-of-range numbers, invalid evidence references, conflicting fields and oversized arrays. Keep the raw response under appropriate access for debugging, but make the validated object the only input to downstream logic.

The Generative & Agentic AI course connects structured outputs to tool contracts, workflow state and release gates.

Exercise

Write a JSON Schema or typed model for an extraction task. Add three cross-field rules the schema alone does not express. Generate or handcraft invalid cases, verify useful errors and demonstrate that no downstream action sees an unvalidated object.

Continue learning

This article is part of the LLM fundamentals and prompt design sequence. Use the neighbouring tasks when you need the prerequisite or the next application.

• Review the prerequisite or neighbouring task in Prompt instructions versus retrieved evidence.
• Continue with Validate JSON output beyond syntactic correctness.

Reference: JSON Schema object reference.