Separate response shape from answer correctness

Learning objective

Enforce structured response contracts with JSON Schema while distinguishing syntactic validity from factual correctness.

Core idea

A structured response contract tells software what a model result must look like. It can require fields, constrain types, and limit permitted values. It cannot establish that an amount is correct, a cited passage supports a claim, or the caller may perform an action. These are separate acceptance decisions.

Distinguish three gates. Parsing establishes that the result is valid JSON. Schema validation establishes that the JSON has the expected shape. Semantic validation establishes that its contents satisfy the application’s rules and evidence requirements. A response can pass the first two gates and fail the third without any contradiction.

Amazon Bedrock structured outputs can constrain generation to a supported JSON schema rather than relying only on a prompt that asks for JSON. Use that mechanism where the model and inference route support it. Retain business validation at the consuming boundary because downstream code, model routes, and risk rules have separate contracts.

How it works

Select the supported generation interface

For Bedrock Converse and ConverseStream, set outputConfig.textFormat to the JSON Schema format. The nested structure uses jsonSchema, whose schema value is a serialized schema string. Keep schema construction in application code rather than asking the model to define the contract it must satisfy.

For InvokeModel with Anthropic Claude models, the documented native field is output_config.format. For supported open-weight models, it is response_format. These are different payload contracts. Copying a Converse field into a native invocation does not configure structured generation; see 1.3.7 for native request validation.

Strict tool use is a complementary mechanism. Adding strict: true to a tool definition constrains tool names and inputs to the tool contract. It does not turn a generated tool argument into authorization to execute that tool. Response formatting and tool argument formatting protect different consumers; tools still need the validation and permission checks described in 2.1.10.

Structured outputs supports a subset of JSON Schema Draft 2020-12. AWS documents basic JSON types, primitive-valued enum, internal references, and selected composition and format features. It does not support recursive schemas, external references, numeric constraints such as minimum or maximum, or string constraints such as minLength and maxLength. It supports additionalProperties only when set to false.

An unsupported schema feature produces a 400 error rather than silently becoming a supported business rule. Move such rules to application validation. For example, an amount field can be a number in the generation schema, while application code checks whether it is positive and below the caller’s authorized limit. Do not delete the business requirement just to make the generation schema compile.

Version a small, explicit contract

Use a response shape that exposes the decision the consumer actually needs. For a source-backed policy answer, fields might include an application-defined status, answer text, and evidence identifiers. A status enum can distinguish answered from insufficient evidence. These names are your application contract, not predefined Bedrock response fields.

Require the fields the consumer depends on and reject unexpected properties. Define how absent information is represented: an explicit status, a nullable value, or a deliberately optional field. Avoid forcing a plausible value into every field when the source lacks the answer. A required string establishes presence, but it does not require the model to admit uncertainty.

Keep the generation schema and the consumer’s validation schema compatible and version them together. A model returning a permitted enum from one schema version can still break a consumer that understands a different version. Release the schema with the prompt, model configuration, and consuming code so rollback restores a compatible set.

AWS documents that first-time grammar compilation can take up to a few minutes and that compiled grammars are cached for 24 hours from first access. Reuse stable schemas and include compilation behavior in latency tests. Creating request-specific schemas without a real contract need can make a predictable response format produce unpredictable startup latency.

Validate meaning after shape

After generation, inspect the inference result before consuming its text. Converse exposes stopReason, including max_tokens, malformed_model_output, and guardrail_intervened. Handle incomplete or malformed generation and guardrail replacement as explicit outcomes. A configured blocked message need not be the business object your downstream code expects.

Then parse and validate the contract for the route you actually received. On a supported successful structured-output path, Bedrock constrains the schema. Consumer-side validation remains valuable when multiple routes, stored artifacts, or schema versions share the same boundary. Do not indiscriminately repair malformed output and execute it; a repair can change the proposed meaning.

Apply domain rules to the validated object. Resolve evidence identifiers against the retrieved passages, recompute derived amounts from authoritative data, and check that a proposed operation fits the caller’s permissions. If the object claims that an account has a particular balance, the field’s numeric type says nothing about the balance’s truth.

Use separate failure reasons so recovery addresses the failed gate. Invalid schema configuration needs a deployment correction. A transient invocation failure can use a bounded retry. Insufficient evidence needs clarification or abstention. An unauthorized action needs denial. Sending every failure back to the model as try again can hide a missing business boundary.

Key distinctions and trade-offs

Prompt-only formatting is an instruction the model might not follow. Structured generation is an API capability that constrains output where supported. JSON parsing and schema validation remain different even when both run in the same library: any JSON value can parse, while only values matching the contract validate.

Schema compliance and factual correctness also diverge. An enum can restrict an assessor to allow or reject, but it cannot establish that the selected verdict is justified. Confidence fields generated by the model do not become calibrated confidence because their type is a number.

Check capability for the selected model and route. AWS directs readers to model cards for support and documents model-specific inference-profile exceptions. It also documents incompatibility between structured outputs and Anthropic citations: enabling both returns a 400 error. Do not assume a schema-capable model supports every combined feature or endpoint.

Architecture / decision scenario

A benefits assistant returns a machine-readable coverage decision. The team defines a schema with an application status enum, answer text, and source identifiers, using outputConfig.textFormat on a supported Converse route. additionalProperties: false prevents an unexpected executable-action field from entering the result contract.

The consumer validates the object and checks the cited policy version against the employee’s plan and date. A schema-valid answer that uses another plan’s passage is withheld. Any calculated reimbursement is recomputed from authoritative values because unsupported numeric constraints and factual correctness remain application responsibilities.

A guardrail_intervened result follows a safe response route rather than being decoded as an approved coverage object. The release test includes valid JSON with missing fields, a valid object containing the wrong plan, an unsupported schema keyword, and a correct source-backed answer. Each fails or passes at the gate it actually tests.

Common exam traps

• Equating parseable JSON with schema compliance.
• Equating schema compliance with evidence support or authorization.
• Assuming every JSON Schema keyword is supported by Bedrock generation.
• Treating strict: true as permission to invoke a tool.
• Using the same formatting field across Converse and native model payloads.
• Assuming structured outputs and Anthropic citations can be enabled together.

What to remember

Constrain response shape with the supported API mechanism and a stable schema. Validate the inference outcome, the consumer contract, and the domain meaning separately. Structured outputs reduces formatting failures; application checks still decide whether a valid object is correct and safe to use.

Knowledge check

References

• AWS, Structured outputs
• AWS, Converse
• AWS, Use a guardrail with the Converse API