# Pydantic data validation

Pydantic is the library that checks data has the right shape before Connect acts on it. FastAPI uses it to validate every request body. Connect's own modules use it to describe tool arguments and provider payloads, so malformed input is refused with a precise message instead of failing halfway through an action.

- **Status:** Reference
- **Audience:** both, developer
- **Last verified:** 2026-11-02
- **Canonical:** https://connectbyjbrh.com/docs/technology/pydantic/

## What it is

Pydantic is a data-validation library for Python, created by Samuel Colvin. A model is a class with typed fields. Pydantic parses input into it, converting where it safely can and refusing where it cannot, and can emit a JSON Schema for it.

Version 2, released in 2023, moved the validation core into Rust (`pydantic-core`). That made it much faster and changed parts of the API, which is why the version floor matters.

**Category** — Data validation and settings
**Version in Connect** — `pydantic>=2.7`
**Import count** — About 78 imports across `backend/`
**Official site** — [docs.pydantic.dev](https://docs.pydantic.dev/)

## Where Connect uses it

| Place in Connect | What it does there |
|---|---|
| Request bodies | Every FastAPI route that accepts JSON declares a model, and an invalid body becomes a 422 with the field named |
| The `/api/v1` door | Models drive the published OpenAPI document |
| Tools for Connect's Employees and the MCP server | Argument schemas, so a model's tool call is validated before anything runs ([tool calling](/docs/technology/tool-calling/)) |

## How it connects

1. A JSON body arrives
2. Pydantic parses it into the declared model
3. Invalid input becomes a 422 with the field and the reason
4. Valid input reaches the handler as typed Python objects
5. Responses and JSON Schema are generated from the same models

## Benefits and limits

What it gives Connect:

- One declaration gives parsing, validation, documentation and a JSON Schema.
- Errors name the field, which makes a 422 actionable for an integrator.
- The Rust core keeps validation cheap even on large payloads.

Where it stops, and what Connect does about it:

- Shape is not permission. A well-formed request can still be refused by plan, role or approval rules in Connect's own code.
- Coercion can surprise: a string `"1"` becomes the integer `1` unless a field is strict. Fields where that matters are declared strict.
- v1-style code does not run unchanged on v2. The floor pins the v2 behaviour.

## Security and privacy

- Validation at the door stops oversized or wrongly typed input from reaching database or provider calls.
- Tool arguments from a model are validated like any untrusted input, which is one of the defences against [prompt injection](/docs/technology/prompt-injection/).
- Error messages name fields, not stored values.

## Licence, cost and versions

| Question | Answer |
|---|---|
| Licence | MIT |
| Cost | None |
| Version | `pydantic>=2.7` (v2) |
| Compatibility | FastAPI's supported v2 range; Python 3.12 |

## Troubleshooting

**422 on a request that looks right** — Read the `detail` list. It gives the location (`body`, the field) and the reason, often a wrong type or a missing required field.
**`AttributeError` on `.dict()`** — That is v1 API. v2 uses `.model_dump()`.
**A number arrives as text in an export** — Check whether the model declares the field as `str`.

## Official references

- [Pydantic documentation](https://docs.pydantic.dev/latest/)
- [Pydantic v2 migration guide](https://docs.pydantic.dev/latest/migration/)
- [JSON Schema](https://json-schema.org/)

## Questions

### Does Pydantic store data?

No. It validates and converts data in memory. Storage is SQLAlchemy and PostgreSQL.

### Where do I see the schema for an API call?

In the `/api/v1` OpenAPI document, rendered for developers. It is generated from the same Pydantic models that validate the call.

## Related

- [FastAPI and Starlette](https://connectbyjbrh.com/docs/technology/fastapi/)
- [JSON Schema](https://connectbyjbrh.com/docs/technology/json-schema/)
- [Tool calling](https://connectbyjbrh.com/docs/technology/tool-calling/)
- [JSON](https://connectbyjbrh.com/docs/technology/json/)

## What this page is based on

- `requirements.txt`
- `backend/app/saas_registry.py`
- https://docs.pydantic.dev/latest/
