Add constraints with the `#[Constrained]` attribute: ```php hidelines={..2} highlight={3}

For schemas that PHP type hints can't express, pass a raw associative array through `OutputConfig::with()`. This path skips the `parsedOutput()` helper; decode the response with `json_decode()`: ```php hidelines={1..3} messages->create( maxTokens: 1024, messages: [ ['role' => 'user', 'content' => 'Extract the key information from this email: John Smith (john@example.com) is interested in our Enterprise plan.'], ], model: 'claude-opus-4-8', outputConfig: OutputConfig::with(format: JSONOutputFormat::with(schema: [ 'type' => 'object', 'properties' => [ 'name' => ['type' => 'string'], 'email' => ['type' => 'string'], 'plan_interest' => ['type' => 'string'], ], 'required' => ['name', 'email', 'plan_interest'], 'additionalProperties' => false, ])), ); $contact = json_decode($message->content[0]->text, associative: true); echo "{$contact['name']} ({$contact['email']})\n"; ```

**`output_config: {format: Model}` with `parsed_output`** Define a model class extending `Anthropic::BaseModel` and pass it as the format to `messages.create()`. The response includes a `parsed_output` attribute with a typed Ruby object. ```ruby hidelines={1..2} require "anthropic" class ContactInfo < Anthropic::BaseModel required :name, String required :email, String required :plan_interest, String end client = Anthropic::Client.new message = client.messages.create( model: "claude-opus-4-8", max_tokens: 1024, messages: [ { role: "user", content: "Extract contact info: John Smith, john@example.com, interested in the Pro plan" } ], output_config: {format: ContactInfo} ) contact = message.parsed_output puts "#{contact.name} (#{contact.email})" ```

The Ruby SDK supports additional model definition features for richer schemas: - **`doc:` keyword:** Add descriptions to fields for more informative schema output - **`Anthropic::ArrayOf[T]`:** Typed arrays. Pass array-level constraints (`min_items:`, `max_items:`) as keywords on `required`/`optional`, not on `ArrayOf` itself - **`Anthropic::EnumOf[:a, :b]`:** Enum fields with constrained values - **`Anthropic::UnionOf[T1, T2]`:** Union types mapped to `anyOf` ```ruby class FamousNumber < Anthropic::BaseModel required :value, Float optional :reason, String, doc: "why is this number mathematically significant?" end class Output < Anthropic::BaseModel required :numbers, Anthropic::ArrayOf[FamousNumber], min_items: 3, max_items: 5 end message = client.messages.create( model: "claude-opus-4-8", max_tokens: 1024, messages: [{role: "user", content: "give me some famous numbers"}], output_config: {format: Output} ) message.parsed_output # => #...]> ```

#### How SDK transformation works The Python, TypeScript, Ruby, and PHP SDKs automatically transform schemas with unsupported features: 1. **Remove unsupported constraints** (for example, `minimum`, `maximum`, `minLength`, `maxLength`) 2. **Update descriptions** with constraint info (for example, "Must be at least 100"), when the constraint is not directly supported with structured outputs 3. **Add `additionalProperties: false`** to all objects 4. **Filter string formats** to supported list only 5. **Validate responses** against your original schema (with all constraints) This means Claude receives a simplified schema, but your code still enforces all constraints through validation. **Example:** A Pydantic field with `minimum: 100` becomes a plain integer in the sent schema, but the SDK updates the description to "Must be at least 100" and validates the response against the original constraint. ### Common use cases

