Skip to content

Usage

Defining a form

A form page is a FormPage, a pydantic.BaseModel subclass. Its fields become the inputs the frontend renders, using either plain Python/Pydantic types or the field types this library provides:

from pydantic_forms.core import FormPage
from pydantic_forms.types import strEnum


class Speed(strEnum):
    _1000 = "1000"
    _10000 = "10000"


class CreateServiceForm(FormPage):
    service_name: str
    service_speed: Speed

Form wizards

A form generator is a function that yields one FormPage subclass at a time. Each yield blocks until the corresponding page’s input has been validated; the validated data is sent back into the generator, and the return value is the combined result once there are no more pages:

from pydantic_forms.types import FormGenerator, State


def create_service_form(state: State) -> FormGenerator:
    user_input = yield CreateServiceForm

    class ConfirmForm(FormPage):
        service_name: str = user_input.service_name

    yield ConfirmForm

    return user_input.model_dump()

You don’t call this generator yourself but register it under a key for start_form to access it, as shown in the next section. Read How it works for details about the machinery.

Registering forms

register_form associates a generator with a key. start_form then resolves that key, seeds the initial state and iterates over the user inputs:

from pydantic_forms.core import register_form, start_form

register_form("create_service", create_service_form)

result = start_form(
    "create_service",
    user_inputs=[
        {"service_name": "svc-1", "service_speed": "1000"},
        {},  # Empty input suffices for the ConfirmForm
    ],
)

The result is whatever the generator returned, with every value already validated and coerced to its annotated type:

>>> result["service_name"]
'svc-1'
>>> result["service_speed"]
<Speed._1000: '1000'>

Omitting the second {} from the user input would produce a FormNotCompleteError.

Async

An async equivalent lives in pydantic_forms.core.asynchronous, with the same post_form, generate_form and start_form functions, for generators defined with async def and yield.

One difference matters: an async generator cannot return a value, so the final result is yielded instead of returned. Writing return user_input.model_dump() in an async def generator is a SyntaxError:

from pydantic_forms.types import FormGeneratorAsync


async def create_service_form(state: State) -> FormGeneratorAsync:
    user_input = yield CreateServiceForm
    yield user_input.model_dump()  # yield, not return

Note the return type: FormGeneratorAsync rather than FormGenerator, since the result is yielded rather than returned.

Register it exactly as above; the endpoint in the next section awaits start_form to drive it.

FastAPI integration

An example endpoint

An example of how you can hook up the form wizard in an API:

from typing import Any

from fastapi import APIRouter

from pydantic_forms.core.asynchronous import start_form

router = APIRouter()


@router.post("/{form_key}")
async def new_form(form_key: str, json_data: list[dict[str, Any]]) -> dict[str, Any]:
    return await start_form(form_key, user_inputs=json_data)

The frontend posts an empty list to get the first page, then re-posts the accumulated inputs after every step until the endpoint returns the validated state. Extra keyword arguments to start_form land in the generator’s initial state.

Error handling

form_error_handler turns FormNotCompleteError and FormValidationError into the JSON responses a frontend expects (see Errors):

from fastapi import FastAPI
from pydantic_forms.exceptions import FormException
from pydantic_forms.exception_handlers.fastapi import form_error_handler

app = FastAPI()
app.add_exception_handler(FormException, form_error_handler)
app.include_router(router)

An unknown form_key raises FormNotFoundError, which the handler reports as a 404.

Page metadata

Sometimes the frontend needs to know something about a page that its JSON schema cannot express. Setting meta__ on a form page attaches arbitrary JSON to the response that carries it:

from typing import ClassVar

from pydantic_forms.types import FormMeta


class ConfirmForm(FormPage):
    meta__: ClassVar[FormMeta] = {"hasNext": False}

    service_name: str

It comes back as .meta on the FormNotCompleteError, and as the meta key of the JSON response:

>>> from pydantic_forms.core import post_form
>>> from pydantic_forms.exceptions import FormNotCompleteError
>>> def confirm_only(state: State) -> FormGenerator:
...     yield ConfirmForm
...     return {}
...
>>> try:
...     post_form(confirm_only, state={}, user_inputs=[])
... except FormNotCompleteError as exc:
...     exc.meta
...
{'hasNext': False}

The value is entirely free-form: this library never looks inside it, it only passes it through, so whatever it holds is a contract between your own backend and frontend. FormMeta documents the well-known keys — hasNext marks whether another page follows, and customButtons relabels or restyles the previous/next buttons — but being total=False, it doesn’t stop a page from adding further keys of its own.

Custom buttons

