Skip to content
Home › Prompt Engineering & Structured Output

Structured Outputs ⚠ verify

Prompt Engineering & Structured Output

Definition

Structured Outputs use constrained decoding to guarantee model output conforms to a JSON Schema — via output_config.format with {type:'json_schema', schema} for message output, and Strict Tool Use (strict: true) for tool inputs.

Key points

  • Set output_config.format = {"type": "json_schema", "schema": {...}}. The param moved from output_format → output_config.format (old name works during a transition period). ⚠ verify (2026-07-08)
  • additionalProperties: false is required on every object (both JSON outputs and strict tool schemas).
  • Constrained decoding compiles the schema into a grammar that constrains output token-by-token → always valid (no JSON.parse() errors), type-safe, no retries needed for schema violations.
  • SDK helper client.messages.parse() deserializes into Pydantic / Zod models.
  • Supported: object/array/string/integer/number/boolean/null; enum (strings/numbers/bools/nulls only) and const; anyOf/allOf (allOf with $ref not supported); $ref/$def/definitions; default; required; string formats (date-time, date, email, uri, uuid, ...); minItems only 0 or 1; regex quantifiers/character-classes/groups.
  • NOT supported (→ 400 with details): recursive schemas; complex types in enums; external $ref (e.g. http://...); numeric constraints (minimum/maximum/multipleOf); string length (minLength/maxLength); array constraints beyond minItems 0/1; additionalProperties set to anything but false; regex backreferences/lookaround/word-boundaries.
  • Grammar caching: first request adds compile latency; compiled grammars cached 24h from last use; invalidated when schema structure or tool set changes; changing only name/description does NOT invalidate. Changing output_config.format invalidates the prompt cache for that thread.
  • Combine with Strict Tool Use (same constrained-decoding family).

Why it matters for the exam

  • The mandatory additionalProperties: false and the supported-vs-unsupported schema feature list are heavily tested in Structured Data Extraction scenarios.
  • "Constrained decoding eliminates syntax errors" is the key link to Validation-Retry Loops.

Common gotchas

  • Forgetting additionalProperties: false on any nested object is the classic trap.
  • Reaching for minimum/maxLength/recursive schemas — all unsupported, all 400.
  • Structured outputs kill syntax errors but not semantic ones (still need validation) — see Validation-Retry Loops.

See also

Sources

Referenced by