Schema generation

Cadwyn automatically generates versioned schemas and everything related to them from HEAD version at runtime — no code is actually generated. These versioned schemas will be automatically used in requests to and responses from versioned API routes.

Rendering schemas

If you have many versions and schemas, it is quite challenging to know what validators, fields, and other attributes are defined in each schema in a specific version. To address this issue, there is a way to render the generated Pydantic models and enums as code using the command-line interface.

NOTICE that cadwyn render does not guarantee rendering correct schemas. It provides a close enough approximation for manual validation, but it is not yet ready for production code generation. For example, it doesn't handle schema renaming in a class's __bases__ yet.

Rendering a module

Here's a way to render the entire module with the schemas:

cadwyn render module data.schemas --app=main:app --version=2024-05-26

This command prints to stdout how the schemas would look in version 2024-05-26 if they were written by hand rather than generated at runtime by Cadwyn. This command takes the schemas from data/schemas.py module and knows what the schemas would look based on the version changes from Cadwyn app instance named app and located in main.py.

Rendering a single model

Here's a way to render a single Pydantic model or enum with the schemas:

cadwyn render model data.schemas:UserCreateRequest --app=main:app --version=2024-05-26

This command prints to stdout how the UserCreateRequest schema would look in version 2024-05-26 if it was written by hand rather than generated at runtime by Cadwyn. This command takes the UserCreateRequest schema from data/schemas.py module and knows what the schema would look based on the version changes from Cadwyn app instance named app and located in main.py.

Generating schemas without FastAPI

Cadwyn can generate versioned schemas from its version changes even without FastAPI:

import cadwyn
from cadwyn.schema_generation import generate_versioned_models
from my_versions import MyVersionedSchema, version_bundle

schema_generators = generate_versioned_models(version_bundle)
MyVersionedSchemaFrom2025 = schema_generators["2025-11-16"][MyVersionedSchema]