Extract structured data from unstructured text: ```bash CLI ant messages create \ --transform 'content.0.text|@fromstr' --format jsonl <<'YAML' model: claude-opus-4-8 max_tokens: 4096 messages: - role: user content: "Extract invoice data from: Invoice #12345, Date: 2024-01-15, Total: $500.00" output_config: format: type: json_schema schema: type: object properties: invoice_number: {type: string} date: {type: string} total_amount: {type: number} line_items: type: array items: {type: object, additionalProperties: false} customer_name: {type: string} required: [invoice_number, date, total_amount, line_items, customer_name] additionalProperties: false YAML ``` ```python Python hidelines={1} import anthropic from pydantic import BaseModel class Invoice(BaseModel): invoice_number: str date: str total_amount: float line_items: list[dict] customer_name: str client = anthropic.Anthropic() invoice_text = "Invoice #12345, Date: 2024-01-15, Total: $500.00" response = client.messages.parse( model="claude-opus-4-8", max_tokens=4096, output_format=Invoice, messages=[ {"role": "user", "content": f"Extract invoice data from: {invoice_text}"} ], ) print(response.parsed_output) ``` ```typescript TypeScript hidelines={1} import Anthropic from "@anthropic-ai/sdk"; import { z } from "zod"; import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod"; const client = new Anthropic(); const InvoiceSchema = z.object({ invoice_number: z.string(), date: z.string(), total_amount: z.number(), line_items: z.array(z.record(z.string(), z.any())), customer_name: z.string() }); const invoiceText = "Invoice #12345, Date: 2024-01-15, Total: $500.00"; const response = await client.messages.parse({ model: "claude-opus-4-8", max_tokens: 4096, output_config: { format: zodOutputFormat(InvoiceSchema) }, messages: [{ role: "user", content: `Extract invoice data from: ${invoiceText}` }] }); console.log(response.parsed_output); ``` ```csharp C# hidelines={1..4} using System.Text.Json; using Anthropic; using Anthropic.Models.Messages; AnthropicClient client = new(); string invoiceText = "Invoice #12345, Date: 2024-01-15, Total: $500.00"; var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_8, MaxTokens = 4096, OutputConfig = new OutputConfig { Format = new JsonOutputFormat { Schema = new Dictionary { ["type"] = JsonSerializer.SerializeToElement("object"), ["properties"] = JsonSerializer.SerializeToElement(new { invoice_number = new { type = "string" }, date = new { type = "string" }, total_amount = new { type = "number" }, line_items = new { type = "array", items = new { type = "object", additionalProperties = false, }, }, customer_name = new { type = "string" }, }), ["required"] = JsonSerializer.SerializeToElement(new[] { "invoice_number", "date", "total_amount", "line_items", "customer_name" }), ["additionalProperties"] = JsonSerializer.SerializeToElement(false), }, }, }, Messages = [new() { Role = Role.User, Content = $"Extract invoice data from: {invoiceText}" }] }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() invoiceText := "Invoice #12345, Date: 2024-01-15, Total: $500.00" schema := map[string]any{ "type": "object", "additionalProperties": false, "properties": map[string]any{ "invoice_number": map[string]any{"type": "string"}, "date": map[string]any{"type": "string"}, "total_amount": map[string]any{"type": "number"}, "line_items": map[string]any{ "type": "array", "items": map[string]any{ "type": "object", "additionalProperties": false, "properties": map[string]any{ "description": map[string]any{"type": "string"}, "quantity": map[string]any{"type": "number"}, "unit_price": map[string]any{"type": "number"}, }, "required": []string{"description", "quantity", "unit_price"}, }, }, "customer_name": map[string]any{"type": "string"}, }, "required": []string{"invoice_number", "date", "total_amount", "line_items", "customer_name"}, } response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_8, MaxTokens: 4096, OutputConfig: anthropic.OutputConfigParam{ Format: anthropic.JSONOutputFormatParam{ Schema: schema, }, }, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock(fmt.Sprintf("Extract invoice data from: %s", invoiceText))), }, }) if err != nil { log.Fatal(err) } for _, block := range response.Content { switch variant := block.AsAny().(type) { case anthropic.TextBlock: fmt.Println(variant.Text) } } } ``` ```java Java hidelines={1..6} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.StructuredMessage; import com.anthropic.models.messages.StructuredMessageCreateParams; import com.anthropic.models.messages.Model; import com.fasterxml.jackson.annotation.JsonProperty; static class LineItem { @JsonProperty("description") public String description; @JsonProperty("quantity") public int quantity; @JsonProperty("unit_price") public double unitPrice; } static class Invoice { @JsonProperty("invoice_number") public String invoiceNumber; @JsonProperty("date") public String date; @JsonProperty("total_amount") public double totalAmount; @JsonProperty("line_items") public List lineItems; @JsonProperty("customer_name") public String customerName; } void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); String invoiceText = "Invoice #12345, Date: 2024-01-15, Total: $500.00"; StructuredMessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_8) .maxTokens(4096L) .outputConfig(Invoice.class) .addUserMessage("Extract invoice data from: " + invoiceText) .build(); StructuredMessage response = client.messages().create(params); Invoice invoice = response.content().stream() .flatMap(block -> block.text().stream()) .findFirst().orElseThrow().text(); IO.println(invoice.invoiceNumber + ": $" + invoice.totalAmount); } ``` ```php PHP hidelines={1..3} messages->create( maxTokens: 4096, messages: [ ['role' => 'user', 'content' => "Extract invoice data from: $invoiceText"] ], model: 'claude-opus-4-8', outputConfig: ['format' => Invoice::class], ); $invoice = $message->parsedOutput(); if ($invoice instanceof Invoice) { echo "Invoice {$invoice->invoice_number}: \${$invoice->total_amount}\n"; } ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new class LineItem < Anthropic::BaseModel required :description, String required :amount, Float end class Invoice < Anthropic::BaseModel required :invoice_number, String required :date, String required :total_amount, Float required :line_items, Anthropic::ArrayOf[LineItem] required :customer_name, String end invoice_text = "Invoice #12345, Date: 2024-01-15, Total: $500.00" message = client.messages.create( model: "claude-opus-4-8", max_tokens: 4096, output_config: {format: Invoice}, messages: [ {role: "user", content: "Extract invoice data from: #{invoice_text}"} ] ) invoice = message.parsed_output puts "Invoice #{invoice.invoice_number}: $#{invoice.total_amount}" ```

