Structured JSON Outputs on Claude Platform on AWS

Most enterprise Claude workloads end in a machine, not a person: an extraction pipeline writing rows, a triage service routing tickets, a workflow engine reading a decision. Those systems need JSON that matches a schema. Claude Platform on AWS supports structured outputs and strict tool use at general availability — the same capability set as the first-party Claude API — so you have two reliable routes to schema-shaped output.

Route 1: wrap the schema in a tool

The most portable pattern is to define a single tool whose input_schema is the JSON Schema you want, then force Claude to "call" it. Claude fills in the tool's input arguments, and those arguments are your structured output — already parsed by the SDK, no string wrangling required. This works on every platform that supports tool use, which makes it a safe default if the same code must also run on Bedrock or Vertex AI.

from anthropic import AnthropicAWS

client = AnthropicAWS()
schema = {"type": "object",
          "properties": {"sentiment": {"type": "string",
                                       "enum": ["positive", "negative", "neutral"]},
                         "summary": {"type": "string"}},
          "required": ["sentiment", "summary"]}
resp = client.messages.create(
    model="claude-sonnet-5", max_tokens=1024,
    tools=[{"name": "record_analysis", "description": "Record the analysis result",
            "input_schema": schema}],
    tool_choice={"type": "tool", "name": "record_analysis"},
    messages=[{"role": "user", "content": "Analyze: 'Shipping was slow but support fixed it fast.'"}])
result = next(b.input for b in resp.content if b.type == "tool_use")

The tool_choice setting of {"type": "tool", ...} forces the model to emit exactly that tool call. Be aware forcing a tool costs slightly more prompt overhead than auto (for example, 474 vs. 354 hidden system-prompt tokens on Claude Sonnet 5).

Route 2: native structured outputs

Recent Claude models also support a native structured-output mechanism configured through the request's output_config.format field (older code that used a top-level output_format should migrate to output_config.format). Anthropic's migration guide points to structured outputs as the modern replacement for assistant-message prefilling, which returns a 400 error on Claude Opus 4.7 and later. Check the official structured-outputs documentation for the exact format options supported by your target model — the point for platform selection is simply that this feature is GA on Claude Platform on AWS, while on Microsoft Foundry it is still beta.

Always validate in application code

Schema enforcement dramatically raises the odds of well-formed output, but a production pipeline should still treat the model as an untrusted producer. Validate every response against the schema with a real validator (for example, the jsonschema package) before it touches downstream systems. Validation catches three real-world failure classes:

Truncation. If stop_reason is "max_tokens", the output was cut off mid-structure. Don't attempt repair — raise max_tokens and retry.
Semantically wrong but syntactically valid. A schema constrains shape, not truth. Enum fields and required lists narrow the space; business-rule checks (totals add up, IDs exist) belong in your code.
Refusals. Newer models can return stop_reason: "refusal" instead of output. Handle it as an explicit branch, not a parse error.

Rule of thumb: retry once with the validation error appended to the conversation ("The previous output failed validation: <error>. Emit corrected JSON only."), then fail loud. Silent best-effort parsing of malformed output is how bad rows reach your warehouse.

Two schema-design habits raise reliability further. Keep the schema shallow — deeply nested optional structures give the model more ways to be almost right — and put a short description on every field, because those descriptions function as instructions and often matter more than the prompt itself. When a field can legitimately be unknown, model that explicitly (a nullable type or an "unknown" enum member) rather than tempting the model to guess a plausible value to satisfy required.

Governance footnotes for AWS teams

Structured-output requests go through the same POST /v1/messages route as any other call, so the only IAM action involved is aws-external-anthropic:CreateInference. One data-handling detail worth knowing for zero-data-retention (ZDR) organizations: Anthropic documents structured outputs as ZDR-eligible with a qualification — only the JSON schema itself is cached, for up to 24 hours since last use. Your prompts and outputs are not retained under a ZDR arrangement; confirm your contract terms with your Anthropic representative.

Where to go next

The tool-forcing mechanics build directly on Tool Use on Claude Platform on AWS. For the cross-platform view of strict tool use, see the strict tool use guide and the feature matrix.

Sources

← All articles