To relabel or restyle the previous/next buttons of a page, add a field with a ButtonsConfig as its default. Each Button takes a text label and a color; set only the buttons and keys you want to change, and the frontend keeps its defaults for the rest. The config is sent as customButtons in the meta of the page, alongside the rest of its meta__, while the field itself stays out of the schema and the validated result:

from pydantic_forms.validators import Button, ButtonsConfig


class ConfirmButtonsForm(FormPage):
    meta__: ClassVar[FormMeta] = {"hasNext": False}

    custom_buttons: ButtonsConfig = ButtonsConfig(
        previous=Button(text="Back"),
        next=Button(text="Confirm", color="danger"),
    )
    confirm: bool
>>> def buttons_form(state: State) -> FormGenerator:
...     yield ConfirmButtonsForm
...     return {}
...
>>> try:
...     post_form(buttons_form, state={}, user_inputs=[])
... except FormNotCompleteError as exc:
...     exc.meta
...
{'hasNext': False, 'customButtons': {'previous': {'text': 'Back'}, 'next': {'text': 'Confirm', 'color': 'danger'}}}

Or set the same overrides as customButtons in meta__ directly:

class ConfirmMetaForm(FormPage):
    meta__: ClassVar[FormMeta] = {
        "hasNext": False,
        "customButtons": {
            "previous": {"text": "Back"},
            "next": {
                "text": "Confirm",
                "color": "danger",
            },
        },
    }

    confirm: bool
>>> def meta_form(state: State) -> FormGenerator:
...     yield ConfirmMetaForm
...     return {}
...
>>> try:
...     post_form(meta_form, state={}, user_inputs=[])
... except FormNotCompleteError as exc:
...     exc.meta["customButtons"]["next"]
...
{'text': 'Confirm', 'color': 'danger'}

Use one or the other, combining them will result in an error. The same goes for using ButtonsConfig multiple times.

meta__ is a ClassVar, which keeps it out of the generated schema and out of the validated result: it is metadata about the page, not a field on it.

Field layout

By default the frontend stacks every field below the previous one, each taking the full width of the form. Layout places fields next to each other on a 12-column grid. It is Annotated metadata, so it combines freely with other constraints and with Field(...):

from datetime import date
from typing import Annotated

from pydantic import Field

from pydantic_forms.validators import Layout, LongText


class ProfileForm(FormPage):
    # Row 1: three fields side by side, their spans add up to 12
    full_name: Annotated[str, Layout(span=6)]
    age: Annotated[int, Layout(span=3)]
    birth_date: Annotated[date, Layout(span=3)]

    # Row 2 and 3: the comments take two rows on the left half, the next fields fill the right half
    comments: Annotated[LongText, Layout(span=6, row_span=2)] = Field(title="Comments")
    phone: Annotated[str, Layout(span=6)]
    email: Annotated[str, Layout(span=6)]

    # No Layout: a row of its own
    remarks: str

Each option is optional:

Option Default Description
span 12, full width Width of the field in columns, 1-12.
start next free column Column to start at, 1-12. The columns before it stay empty.
new_row False Always start on a new row, even when the current row has space left.
row_span 1 Height of the field in rows. The following fields are placed next to it.
align "stretch" Vertical position within the row: "start", "center", "end" or "stretch".

Layout only adds a layout object to the field’s JSON schema, using camelCase keys and leaving out the options that are not set. It does not change validation:

>>> ProfileForm.model_json_schema()["properties"]["comments"]["layout"]
{'rowSpan': 2, 'span': 6}
>>> class NoticeForm(FormPage):
...     notice: Annotated[str, Layout(span=6, start=7, new_row=True, align="end")]
...
>>> NoticeForm.model_json_schema()["properties"]["notice"]["layout"]
{'align': 'end', 'newRow': True, 'span': 6, 'start': 7}

A field that would not fit on the grid is rejected when the form is defined:

>>> Layout(start=10, span=6)
Traceback (most recent call last):
...
ValueError: start + span exceeds the 12 column grid

Placing the fields is up to the frontend. The pydantic-forms npm package renders the layout on a CSS grid, also inside nested models and list items, where the 12 columns are the width of the nested object. Fields without a Layout take the full width, so existing forms render as before.

Fields whose options come from an endpoint

A Choice carries its options in the schema. Many fields cannot: the customers, locations or ports a person picks from live in another system and are fetched when the form is shown. Until now each client knew, in its own code, which endpoint goes with which format. OptionsSource lets the field type say so itself, so that any client that renders or fills the form reads one description:

from typing import Annotated

from pydantic import BaseModel, Field

from pydantic_forms.core import page_schema
from pydantic_forms.validators import OptionsSource