Classify content with structured categories: ```bash CLI ant messages create \ --transform 'content.0.text|@fromstr' --format jsonl <<'YAML' model: claude-opus-4-8 max_tokens: 1024 messages: - role: user content: "Classify this feedback: Great product, fast shipping!" output_config: format: type: json_schema schema: type: object properties: category: type: string confidence: type: number tags: type: array items: type: string sentiment: type: string required: - category - confidence - tags - sentiment additionalProperties: false YAML ``` ```python Python hidelines={1} from anthropic import Anthropic from pydantic import BaseModel client = Anthropic() class Classification(BaseModel): category: str confidence: float tags: list[str] sentiment: str feedback_text = "Great product, but the delivery was slow." response = client.messages.parse( model="claude-opus-4-8", max_tokens=1024, output_format=Classification, messages=[{"role": "user", "content": f"Classify this feedback: {feedback_text}"}], ) print(response.parsed_output) ``` ```typescript TypeScript hidelines={1} import Anthropic from "@anthropic-ai/sdk"; import { z } from "zod"; import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod"; const client = new Anthropic(); const ClassificationSchema = z.object({ category: z.string(), confidence: z.number(), tags: z.array(z.string()), sentiment: z.string() }); const feedbackText = "Great product, but the delivery was slow."; const response = await client.messages.parse({ model: "claude-opus-4-8", max_tokens: 1024, output_config: { format: zodOutputFormat(ClassificationSchema) }, messages: [{ role: "user", content: `Classify this feedback: ${feedbackText}` }] }); console.log(response.parsed_output); ``` ```csharp C# hidelines={1..6} using System.Text.Json; using Anthropic; using Anthropic.Models.Messages; AnthropicClient client = new(); string feedbackText = "Great product, fast shipping!"; var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_8, MaxTokens = 1024, Messages = [new() { Role = Role.User, Content = $"Classify this feedback: {feedbackText}" }], OutputConfig = new OutputConfig { Format = new JsonOutputFormat { Schema = new Dictionary { ["type"] = JsonSerializer.SerializeToElement("object"), ["properties"] = JsonSerializer.SerializeToElement(new { category = new { type = "string" }, confidence = new { type = "number" }, tags = new { type = "array", items = new { type = "string" } }, sentiment = new { type = "string" }, }), ["required"] = JsonSerializer.SerializeToElement(new[] { "category", "confidence", "tags", "sentiment" }), ["additionalProperties"] = JsonSerializer.SerializeToElement(false), }, }, }, }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); ``` ```go Go hidelines={1..14,-1} package main import ( "context" "encoding/json" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() feedbackText := "Great product, fast shipping!" schema := map[string]any{ "type": "object", "properties": map[string]any{ "category": map[string]any{"type": "string"}, "confidence": map[string]any{"type": "number"}, "tags": map[string]any{"type": "array", "items": map[string]any{"type": "string"}}, "sentiment": map[string]any{"type": "string"}, }, "required": []string{"category", "confidence", "tags", "sentiment"}, "additionalProperties": false, } response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_8, MaxTokens: 1024, OutputConfig: anthropic.OutputConfigParam{ Format: anthropic.JSONOutputFormatParam{ Schema: schema, }, }, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock(fmt.Sprintf("Classify this feedback: %s", feedbackText))), }, }) if err != nil { log.Fatal(err) } for _, block := range response.Content { switch variant := block.AsAny().(type) { case anthropic.TextBlock: var result map[string]any json.Unmarshal([]byte(variant.Text), &result) fmt.Println(result) } } } ``` ```java Java hidelines={1..6} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.StructuredMessage; import com.anthropic.models.messages.StructuredMessageCreateParams; import com.anthropic.models.messages.Model; import com.fasterxml.jackson.annotation.JsonProperty; static class Classification { @JsonProperty("category") public String category; @JsonProperty("confidence") public double confidence; @JsonProperty("tags") public List tags; @JsonProperty("sentiment") public String sentiment; } void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); String feedbackText = "Great product, fast shipping!"; StructuredMessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_8) .maxTokens(1024L) .outputConfig(Classification.class) .addUserMessage("Classify this feedback: " + feedbackText) .build(); StructuredMessage response = client.messages().create(params); Classification result = response.content().stream() .flatMap(block -> block.text().stream()) .findFirst().orElseThrow().text(); IO.println(result.category + " (" + result.confidence + ")"); } ``` ```php PHP hidelines={1..3} messages->create( maxTokens: 1024, messages: [ ['role' => 'user', 'content' => "Classify this feedback: {$feedbackText}"] ], model: 'claude-opus-4-8', outputConfig: ['format' => Classification::class], ); $result = $message->parsedOutput(); if ($result instanceof Classification) { echo "{$result->category} ({$result->confidence}): {$result->sentiment}\n"; } ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new class Classification < Anthropic::BaseModel required :category, String required :confidence, Float required :tags, Anthropic::ArrayOf[String] required :sentiment, String end feedback_text = "Great product, fast shipping!" message = client.messages.create( model: "claude-opus-4-8", max_tokens: 1024, output_config: {format: Classification}, messages: [ {role: "user", content: "Classify this feedback: #{feedback_text}"} ] ) puts message.parsed_output ```

