schema-authority

schema-authority

Core principle: one definition is the truth. Everything else — types, validators, docs, mocks, test fixtures, client SDKs — is derived from it. Never write the same shape twice.

If two places describe the same data, one of them is already wrong and you just don't know it yet.

1) Pydantic as canonical model → derive everything

# models/article.py  ←  THE truth. Touch this file, regenerate everything else.
from pydantic import BaseModel, Field
from typing import Literal
from datetime import datetime
from uuid import UUID

class ArticleBase(BaseModel):
    title: str = Field(..., min_length=3, max_length=200)
    slug: str  = Field(..., pattern=r"^[a-z0-9-]+$")
    status: Literal["draft", "published", "archived"] = "draft"

class ArticleCreate(ArticleBase):
    body_markdown: str

class ArticleRead(ArticleBase):
    id: UUID
    created_at: datetime
    word_count: int

    model_config = {"from_attributes": True}   # ORM → Pydantic without extra code

FastAPI auto-generates the OpenAPI spec from these models — no separate spec file to maintain.

# main.py
from fastapi import FastAPI
app = FastAPI(title="Content API", version="1.0.0")

@app.post("/articles", response_model=ArticleRead, status_code=201)
async def create_article(body: ArticleCreate, db: AsyncSession = Depends(get_db)):
    ...

Export the spec once, drive everything downstream from it:

# Export spec
curl http://localhost:8000/openapi.json > openapi.json

# Generate TypeScript types (frontend consumes these — never writes its own)
npx openapi-typescript openapi.json -o src/types/api.ts

# Generate a typed fetch client
npx openapi-fetch --input openapi.json --output src/lib/client

2) SQLModel: one class for ORM + API schema

# SQLModel collapses Pydantic model + SQLAlchemy ORM model into one definition.
# The database schema IS the Pydantic schema. Drift is structurally impossible.
from sqlmodel import SQLModel, Field
from typing import Optional
from uuid import UUID, uuid4

class Article(SQLModel, table=True):
    id: UUID = Field(default_factory=uuid4, primary_key=True)
    title: str = Field(index=True, max_length=200)
    slug: str  = Field(unique=True)
    status: str = Field(default="draft")
    body_markdown: str

class ArticleCreate(SQLModel):           # request body — no id, no status
    title: str
    slug: str
    body_markdown: str

class ArticleRead(Article):              # response — full row
    pass