AI & Automation

AI Structured Outputs: Valid JSON Still Needs Business Validation

A supply request arrives as a paragraph. An AI system turns it into a tidy object. Every required field appears. The quantity is wrong.

The receiving software can read the answer. The purchasing coordinator still cannot use it.

Build the output contract around four checks: parsing, schema compliance, source support, and business rules. Decide whether each check permits the result to advance.

Each check needs its own finding. A green check beside one does not complete the other three.

The workflow below uses fictional supply records. It proposes an acceptance method for individual results. It makes no API calls, places no orders, and describes no completed client work.

Define What the Object Represents

Start with the receiving team's task. In this example, a coordinator needs a draft supply request for review. The object represents what a source document says. It contains no purchase authorization.

Give that distinction a place in the field definitions. A requested quantity describes a request. An approval would describe a separate decision by an authorized person. Combining those meanings inside one field leaves the reviewer guessing which event occurred.

Use a compact contract with explicit unknown values. Require the keys even when their values are unknown. That lets a reviewer distinguish an intentional abstention from a missing field.

The JSON Schema object reference explains that listing properties does not require their presence. Use required to require keys and additionalProperties: false to reject undeclared keys. A present null also differs from an absent property.

Here is the proposed extraction schema. Null means the supplied text does not establish a usable value. The status describes extraction completeness only.

{
  "type": "object",
  "properties": {
    "request_id": {"type": ["string", "null"]},
    "item_code": {"type": ["string", "null"]},
    "quantity": {"type": ["integer", "null"]},
    "unit": {"type": ["string", "null"]},
    "source_location": {"type": ["string", "null"]},
    "status": {"type": "string", "enum": ["extracted", "needs_review"]},
    "review_reason": {"type": ["string", "null"]}
  },
  "required": [
    "request_id", "item_code", "quantity", "unit",
    "source_location", "status", "review_reason"
  ],
  "additionalProperties": false
}

Keep the schema version in the surrounding processing record. Here, call it supply-request-v1. Assign that version outside the model so the model cannot choose which contract applies.

Define each field before adding another. item_code means the literal requested identifier. unit means the stated unit of measure. Neither field asks the model to find a substitute product or convert packaging.

Put Three Candidate Answers Beside One Source

The fictional source is document SR-014, line four: “Request twenty boxes of BX-7. Purchasing approval is pending.” These words are invented for this example.

The following comparison uses the same schema for three separate situations. The first two candidates receive the complete line. The third receives an excerpt that omits the quantity.

Candidate Quantity Status Acceptance finding
Wrong extraction 200 extracted Structure passes; source check fails
Supported extraction 20 extracted Source supports the fields; purchasing remains pending
Appropriate abstention null needs_review Incomplete excerpt cannot establish quantity

The schema-valid but wrong object looks like this:

{
  "request_id": "SR-014",
  "item_code": "BX-7",
  "quantity": 200,
  "unit": "boxes",
  "source_location": "SR-014 line 4",
  "status": "extracted",
  "review_reason": null
}

The supported object differs in a business-critical value:

{
  "request_id": "SR-014",
  "item_code": "BX-7",
  "quantity": 20,
  "unit": "boxes",
  "source_location": "SR-014 line 4",
  "status": "extracted",
  "review_reason": null
}

Now suppose the supplied excerpt reads “Request boxes of BX-7,” under the same document identifier. The quantity is absent. An appropriate abstention preserves the known fields:

{
  "request_id": "SR-014",
  "item_code": "BX-7",
  "quantity": null,
  "unit": "boxes",
  "source_location": "SR-014 excerpt line 4",
  "status": "needs_review",
  "review_reason": "Quantity is absent from the supplied excerpt."
}

Do not substitute zero for that missing quantity. In this contract, zero would assert a number the source never supplied. Keep the incomplete record available for review without promoting it into a completed request.

Check Parsing Before Interpreting Fields

Treat the raw response as unaccepted material. Preserve the response identifier, source reference, contract version, and completion status before inspecting the object.

The parsing check asks whether the payload is valid JSON. It does not decide whether the quantity is plausible or whether the requested item exists. Keep those decisions in later checks with their own findings.

If parsing fails, stop processing that candidate. Do not repair a missing bracket and silently treat the repaired text as the original response. A reviewer needs to know which bytes came back and which changes someone introduced.

A repair can become a new candidate when your workflow allows it. Give it a separate attempt identifier. Preserve the first failure. Run the replacement through every acceptance check again.

This distinction matters in AI data entry automation, where one field can become an input to another system. Keep an unreadable response out of the same queue as a verified extraction. Both may require attention, but they require different work.

Validate the Contract Independently

After parsing, check the object against the local contract. Verify required keys, declared types, permitted status values, and unexpected properties. Record which contract version produced the result.

In this example, a quantity written as the string "20" fails the integer-or-null rule. An extra approved field fails the closed-object rule. Neither failure needs a model to explain it.

A valid object still needs cross-field checks. Under this proposed contract, extracted requires non-null values in all five extraction fields and a null review reason. needs_review requires a concrete reason. Implement those conditions as explicit acceptance rules outside the displayed schema.