Generate API-ready responses: ```bash CLI ant messages create \ --transform 'content.0.text' --raw-output <<'YAML' model: claude-opus-4-8 max_tokens: 1024 output_config: format: type: json_schema schema: type: object properties: status: type: string data: type: object additionalProperties: false errors: type: array items: type: object additionalProperties: false metadata: type: object additionalProperties: false required: - status - data - metadata additionalProperties: false messages: - role: user content: "Process this request: ..." YAML ``` ```python Python hidelines={1} from anthropic import Anthropic from pydantic import BaseModel client = Anthropic() class APIResponse(BaseModel): status: str data: dict errors: list[dict] | None metadata: dict response = client.messages.parse( model="claude-opus-4-8", max_tokens=1024, output_format=APIResponse, messages=[{"role": "user", "content": "Process this request: ..."}], ) print(response.parsed_output) ``` ```typescript TypeScript hidelines={1} import Anthropic from "@anthropic-ai/sdk"; import { z } from "zod"; import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod"; const client = new Anthropic(); const APIResponseSchema = z.object({ status: z.string(), data: z.record(z.string(), z.any()), errors: z.array(z.record(z.string(), z.any())).optional(), metadata: z.record(z.string(), z.any()) }); const response = await client.messages.parse({ model: "claude-opus-4-8", max_tokens: 1024, output_config: { format: zodOutputFormat(APIResponseSchema) }, messages: [{ role: "user", content: "Process this request..." }] }); console.log(response.parsed_output); ``` ```csharp C# hidelines={1..6} using System.Text.Json; using Anthropic; using Anthropic.Models.Messages; AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_8, MaxTokens = 1024, Messages = [new() { Role = Role.User, Content = "Process this request: ..." }], OutputConfig = new OutputConfig { Format = new JsonOutputFormat { Schema = new Dictionary { ["type"] = JsonSerializer.SerializeToElement("object"), ["properties"] = JsonSerializer.SerializeToElement(new { status = new { type = "string" }, data = new { type = "object", additionalProperties = false }, errors = new { type = "array", items = new { type = "object", additionalProperties = false }, }, metadata = new { type = "object", additionalProperties = false }, }), ["required"] = JsonSerializer.SerializeToElement(new[] { "status", "data", "metadata" }), ["additionalProperties"] = JsonSerializer.SerializeToElement(false), }, }, }, }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_8, MaxTokens: 1024, OutputConfig: anthropic.OutputConfigParam{ Format: anthropic.JSONOutputFormatParam{ Schema: map[string]any{ "type": "object", "additionalProperties": false, "properties": map[string]any{ "status": map[string]any{ "type": "string", }, "data": map[string]any{ "type": "object", "additionalProperties": false, }, "errors": map[string]any{ "type": "array", "items": map[string]any{ "type": "object", "additionalProperties": false, }, }, "metadata": map[string]any{ "type": "object", "additionalProperties": false, }, }, "required": []string{"status", "data", "metadata"}, }, }, }, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Process this request: ...")), }, }) if err != nil { log.Fatal(err) } for _, block := range response.Content { switch variant := block.AsAny().(type) { case anthropic.TextBlock: fmt.Println(variant.Text) } } } ``` ```java Java hidelines={1..6} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.StructuredMessage; import com.anthropic.models.messages.StructuredMessageCreateParams; import com.anthropic.models.messages.Model; import com.fasterxml.jackson.annotation.JsonProperty; static class APIData { @JsonProperty("message") public String message; @JsonProperty("resource_id") public String resourceId; } static class APIError { @JsonProperty("code") public String code; @JsonProperty("message") public String message; } static class APIMetadata { @JsonProperty("request_id") public String requestId; @JsonProperty("timestamp") public String timestamp; } static class APIResponse { @JsonProperty("status") public String status; @JsonProperty("data") public APIData data; @JsonProperty("errors") public List errors; @JsonProperty("metadata") public APIMetadata metadata; } void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); StructuredMessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_8) .maxTokens(1024L) .outputConfig(APIResponse.class) .addUserMessage("Process this request: ...") .build(); StructuredMessage response = client.messages().create(params); APIResponse result = response.content().stream() .flatMap(block -> block.text().stream()) .findFirst().orElseThrow().text(); IO.println(result.status); } ``` ```php PHP hidelines={1..3} messages->create( maxTokens: 1024, messages: [ ['role' => 'user', 'content' => 'Process this request: ...'] ], model: 'claude-opus-4-8', outputConfig: ['format' => APIResponse::class], ); $result = $message->parsedOutput(); if ($result instanceof APIResponse) { echo "{$result->status}: {$result->data->message}\n"; } ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new class Payload < Anthropic::BaseModel required :message, String end class APIError < Anthropic::BaseModel required :code, String required :detail, String end class Metadata < Anthropic::BaseModel required :request_id, String end class APIResponse < Anthropic::BaseModel required :status, String required :data, Payload optional :errors, Anthropic::ArrayOf[APIError] required :metadata, Metadata end message = client.messages.create( model: "claude-opus-4-8", max_tokens: 1024, output_config: {format: APIResponse}, messages: [ {role: "user", content: "Process this request: ..."} ] ) puts message.parsed_output ```

