---
title: "Use Zod or Pydantic to define structured · Agent Wranglers"
url: https://agentwranglers.se/playbook/stack/ai-software/zod-or-pydantic
updated: 2026-10-21
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Use Zod or Pydantic to define structured output

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers). Updated 2026-10-21.

For AI agents: [llms.txt](https://agentwranglers.se/llms.txt) is a short guide that sends you to the rules your problem needs, and [rules.json](https://agentwranglers.se/playbook/stack/rules.json) holds every rule of this playbook as JSON.

- Level: Recommended
- Chapter: [AI software](https://agentwranglers.se/playbook/stack/ai-software)
- Rule: Define each structured answer once, as a Zod schema in TypeScript or a Pydantic model in Python. Send its JSON Schema to the model and validate the reply with the same definition.
- Applies when: The project it uses AI models.
- Cost: Open source. Both are MIT licensed and free to use in any app.
- How: Zod is MIT licensed. It shipped 1.0 in March 2020 and 4.6.7 on 12 October 2026, with about 207 million weekly npm downloads. Pydantic is MIT licensed. It shipped 1.0 in October 2019 and 2.14.1 on 11 October 2026, with about 243 million weekly PyPI downloads. Both pass all five tests. Zod's `z.toJSONSchema()` and Pydantic's `model_json_schema()` both write JSON Schema draft 2020-12, which the provider SDKs accept. What to ask the model for is in [Ask for output that matches a schema](https://agentwranglers.se/playbook/ai-features/structured-output-and-tools/schema-output). Choose something else when the project uses another language. Then write the schema as a JSON Schema file and check replies with the most downloaded validator for that language.
- Check: Every model call whose answer code reads passes a schema. A unit test feeds the validator one valid reply and one invalid reply, and only the valid one passes.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### TypeScript example

```ts
import * as z from 'zod';

export const Ticket = z.object({
  category: z.enum(['billing', 'delivery', 'other']),
  summary: z.string().max(200),
});

export const ticketJsonSchema = z.toJSONSchema(Ticket);
export const parseTicket = (reply: string) => Ticket.parse(JSON.parse(reply));
```

### Python example

```python
from typing import Literal

from pydantic import BaseModel, Field

class Ticket(BaseModel):
    category: Literal["billing", "delivery", "other"]
    summary: str = Field(max_length=200)

TICKET_JSON_SCHEMA = Ticket.model_json_schema()

def parse_ticket(reply: str) -> Ticket:
    return Ticket.model_validate_json(reply)
```

## Sources

- [JSON Schema draft 2020-12](https://json-schema.org/draft/2020-12)

## Related rules

- [Ask for output that matches a schema](https://agentwranglers.se/playbook/ai-features/structured-output-and-tools/schema-output) in AI features

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/stack/ai-software/zod-or-pydantic">Agent Wranglers software choices playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Use each provider's official SDK to call models](https://agentwranglers.se/playbook/stack/ai-software/official-model-sdk)
- Next: [Use pgvector in PostgreSQL before a separate vector database](https://agentwranglers.se/playbook/stack/ai-software/pgvector-first)
- [AI software](https://agentwranglers.se/playbook/stack/ai-software)