pydantic-prism

Project one canonical pydantic model along any axis — and keep the relationship graph that survives the projection.

Tag a single model's fields with named scopes; derive real pydantic.BaseModel subclasses per scope (API response, storage row, LLM tool input, audit log) with working validation, serialization, and JSON schema. Declare FK-style references in the same metadata and introspect them through __refs__ — the graph survives every projection. The projection half has prior art; combining it with an introspectable relationship graph does not.

30 seconds

from typing import Annotated
from uuid import UUID

from pydantic_prism import Scope, ScopedModel, scoped


class Public(Scope): ...
class Internal(Public): ...   # Internal sees everything Public sees
class Storage(Internal): ...  # Storage sees everything Internal sees


class User(ScopedModel):
    id: Annotated[UUID, scoped(Public)]
    email: Annotated[str, scoped(Internal)]
    password_hash: Annotated[str, scoped(Storage)]
    display_name: Annotated[str, scoped(Public)]


UserPublic = User.scope(Public)      # fields: id, display_name
UserInternal = User.scope(Internal)  # fields: id, email, display_name
UserStorage = User.scope(Storage)    # all four fields

UserPublic is a real, cached BaseModel subclass named "UserPublic" — User.scope(Public) is User.scope(Public), so FastAPI response models and OpenAPI component schemas stay stable.

Scopes are classes; inheritance forms the scope graph, so the membership rule is one line: a field tagged T is in projection S iff issubclass(S, T). Untagged fields belong to no scope and can never leak into a projection. Scopes compose with set operators (| & - ~), both in field tags and at the call site.

Why not hand-write UserIn / UserOut?

Parallel classes drift from the canonical, lose constraints, and have no idea your models reference each other. Prism derives every face from one source of truth and keeps the references coherent across all of them. See projections, not inheritance.

In fact prism derives those two faces by name: tag read-only fields Out and write-only fields In, then User.input(Public) (a UserIn that drops read-only fields and forbids unknown keys — mass-assignment-safe by shape) and User.output(Public) (a UserOut that never echoes write-only fields). See prevent mass-assignment.

Install

pip install pydantic-prism        # pydantic >= 2.12, Python >= 3.12

Documentation

The docs follow the Diátaxis framework — start where your need fits:

• Documentation home — the full table of contents.
• Tutorial: your first scoped model — one hand-held lesson, one model to two projections.
• How-to guides — short recipes: redact PII, trace data flow, PATCH models, LLM tool schemas, FastAPI, ORM bridge, editor stubs, diagrams.
• Reference — the API, the pydantic-prism CLI, and the error table.
• Explanation — the scope algebra, why projections aren't inheritance, what ref() does and does not model.

ROADMAP.md lists what is shipped, planned, and deliberately out of scope.

Gotchas

• Before-validator ordering. A @scoped_validator(mode="before") runs before a plain @model_validator(mode="before") it inherits from a base (pydantic is child-first), so a child depending on the base hook's transformation sees raw data. prism warns at class definition. Prefer mode="after" (no race); else call run_inherited_before in the validator. See carry a custom base.

Develop

pdm install -G dev
bin/test.sh                       # pytest with coverage (100% gate)
bin/autoformat.sh                 # ruff format + ruff check --fix
pdm run pyright                   # strict, src/

MIT licensed. Built on the public pydantic API only — no pydantic._internal.