## Strict tool use For enforcing JSON Schema compliance on tool inputs with grammar-constrained sampling, see [Strict tool use](/docs/en/agents-and-tools/tool-use/strict-tool-use). ## Using both features together JSON outputs and strict tool use solve different problems and work together: - **JSON outputs** control Claude's response format (what Claude says) - **Strict tool use** validates tool parameters (how Claude calls your functions) When combined, Claude can call tools with guaranteed-valid parameters AND return structured JSON responses. This is useful for agentic workflows where you need both reliable tool calls and structured final outputs. ```bash CLI nocheck ant messages create <<'YAML' model: claude-opus-4-8 max_tokens: 1024 messages: - role: user content: Help me plan a trip to Paris departing May 15, 2026 # JSON outputs: structured response format output_config: format: type: json_schema schema: type: object properties: summary: type: string next_steps: type: array items: type: string required: [summary, next_steps] additionalProperties: false # Strict tool use: guaranteed tool parameters tools: - name: search_flights strict: true input_schema: type: object properties: destination: type: string date: type: string format: date required: [destination, date] additionalProperties: false YAML ``` ```python Python hidelines={1..4} import anthropic client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-4-8", max_tokens=1024, messages=[ { "role": "user", "content": "Help me plan a trip to Paris departing May 15, 2026", } ], # JSON outputs: structured response format output_config={ "format": { "type": "json_schema", "schema": { "type": "object", "properties": { "summary": {"type": "string"}, "next_steps": {"type": "array", "items": {"type": "string"}}, }, "required": ["summary", "next_steps"], "additionalProperties": False, }, } }, # Strict tool use: guaranteed tool parameters tools=[ { "name": "search_flights", "strict": True, "input_schema": { "type": "object", "properties": { "destination": {"type": "string"}, "date": {"type": "string", "format": "date"}, }, "required": ["destination", "date"], "additionalProperties": False, }, } ], ) print(response) ``` ```typescript TypeScript hidelines={1..4} import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const response = await client.messages.create({ model: "claude-opus-4-8", max_tokens: 1024, messages: [{ role: "user", content: "Help me plan a trip to Paris departing May 15, 2026" }], // JSON outputs: structured response format output_config: { format: { type: "json_schema", schema: { type: "object", properties: { summary: { type: "string" }, next_steps: { type: "array", items: { type: "string" } } }, required: ["summary", "next_steps"], additionalProperties: false } } }, // Strict tool use: guaranteed tool parameters tools: [ { name: "search_flights", description: "Search for available flights to a destination on a specific date", strict: true, input_schema: { type: "object", properties: { destination: { type: "string" }, date: { type: "string", format: "date" } }, required: ["destination", "date"], additionalProperties: false } } ] }); // Claude may call the tool first (tool_use) or respond with JSON (text) console.log("Stop reason:", response.stop_reason); for (const block of response.content) { if (block.type === "tool_use") { console.log(`Tool call: ${block.name}(${JSON.stringify(block.input)})`); } else if (block.type === "text") { console.log("Response:", block.text); } } ``` ```csharp C# hidelines={1..6} using System.Text.Json; using Anthropic; using Anthropic.Models.Messages; AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus4_8, MaxTokens = 1024, Messages = [new() { Role = Role.User, Content = "Help me plan a trip to Paris departing May 15, 2026" }], // JSON outputs: structured response format OutputConfig = new OutputConfig { Format = new JsonOutputFormat { Schema = new Dictionary { ["type"] = JsonSerializer.SerializeToElement("object"), ["properties"] = JsonSerializer.SerializeToElement(new { summary = new { type = "string" }, next_steps = new { type = "array", items = new { type = "string" } }, }), ["required"] = JsonSerializer.SerializeToElement(new[] { "summary", "next_steps" }), ["additionalProperties"] = JsonSerializer.SerializeToElement(false), }, }, }, // Strict tool use: guaranteed tool parameters Tools = [ new Tool { Name = "search_flights", Strict = true, InputSchema = new InputSchema(new Dictionary { ["properties"] = JsonSerializer.SerializeToElement(new Dictionary { ["destination"] = new { type = "string" }, ["date"] = new { type = "string", format = "date" }, }), ["required"] = JsonSerializer.SerializeToElement(new[] { "destination", "date" }), ["additionalProperties"] = JsonSerializer.SerializeToElement(false), }), } ], }; var message = await client.Messages.Create(parameters); Console.WriteLine(message); ``` ```go Go hidelines={1..11,-1} package main import ( "context" "fmt" "log" "github.com/anthropics/anthropic-sdk-go" ) func main() { client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus4_8, MaxTokens: 1024, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Help me plan a trip to Paris departing May 15, 2026")), }, // JSON outputs: structured response format OutputConfig: anthropic.OutputConfigParam{ Format: anthropic.JSONOutputFormatParam{ Schema: map[string]any{ "type": "object", "additionalProperties": false, "properties": map[string]any{ "summary": map[string]any{"type": "string"}, "next_steps": map[string]any{"type": "array", "items": map[string]any{"type": "string"}}, }, "required": []string{"summary", "next_steps"}, }, }, }, // Strict tool use: guaranteed tool parameters Tools: []anthropic.ToolUnionParam{ {OfTool: &anthropic.ToolParam{ Name: "search_flights", Strict: anthropic.Bool(true), InputSchema: anthropic.ToolInputSchemaParam{ Properties: map[string]any{ "destination": map[string]any{"type": "string"}, "date": map[string]any{"type": "string", "format": "date"}, }, Required: []string{"destination", "date"}, ExtraFields: map[string]any{ "additionalProperties": false, }, }}}, }, }) if err != nil { log.Fatal(err) } fmt.Println(response.Content) } ``` ```java Java hidelines={1..12,53} import com.anthropic.client.AnthropicClient; import com.anthropic.client.okhttp.AnthropicOkHttpClient; import com.anthropic.core.JsonValue; import com.anthropic.models.messages.JsonOutputFormat; import com.anthropic.models.messages.Message; import com.anthropic.models.messages.MessageCreateParams; import com.anthropic.models.messages.Model; import com.anthropic.models.messages.OutputConfig; import com.anthropic.models.messages.Tool; import com.anthropic.models.messages.Tool.InputSchema; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); // JSON outputs: structured response format JsonOutputFormat.Schema outputSchema = JsonOutputFormat.Schema.builder() .putAdditionalProperty("type", JsonValue.from("object")) .putAdditionalProperty("properties", JsonValue.from(Map.of( "summary", Map.of("type", "string"), "next_steps", Map.of("type", "array", "items", Map.of("type", "string")) ))) .putAdditionalProperty("required", JsonValue.from(List.of("summary", "next_steps"))) .putAdditionalProperty("additionalProperties", JsonValue.from(false)) .build(); // Strict tool use: guaranteed tool parameters InputSchema toolSchema = InputSchema.builder() .properties(JsonValue.from(Map.of( "destination", Map.of("type", "string"), "date", Map.of("type", "string", "format", "date") ))) .putAdditionalProperty("required", JsonValue.from(List.of("destination", "date"))) .putAdditionalProperty("additionalProperties", JsonValue.from(false)) .build(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_4_8) .maxTokens(1024L) .addUserMessage("Help me plan a trip to Paris departing May 15, 2026") .outputConfig(OutputConfig.builder() .format(JsonOutputFormat.builder().schema(outputSchema).build()) .build()) .addTool(Tool.builder() .name("search_flights") .description("Search for available flights to a destination on a specific date") .strict(true) .inputSchema(toolSchema) .build()) .build(); Message response = client.messages().create(params); IO.println(response); } ``` ```php PHP hidelines={1..3} messages->create( maxTokens: 1024, messages: [ ['role' => 'user', 'content' => 'Help me plan a trip to Paris departing May 15, 2026'] ], model: 'claude-opus-4-8', // JSON outputs: structured response format outputConfig: ['format' => TripPlan::class], // Strict tool use: guaranteed tool parameters tools: [ [ 'name' => 'search_flights', 'strict' => true, 'input_schema' => [ 'type' => 'object', 'properties' => [ 'destination' => ['type' => 'string'], 'date' => ['type' => 'string', 'format' => 'date'] ], 'required' => ['destination', 'date'], 'additionalProperties' => false ] ] ], ); // Claude may call the tool first (tool_use) or respond with JSON (text) $plan = $message->parsedOutput(); if ($plan instanceof TripPlan) { echo $plan->summary, "\n"; } elseif ($toolUse = array_find($message->content, fn($block) => $block instanceof ToolUseBlock)) { echo "Tool call: {$toolUse->name}(", json_encode($toolUse->input), ")\n"; } ``` ```ruby Ruby hidelines={1..2} require "anthropic" client = Anthropic::Client.new message = client.messages.create( model: "claude-opus-4-8", max_tokens: 1024, messages: [ {role: "user", content: "Help me plan a trip to Paris departing May 15, 2026"} ], # JSON outputs: structured response format output_config: { format: { type: :json_schema, schema: { type: "object", properties: { summary: {type: "string"}, next_steps: {type: "array", items: {type: "string"}} }, required: ["summary", "next_steps"], additionalProperties: false } } }, # Strict tool use: guaranteed tool parameters tools: [ { name: "search_flights", strict: true, input_schema: { type: "object", properties: { destination: {type: "string"}, date: {type: "string", format: "date"} }, required: ["destination", "date"], additionalProperties: false } } ] ) puts message ``` ## Important considerations ### Grammar compilation and caching Structured outputs use constrained sampling with compiled grammar artifacts. This introduces some performance characteristics to be aware of: - **First request latency:** The first time you use a specific schema, there is additional latency while the grammar compiles - **Automatic caching:** Compiled grammars are cached for 24 hours from last use, making subsequent requests much faster - **Cache invalidation:** The cache is invalidated if you change: - The JSON schema structure - The set of tools in your request (when using both structured outputs and tool use) - Changing only `name` or `description` fields does not invalidate the cache ### Prompt modification and token costs When using structured outputs, Claude automatically receives an additional system prompt explaining the expected output format. This means: - Your input token count is slightly higher - The injected prompt costs you tokens like any other system prompt - Changing the `output_config.format` parameter will invalidate any [prompt cache](/docs/en/build-with-claude/prompt-caching) for that conversation thread ### JSON Schema limitations Structured outputs support standard JSON Schema with some limitations. Both JSON outputs and strict tool use share these limitations.