That separation keeps the schema small while making its limits visible. The displayed schema alone permits inconsistent combinations. A consumer must not assume every valid combination represents a completed extraction.

Use a separate result for contract failures. Record the offending field and the expected condition. Avoid a generic “AI failed” message that forces the next reviewer to reconstruct the problem.

Keep these checks in the workflow definition alongside the prompt. The LLM operations framework provides the broader operating context. Here, the immediate concern is whether this one object can advance to evidence review.

Verify Values Against the Supplied Evidence

Open the recorded source location. Compare the requested identifier, item code, quantity, and unit with the actual passage. A location written by the model is a claim to verify.

For SR-014, the quantity check rejects two hundred because line four says twenty. The parser cannot catch this. The schema cannot catch it. Even a rule accepting quantities from one through five hundred would admit the wrong answer.

Check the relationship between fields as well. Twenty boxes and twenty individual items describe different requests. An item code copied correctly does not justify changing the unit to a familiar packaging convention.

Preserve the source wording when normalization could change meaning. Converting the written number twenty into the integer twenty is explicit in this example. Converting boxes into individual units requires a separate, verified conversion rule.

If the passage cannot be located, mark evidence review unresolved. Do not accept a convincing explanation as a substitute for the passage. Request the missing source location or return the candidate for correction.

For a request spanning several lines, extend the contract deliberately. Attach a source location to each extracted item. A single pointer to a long document can conceal which passage supports which value.

Apply Business Rules Without Inventing Approval

Suppose the fictional team permits draft requests only for recognized item codes and positive quantities. Suppose it also requires purchasing approval before an order can be prepared. These are invented operating rules, not industry requirements.

The supported object clears the source check. The coordinator must still confirm that BX-7 is recognized in the team's chosen reference. The article supplies no catalog, so catalog acceptance remains unknown.

The approval decision is clearer. The source explicitly says approval is pending. A complete extraction must remain a draft while that condition holds.

Keep business-rule findings outside the model's extraction status. Otherwise extracted can become a misleading shortcut for “ready to order.” Record separate findings for source support, catalog recognition, quantity rules, and approval.

When a rule fails, preserve the supported values. A correct quantity can coexist with a rejected request. Replacing the quantity to make the request pass would destroy the distinction between what someone requested and what the business permits.

Assign unresolved questions to the role that owns them. The source owner clarifies an ambiguous unit. Purchasing resolves approval. The workflow maintainer resolves contract failures. A model-generated confidence score does not replace those responsibilities.

Pin Provider Behavior to the Configuration

The technical example uses Claude's direct Messages API with claude-opus-5-5 and output_config.format containing type: json_schema plus the schema. This configuration was documented when checked on October 28, 2026. No request was executed.

The structured-output documentation lists a supported schema subset. Numerical bounds, string-length constraints, recursive schemas, and external references are unsupported. Objects require additionalProperties: false. Keep unsupported checks in the receiving application.

The same documentation identifies exceptions: refusal can arrive with HTTP 200 and a nonmatching body; max_tokens can leave incomplete output. String enum capitalization can also differ. Local validation remains necessary.

Handle those outcomes before accepting fields. A refusal is a provider response condition. An abstention is an extraction result stating that evidence is missing. Preserve that distinction in your review queue.

If output is incomplete, hold the candidate. Reconsider the request or output allowance before another attempt. Do not stitch a guessed ending onto a partial object.

These details belong to the named configuration. Recheck the applicable documentation when changing providers, models, or SDK helpers. Record the change before comparing acceptance results across versions.

Give the Reviewer a Usable Acceptance Record

Use the following worksheet for each candidate. These fields are a proposed handoff method. They are separate from the extraction schema and should be filled from the checks performed.

Check Record Result for the supported fictional candidate
Response completion Provider status and attempt identifier Must be checked on a real response
Parsing Valid JSON or exact failure Valid in the displayed example
Schema Contract version and violations Matches supply-request-v1
Evidence Compared fields and source location Twenty boxes of BX-7, SR-014 line four
Business rules Named rule and verified reference Catalog unknown; approval pending
Disposition Hold, correct, or accept as draft Hold for remaining review

Keep the record narrow enough to inspect. Include the source passage, the candidate object, and the findings that determine its disposition. Avoid burying the unresolved approval beneath a long model explanation.

Before any external action, show the authorized reviewer the exact proposed action and its supporting record. Keep acceptance of an extraction separate from permission to act. The broader AI agent workflow needs that boundary wherever a proposed result reaches an execution step.

If the reviewer corrects a value, retain the original candidate and record the correction. Recheck affected rules against the corrected object. Approval applies to the reviewed version, not to whatever object happens to be latest.

A structured answer is ready for review when its fields and evidence can be inspected together. Accept the evidence before the action.

Sources

Topic map: APIs, webhooks, and automation

Articles in this cluster, then the 3 clusters that share the most topics with it.

This cluster: APIs, webhooks, and automation

Neighbor: CRM and pipeline data

Neighbor: Spreadsheets, CSV files, and data handoffs

Neighbor: Records, access, and continuity