Structured Outputs

Relevant source files

The following files were used as context for generating this wiki page:

• schemautil.go
• examples/structured-outputs/main.go
• examples/tools-streaming-jsonschema/main.go
• betamessage.go
• betamessage_test.go
• betamessagebatch.go
• tools.md

Structured Outputs is a feature in the Anthropic Go SDK that allows developers to constrain Claude's response to a specific JSON schema. This ensures that the model provides data in a predictable, machine-readable format rather than unstructured text. It is primarily implemented through the OutputFormat parameter in message creation requests and involves transforming standard JSON schemas into a strict format compatible with the Anthropic API.

The system relies on schema transformation utilities and beta-prefixed API parameters to enforce compliance. Users can define schemas using Go structs with tags, which are then reflected into JSON schemas and processed by the SDK to meet strict requirements, such as disabling additional properties and handling specific schema keys.

Sources: schemautil.go:1-35, examples/structured-outputs/main.go:1-50, betamessagebatch.go:570-580

Architecture and Data Flow

The Structured Output flow begins with the definition of a JSON schema, often derived from a Go struct. This schema is passed through a transformation layer that ensures it meets Anthropic's "strict" requirements before being sent to the API.

Schema Transformation Logic

The transformSchema function is the core logic for ensuring compatibility. It performs several critical operations:

• Property Filtering: Only specific keys (e.g., type, properties, required, items, anyOf) are kept in the final schema.
• Strict Objects: For types of "object", additionalProperties is explicitly set to false.
• Logical Simplification: oneOf blocks are converted to anyOf.
• Description Appending: Unsupported properties found in the input are stringified and appended to the description field of the schema to preserve context without violating strictness.

The diagram above illustrates the recursive transformation process used to create a strict JSON schema for the Anthropic API.
Sources: schemautil.go:78-185

Implementation Components

Key Data Structures

Structured outputs are configured using specific parameter types within the Beta message services.

Type	Description	File Reference
BetaJSONOutputFormatParam	Contains the strict JSON schema to be used for the response format.	schemautil.go:34
BetaOutputConfigParam	High-level configuration containing the format and model effort levels.	betamessage.go
BetaToolInputSchemaParam	Schema used specifically for tool input definitions.	schemautil.go:39

API Integration

To request structured output, the OutputFormat or OutputConfig field must be populated in the request parameters. A specific beta header, typically structured-outputs-2025-11-13, is required for the feature to function.

msg, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
    Model:        anthropic.Model("claude-sonnet-4-5"),
    MaxTokens:    1024,
    Messages:     messages,
    OutputFormat: anthropic.BetaJSONSchemaOutputFormat(schemaMap),
    Betas:        []anthropic.AnthropicBeta{"structured-outputs-2025-11-13"},
})

Sources: examples/structured-outputs/main.go:38-44, betamessagebatch.go:570-580

Supported Schema Elements

The SDK enforces a whitelist of supported JSON schema keys. Elements outside this list are moved to the description field during transformation.

Supported Keys

• Top-level: $ref, $defs, type, anyOf, oneOf, description, title
• Objects: properties, additionalProperties, required
• Arrays: items, minItems (limited to 0 or 1)
• Strings: format (restricted to supported types)

Supported String Formats

The SDK supports a specific subset of string formats: date-time, time, date, duration, email, hostname, uri, ipv4, ipv6, and uuid.
Sources: schemautil.go:42-76

Tool-Based Structured Outputs

While the explicit OutputFormat is one way to achieve structured data, the SDK also supports structured outputs through tool definitions. The BetaToolInputSchema function prepares a schema specifically for tools, using the same transformation logic as the general output format.

The sequence diagram shows how the SDK intercepts the schema, transforms it, and then transmits the strict version to the API to ensure a valid structured response.
Sources: schemautil.go:1-35, tools.md:1-50

Schema Utility Functions

The SDK provides helper functions in schemautil.go to simplify the creation of these parameters from standard maps.

• BetaJSONSchemaOutputFormat(map[string]any): Wraps a map-based JSON schema into the BetaJSONOutputFormatParam after applying transformations.
• BetaToolInputSchema(map[string]any): Prepares a schema for use in tool definitions.
• transformSchema(map[string]any): Internal recursive function that applies strictness rules (e.g., setting additionalProperties: false).

Sources: schemautil.go:32-41, schemautil.go:102-120

Conclusion

Structured Outputs in the Anthropic Go SDK provide a robust mechanism for obtaining deterministic JSON responses. By utilizing the transformation utilities in schemautil.go, developers can use familiar JSON schema definitions while the SDK handles the complexities of making those schemas "strict" for Claude. This feature is essential for building reliable integrations where Claude's output serves as input for programmatic systems.