Pydantic Schema Best Practices for Production Models

Start with the distinction that causes most production bugs: optional versus nullable. An optional field, declared with a default, is simply absent when not provided — the JSON omits the key. A nullable field accepts null as a value. These are not the same thing, and conflating them leaks through to consumers. If "age is unknown" means the field is missing, make it optional; if it means the field is present but explicitly no value, make it nullable. The generator's default handling is deliberate: give a default only when the schema should tolerate absence, and keep the type narrow when absence is invalid.

Constrain fields at the type, not in code. A field that accepts any string but should only accept a country code is a string until a constraint makes it a code. In Pydantic, constraints like min_length, max_length, ge, and le live in the Field(...) specifier, and they flow automatically into the JSON Schema as minLength and minimum. Put the constraint in the model once, and both Python validation and JSON Schema consumers enforce it. Validation near the boundary is cheaper than validation in every consumer.

Prefer narrow, explicit types over wide ones. A list field with no element type accepts a heterogeneous array, which almost never matches reality. Model what the list actually holds — a list of strings, a list of nested objects — so that a mis-typed element fails at the boundary instead of cascading through downstream code. The same principle applies to dict fields: name the value type when you can, and prefer EmailStr and datetime over their looser string counterparts.

Compose small models into larger ones. Rather than a single model with twenty flat fields, define a reusable sub-model for an address or a payment method and nest it as a field type. Nested composition mirrors how real objects are structured, keeps each model reviewable, and gives you one canonical definition to reuse across schemas. The generator's output is ready to combine: each generated class can be imported and embedded as a field type in another class.

Keep the schema backward-compatible as the API evolves. Adding a new optional field is safe — old consumers ignore it and new consumers get a default. Adding a new required field, changing a type, or renaming a field breaks every existing consumer. When you must change a contract, version it rather than mutating it in place. The discipline of reviewing "requiredness" on every new field is the cheapest insurance you can buy against a coordinated deployment.

Treat the JSON Schema as the source of truth for cross-language consumers. Whatever consumes the API — a TypeScript client, a React form, a Java service — should derive its types from the generated schema rather than hand-copying field names. A single exported schema drives client type generation, form builders, and documentation, which eliminates the drift that appears when each layer writes its own copy of the shape.

Write the descriptions as if a stranger must integrate with you. The description on each field is the only documentation many consumers will read; it should state the semantic meaning, the units, and the allowed domain. A description like "the ISO 3166-1 alpha-2 country code of the user's residence" beats "country" in every downstream context — and it becomes the doc text in OpenAPI automatically.

For structured LLM output, apply the strictest version of these rules. When a model response must be parsed into your Pydantic class, every field is a potential hallucination point, so required fields should be truly required, constraints should reject implausible values, and the validator should be the gatekeeper between freeform output and your business logic. A response that fails validation is retried or rejected; a response that passes is guaranteed to match your contract. That guarantee is the entire point of the pattern.

These practices — explicit optional-vs-null, type-level constraints, narrow types, nested composition, backward compatibility, schema-driven clients, and rich descriptions — are the difference between a schema that merely parses and a contract that engineers trust. Build the habit at model design time, because every field decision you make here is inherited by every consumer downstream.

Test the contract the way you test code. Every model deserves a small suite of cases: a valid payload that should parse, a payload missing a required field that should fail, a payload with a wrong type that should fail, and boundary values at the edges of your constraints. Because the failure messages carry the field name and the reason, a failing test tells you exactly where the contract and reality disagree. When you change a schema, run the suite; a change that turns a previously valid payload into a failure is a breaking change, whether or not the type checker notices. For agent projects, this suite doubles as the test of your structured-output contract — feeding the model's actual output through the validator in tests catches the hallucinations and format drift that would otherwise reach production. A schema that is tested is a schema you can evolve with confidence, because the suite will tell you when an update breaks the world.