- All basic types: object, array, string, integer, number, boolean, null - `enum` (strings, numbers, bools, or nulls only - no complex types) - `const` - `anyOf` and `allOf` (with limitations - `allOf` with `$ref` not supported) - `$ref`, `$def`, and `definitions` (external `$ref` not supported) - `default` property for all supported types - `required` and `additionalProperties` (must be set to `false` for objects) - String formats: `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `uri`, `ipv4`, `ipv6`, `uuid` - Array `minItems` (only values 0 and 1 supported)

- Recursive schemas - Complex types within enums - External `$ref` (for example, `'$ref': 'http://...'`) - Numerical constraints (`minimum`, `maximum`, `multipleOf`, etc.) - String constraints (`minLength`, `maxLength`) - Array constraints beyond `minItems` of 0 or 1 - `additionalProperties` set to anything other than `false` If you use an unsupported feature, you'll receive a 400 error with details.

**Supported regex features:** - Full matching (`^...$`) and partial matching - Quantifiers: `*`, `+`, `?`, simple `{n,m}` cases - Character classes: `[]`, `.`, `\d`, `\w`, `\s` - Groups: `(...)` **NOT supported:** - Backreferences to groups (for example, `\1`, `\2`) - Lookahead/lookbehind assertions (for example, `(?=...)`, `(?!...)`) - Word boundaries: `\b`, `\B` - Complex `{n,m}` quantifiers with large ranges Simple regex patterns work well. Complex patterns may result in 400 errors.

The Python, TypeScript, Ruby, and PHP SDKs can automatically transform schemas with unsupported features by removing them and adding constraints to field descriptions. See [SDK-specific methods](#sdk-specific-methods) for details. ### Property ordering When using structured outputs, properties in objects maintain their defined ordering from your schema, with one important caveat: **required properties appear first, followed by optional properties**. For example, given this schema: ```json { "type": "object", "properties": { "notes": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "age": { "type": "integer" } }, "required": ["name", "email"], "additionalProperties": false } ``` The output will order properties as: 1. `name` (required, in schema order) 2. `email` (required, in schema order) 3. `notes` (optional, in schema order) 4. `age` (optional, in schema order) This means the output might look like: ```json { "name": "John Smith", "email": "john@example.com", "notes": "Interested in enterprise plan", "age": 35 } ``` If property order in the output is important to your application, mark all properties as required, or account for this reordering in your parsing logic. ### Invalid outputs While structured outputs guarantee schema compliance in most cases, there are scenarios where the output may not match your schema: **Refusals** (`stop_reason: "refusal"`) Claude maintains its safety and helpfulness properties even when using structured outputs. If Claude refuses a request for safety reasons: - The response has `stop_reason: "refusal"` - You'll receive a 200 status code - You'll be billed for the tokens generated - The output may not match your schema because the refusal message takes precedence over schema constraints **Token limit reached** (`stop_reason: "max_tokens"`) If the response is cut off due to reaching the `max_tokens` limit: - The response has `stop_reason: "max_tokens"` - The output may be incomplete and not match your schema - Retry with a higher `max_tokens` value to get the complete structured output ### Schema complexity limits Structured outputs work by compiling your JSON schemas into a grammar that constrains Claude's output. More complex schemas produce larger grammars that take longer to compile. To protect against excessive compilation times, the API enforces several complexity limits. #### Explicit limits The following limits apply to all requests with `output_config.format` or `strict: true`: | Limit | Value | Description | |-------|-------|-------------| | Strict tools per request | 20 | Maximum number of tools with `strict: true`. Non-strict tools don't count toward this limit. | | Optional parameters | 24 | Total optional parameters across all strict tool schemas and JSON output schemas. Each parameter not listed in `required` counts toward this limit. | | Parameters with union types | 16 | Total parameters that use `anyOf` or type arrays (for example, `"type": ["string", "null"]`) across all strict schemas. These are especially expensive because they create exponential compilation cost. | These limits apply to the combined total across all strict schemas in a single request. For example, if you have 4 strict tools with 6 optional parameters each, you'll reach the 24-parameter limit even though no single tool seems complex. #### Additional internal limits Beyond the explicit limits in the preceding table, there are additional internal limits on the compiled grammar size. These limits exist because schema complexity doesn't reduce to a single dimension: features like optional parameters, union types, nested objects, and number of tools interact with each other in ways that can make the compiled grammar disproportionately large. When these limits are exceeded, you'll receive a 400 error with the message "Schema is too complex for compilation." These errors mean the combined complexity of your schemas exceeds what can be efficiently compiled, even if each individual limit in the preceding table is satisfied. As a final stop-gap, the API also enforces a **compilation timeout of 180 seconds**. Schemas that pass all explicit checks but produce very large compiled grammars may hit this timeout. #### Tips for reducing schema complexity If you're hitting complexity limits, try these strategies in order: 1. **Mark only critical tools as strict.** If you have many tools, reserve it for tools where schema violations cause real problems, and rely on Claude's natural adherence for simpler tools. 2. **Reduce optional parameters.** Make parameters `required` where possible. Each optional parameter roughly doubles a portion of the grammar's state space. If a parameter always has a reasonable default, consider making it required and having Claude provide that default explicitly. 3. **Simplify nested structures.** Deeply nested objects with optional fields compound the complexity. Flatten structures where possible. 4. **Split into multiple requests.** If you have many strict tools, consider splitting them across separate requests or sub-agents. For persistent issues with valid schemas, [contact support](https://support.claude.com/en/articles/9015913-how-to-get-support) with your schema definition. ## Data retention Prompts and responses are processed with ZDR when using structured outputs. However, the JSON schema itself is temporarily cached for up to 24 hours since last use for optimization purposes. No prompt or response data is retained beyond the API response. Structured outputs are HIPAA eligible, but **PHI must not be included in JSON schema definitions**. The API compiles JSON schemas into grammars that are cached separately from message content, and these cached schemas do not receive the same PHI protections as prompts and responses. Do not include PHI in schema property names, `enum` values, `const` values, or `pattern` regular expressions. PHI should only appear in message content (prompts and responses), where it is protected under HIPAA safeguards. For ZDR and HIPAA eligibility across all features, see [API and data retention](/docs/en/manage-claude/api-and-data-retention). ## Feature compatibility **Works with:** - **[Batch processing](/docs/en/build-with-claude/batch-processing):** Process structured outputs at scale with 50% discount - **[Token counting](/docs/en/build-with-claude/token-counting):** Count tokens without compilation - **[Streaming](/docs/en/build-with-claude/streaming):** Stream structured outputs like normal responses - **Combined usage:** Use JSON outputs (`output_config.format`) and strict tool use (`strict: true`) together in the same request **Incompatible with:** - **[Citations](/docs/en/build-with-claude/citations):** Citations require interleaving citation blocks with text, which conflicts with strict JSON schema constraints. Returns 400 error if citations enabled with `output_config.format`. - **Message Prefilling:** Incompatible with JSON outputs **Grammar scope:** Grammars apply only to Claude's direct output, not to tool use calls, tool results, or thinking tags (when using [Extended Thinking](/docs/en/build-with-claude/extended-thinking)). Grammar state resets between sections, allowing Claude to think freely while still producing structured output in the final response.