LocationCode = Annotated[
    str,
    Field(json_schema_extra={"format": "locationCode"}),
    OptionsSource(url="/api/locations"),
]

CustomerId = Annotated[
    str,
    Field(json_schema_extra={"format": "customerId"}),
    OptionsSource(
        url="/api/customers", value="customer_id", label="{fullname} ({shortcode})"
    ),
]


class NewServiceForm(FormPage):
    customer: CustomerId
    contact: Annotated[
        str,
        OptionsSource(
            url="/api/customers/{customer}/contacts",
            value="email",
            label="name",
            depends_on={"customer": "1/customer"},
        ),
    ]
    location: LocationCode

The location codes come back as a list of strings, so each item is both value and label. The customers come back as objects: value names the key that is submitted, label what a person sees, here a template over two keys. The contacts depend on the chosen customer: {customer} in the URL is filled with the value of the customer field beside it, which 1/customer points at, and the client offers no contacts until it has one.

Only url is required:

Option Meaning
url Relative to the API that serves the form, or absolute, query string included. A {name} placeholder in the path or the query string is filled with the value depends_on[name] points at.
search Name of the query parameter that narrows the list on the server. Without it a client fetches the list once and filters it itself.
items JSON pointer to the list inside the response, such as "/data/customers". Without it the response is the list.
value Key of an item that is the field’s value. Without it the item itself is.
label Key of an item, or a {key} template, shown to a person. Without it the value is shown.
depends_on Where each {name} in the URL gets its value while the page is filled in, as a pointer into the page’s data. See below.

The URL carries its own query string, written by the form author the way the route reads it, repeated keys and all. The {name} placeholders are those of a URI Template at its simplest level, so a client percent-encodes the value it fills in. It then appends search when it is declared, and fetches.

OptionsSource only adds an optionsSource object to the field’s JSON schema, with camelCase keys and the options that are not set left out. It does not change validation, and it composes with the format the type already has, with a Layout and with Field(...):

>>> schema = page_schema(NewServiceForm)
>>> schema["properties"]["location"]
{'format': 'locationCode', 'optionsSource': {'url': '/api/locations'}, 'title': 'Location', 'type': 'string'}
>>> schema["properties"]["contact"]["optionsSource"]
{'dependsOn': {'customer': '1/customer'}, 'label': 'name', 'url': '/api/customers/{customer}/contacts', 'value': 'email'}

Pointing at the fields a request needs

Dependencies come in two kinds. A value the form already knows when it builds the page, such as the node chosen on the previous page, is written into the URL by the form author. A value the person chooses on this page is a {name} in the URL, and depends_on says where in the page’s data it is read from: a JSON pointer from the page, or a relative JSON pointer, as published with JSON Schema 2020-12, from the field’s own value. The relative form’s # suffix, which yields a name rather than a value, is not accepted. A pointer is a path, so two fields with the same name at different depths are never confused, and a client never searches for a name:

class Port(BaseModel):
    node: Annotated[int, OptionsSource(url="/api/nodes")]
    port: Annotated[
        int,
        OptionsSource(
            url="/api/nodes/{node}/ports?speed={speed}",
            depends_on={"node": "1/node", "speed": "/service_speed"},
        ),
    ]


class PortsForm(FormPage):
    service_speed: int
    ports: list[Port]

For the port in a row, 1/node goes one level up, to the row, then into its node: the node chosen in that same row. /service_speed starts at the page and reads the speed chosen once for all rows; from inside a row the same field is 3/service_speed, up through the row and the list to the page. Until a row has a node, its port has no options yet.

A placeholder that depends_on does not map, a mapping the URL does not use, and a pointer that is not one are refused when the type is defined. A pointer that points at no field of the page is refused when the page is defined, inside list items and nested models as well. A page that is a plain BaseModel rather than a FormPage is checked when page_schema makes its schema:

>>> OptionsSource(url="/api/nodes/{node}/ports")
Traceback (most recent call last):
...
ValueError: url names ['node'], which depends_on does not map to a field
>>> class ContactForm(FormPage):
...     contact: Annotated[
...         str,
...         OptionsSource(
...             url="/api/customers/{customer}/contacts",
...             depends_on={"customer": "1/customer"},
...         ),
...     ]
...
Traceback (most recent call last):
...
ValueError: ContactForm: /properties/contact fills 'customer' from '1/customer', which points at no field

On a list field the source describes the options of its items; a list of a sourced type, list[LocationCode], carries it on items, and a relative pointer then starts at each item. Fetching is the client’s job: it calls the URL with the person’s credentials and shows label for each item while submitting value. This library takes no dependency on HTTP. A program reading a page gets the sourced fields by their location in the schema from options_sources, see A page for a program.