Structured Output Schema Builder

Data Contracts for AI: A Technical Guide to Structured Outputs

One of the biggest challenges in building AI-powered applications is reliability. Conversational LLM responses are unpredictable and difficult to integrate with traditional software. Structured Outputs solve this by forcing the model to act as a data-generation engine that follows a strict schema, turning a chat completion into a typed API call.

The Structured Output Schema Builder helps you design these contracts with precision, then export them as JSON Schema, Zod, or Pydantic so they fit wherever your stack lives.

The Role of JSON Schema in LLM Workflows

JSON Schema is the industry-standard blueprint for data. When you send a schema to an LLM via OpenAI's response_format, Anthropic's tools parameter, or Gemini's responseSchema, the model uses it to constrain its vocabulary at the decoder level:

• Strict adherence. The model will not output keys that aren't in your schema.
• Type safety. A field defined as integer is mathematically prevented from being returned as string.
• Required fields. You specify which fields must be present; your code never crashes on missing properties.
• Enums. Closed sets of values become impossible to violate. status defined as ["pending", "active", "cancelled"] cannot return "canceled" (misspelled) or "in_progress" (out of vocabulary).
• Bounded numbers. minimum, maximum, exclusiveMinimum constrain numeric ranges.
• String patterns. pattern: "^[A-Z]{3}-\\d{4}$" rejects non-matching outputs.

This is enforced by constrained decoding, at each token generation step, the decoder filters its vocabulary to only tokens that keep the partial output valid under the schema. The model literally can't produce invalid JSON.

Provider Differences

OpenAI Structured Outputs caveats: Every property must be in required (use ["type", "null"] for optional values). Maximum 100 total properties, 5 levels of nesting, 500 enum values per field. No anyOf with mixed types. No patternProperties or additionalProperties: true.

Anthropic tool use: You define a "tool" whose input schema is what you want extracted. The model "calls the tool" with structured arguments, which is just your output. The tool doesn't have to do anything; you're using the schema enforcement, not the tool execution.

Gemini: Pass responseSchema directly. Similar constraints to OpenAI but more permissive about optional fields.

Best Practices for Schema Design

1. Be descriptive. The description field is your inline prompt to the model:

A field named delivery_date with no description leaves the model guessing the format. The description disambiguates.

2. Use enums aggressively. Free-text fields invite errors. Closed sets eliminate them:

The model cannot return "urgent" or "important", it's constrained to the four values.

3. Keep schemas focused. Large schemas burn tokens and confuse the model. If you need 50 data points, consider:

• Two sequential calls with smaller schemas (extract A first, then B given A's context).
• A two-pass approach: classify which sub-schema applies, then extract under that sub-schema.
• Hierarchical extraction: top-level summary first, then drill down with a second call.

4. Use format hints. JSON Schema format values (date, date-time, email, uri, uuid) are widely recognized by LLMs as additional context, even when not enforced by the validator.

5. Avoid free-form objects. {"type": "object"} with no properties lets the model invent any structure, defeating the purpose. Always specify the shape.

Integration: Zod and Pydantic

Modern frameworks make it easy to bridge AI schemas and runtime code.

Zod (TypeScript):

One schema gives you the runtime validator, the TypeScript type, and the JSON Schema sent to the API. No drift between layers.

Pydantic (Python):

Pydantic is the backbone of LangChain, Instructor, and most Python AI tooling. Field(description=...) becomes the JSON Schema description sent to the model.

Common Patterns

Classification:

Extraction:

Multi-step reasoning with intermediate output:

Asking for reasoning steps in a structured field is a cheap form of chain-of-thought.

Cost and Token Considerations

The schema is sent with every request and counts toward input tokens:

• A schema with 10 well-described fields: ~400-800 tokens.
• A schema with 50 fields and verbose descriptions: 1,500-3,000 tokens.
• A schema with deeply nested objects: can balloon to 5,000+ tokens.

At GPT-4o pricing ($2.50 per 1M input), 1,500 tokens × 10,000 calls = $37.50 in schema-only cost.

Mitigations:

• Prompt caching. Anthropic prompt caching and OpenAI cached input bill repeated content at ~10% normal rate. Keep the schema and system prompt stable so the cache hits.
• Trim descriptions. "The customer's full legal name as it appears on their ID" is great for first-call accuracy. After validation in production, you may be able to shorten to "Customer's legal name" without quality loss.
• Smaller schemas, more calls. Two 500-token schema calls often cost less than one 2000-token schema call, depending on shared input.

Validation as Defense-in-Depth

Even with Structured Outputs, validate on receipt:

1. Schema conformance. Re-validate against your Zod/Pydantic schema. Catches edge cases.
2. Business rule validation. Schema says quantity > 0, but business logic might require quantity <= 10000. Apply both.
3. Sanity checks on numbers. A schema-valid total: 99999999 might be a hallucination. Range-check against context.
4. Retry on failure. If validation fails (rare with Structured Outputs, common with JSON Mode), retry with the error message included: "Your previous response failed validation: {error}. Please try again."

Common Mistakes

• Vague descriptions. "the date" vs "delivery date in ISO-8601 format."
• Free-text where enums would work. Letting status be any string when it has 4 valid values.
• Forgetting required. OpenAI Structured Outputs requires every property in required; omitting is a common silent failure.
• Over-nesting. 6 levels deep, the model gets lost, and OpenAI's 5-level limit blocks you anyway.
• Schema drift. Zod schema and JSON Schema diverging because you maintain them separately. Use one as the source of truth and derive the other.
• Not caching. Sending the same 2,000-token schema on every request without prompt caching enabled.
• Trusting blindly. Structured Outputs guarantees schema conformance, not semantic correctness. The model can still hallucinate values that fit the schema.

Privacy-First Schema Design

Defining your data structure is a sensitive part of your application's architecture. It reveals your database schema, business logic, and data requirements. Many online schema generators store your schemas for "training" or analytics.

The Structured Output Schema Builder runs entirely in your local browser. Your data contracts, field descriptions, and proprietary schemas never leave your machine. Useful when:

• Your schema reflects an unreleased product's data model.
• Field descriptions contain internal terminology or competitive information.
• You're under NDA with a client whose use case is confidential.
• Compliance frameworks (HIPAA, SOC 2) require you to track where schema definitions are processed.

Once defined locally, export to JSON Schema, Zod, or Pydantic and integrate with your API calls of choice. The builder is a design tool, not a middleman.