Structured Output

The --json-schema flag forces Claude to return data matching an exact JSON schema. This is not prompt engineering — it uses constrained decoding at the token level, which means the output is guaranteed to conform to your schema. It is the single most underestimated feature of the CLI for data extraction, classification, and API integration.

Basic Schema

Pass a JSON Schema string to --json-schema alongside --output-format json. Claude will return a response envelope with a structured_output field containing the schema-conforming data.

Schema in, structured data out. No parsing regex, no “please respond in JSON” prompting. The structured_output field contains the extracted data with correct types — age is the integer 32, not the string "32".

Complex Schemas

Schemas can contain nested objects, arrays, enums, and description hints. The constrained decoding guarantee holds regardless of schema complexity.

Arrays of Objects

Enum Constraints for Classification

Use enum to restrict a field to a fixed set of values. Combined with constrained decoding, this turns Claude into a deterministic classifier:

{
  "type": "object",
  "properties": {
    "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral"] },
    "confidence": { "type": "number" }
  },
  "required": ["sentiment", "confidence"]
}

Claude can only produce one of the three enum values for sentiment. There is no possibility of a hallucinated fourth option.

Description Hints

Add description fields to guide extraction without changing the schema structure. This is especially useful when field names alone are ambiguous:

{
  "type": "object",
  "properties": {
    "action_items": {
      "type": "array",
      "description": "List of concrete next steps mentioned in the meeting notes",
      "items": {
        "type": "object",
        "properties": {
          "task": { "type": "string", "description": "The specific action to take" },
          "owner": { "type": "string", "description": "Person responsible" },
          "deadline": { "type": "string", "description": "ISO 8601 date if mentioned, otherwise empty string" }
        },
        "required": ["task", "owner", "deadline"]
      }
    }
  },
  "required": ["action_items"]
}

Schema Design Tips

• Use required liberally. Any field not listed in required may be omitted. Put everything in required unless you genuinely want optional fields.
• Use enum for classification. Sentiment, severity, category — anything with a finite set of values belongs in an enum.
• Use description to guide extraction. The model reads these hints during generation. A well-written description is often more effective than a longer prompt.
• Keep schemas as flat as possible. Deep nesting costs more tokens to compile and generate. If your schema has more than three levels of nesting, consider restructuring.

result vs structured_output

When using --json-schema, the JSON envelope gains a new top-level field. Understanding which field to read is critical.

These two fields are independent. Claude may provide a text explanation in result AND structured data in structured_output, or result may be empty. The behavior is inconsistent between calls — sometimes both are populated, sometimes only structured_output. Your parser should always read structured_output for the data and treat result as an optional bonus.

In the basic entity extraction example above, result was an empty string. But in the array example, Claude provided both a human-readable summary in result and the structured array in structured_output:

Constrained Decoding

Unlike prompt-based approaches (“respond in JSON format”), --json-schema uses grammar-based constrained decoding. At each token generation step, the model can only produce tokens that keep the output valid against the schema. This is not post-processing or validation — it happens during generation itself.

The practical implications:

• 100% compliance — the output always matches the schema, every time, without exception
• No hallucinated fields — only declared properties appear in the output
• Correct types — integers are integers, strings are strings, arrays are arrays
• Required fields guaranteed — every field listed in required will be present
• Enum enforcement — values are restricted to exactly the options you specify

This is what separates --json-schema from asking Claude to “please return JSON.” With prompt engineering, you get ~95% compliance and need to handle parse failures. With constrained decoding, you get 100% compliance and can skip the error handling entirely.

The tradeoff is that complex schemas cost more tokens. The schema itself gets compiled into a grammar, and a schema with 20 nested objects takes longer to compile and generates more output tokens than a flat 3-field schema. For most use cases the difference is negligible, but it is worth knowing if you are processing thousands of documents with a deeply nested schema.

Use Cases

Structured output unlocks a category of workflows that are impossible with plain text responses:

1. Data extraction — pull structured fields from unstructured text (emails, PDFs, logs)
2. Classification — sentiment, category, priority level with enum constraints
3. Code review — structured review output with severity, file, line number, and suggestion
4. Form filling — extract form fields from natural language input
5. API response generation — guarantee your Claude-powered API returns valid, typed responses
6. Batch processing — extract the same fields from hundreds of documents with consistent output

For a complete parsing example in Node.js, including error handling and schema construction, see the source guide.