Skip to content

Pydantic SchemaForms

Pydantic SchemaForms logo

PyPI version Downloads Downloads Downloads XERJ Corpus Hub contributor

Support Python Versions

Static Badge Ruff Coverage Status Tests Status Versioning: Year-Quarter-Build

CI/CD Pipeline: Testing - Main Testing - Dev

SonarCloud:

Coverage Maintainability Rating Quality Gate Status Reliability Rating Vulnerabilities


Requires Python 3.14+ — this library uses Python 3.14 language features and will not import on older versions.

Overview

pydantic-schemaforms turns a Pydantic model into a server-rendered HTML form, and validates what comes back with the same model.

from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse

from pydantic_schemaforms import Field, FormModel, html, render_form_html_async


class SignupForm(FormModel):
    name: str = Field(title='Full name', min_length=2)
    email: str = Field(title='Email', ui_element='email')


app = FastAPI()
RENDER_OPTIONS = {'include_framework_assets': True, 'asset_mode': 'cdn'}


@app.get('/signup', response_class=HTMLResponse)
async def show_signup():
    return await render_form_html_async(SignupForm, submit_url='/signup', **RENDER_OPTIONS)


@app.post('/signup', response_class=HTMLResponse)
async def submit_signup(request: Request):
    result = SignupForm.validate(await request.form(), submit_url='/signup', **RENDER_OPTIONS)
    if not result.is_valid:
        return await result.render_with_errors_async()

    name = result.data['name']
    return html(t'<p>Thanks for signing up, {name}!</p>')

That's a complete FastAPI app: a styled signup form, browser and server validation, errors shown next to each field with the user's input kept, and the validated data as a plain dictionary. A Flask version is the same model with render_form_html() and request.form.

Features

  • One model for everything. The form, its validation, the validated data and, with as_api_model(), a typed JSON API all come from one Pydantic class.
  • Inputs from types. str, int, date, bool, Enum, Literal, EmailStr and more pick their input; Field(ui_element=...) chooses any of 40+ others (currency, tags, rating, code editor, file upload, ...).
  • Complex forms by nesting. Sub-forms, optional sub-forms and repeating lists, shown as sections, tabs, columns, an accordion or a step wizard with one layout= argument. Data and errors come back nested like the model.
  • Fields that respond. Show a field only when it applies with ui_show_when, enforced on the server too. Group fields and share rows with ui_group and ui_cols, keeping the data flat.
  • Review pages for free. render_display() shows validated data read-only, with the form's labels and sections, for confirmation pages.
  • Bootstrap, Material Design 3 or plain HTML, with opt-in dark mode for Bootstrap and Material, and assets inlined, linked from a CDN or left to your page.
  • Escaped by construction. All HTML is built with Python 3.14 t-strings and an escaping processor.
  • Accessibility-tested. Every input, layout and error state is checked with axe-core against WCAG 2.0–2.2 A and AA rules on every pull request.
  • More when you need it: live validation over HTMX, CSV import into an editable table, CSRF protection, rule-based validators and plugin hooks for your own inputs.

Install

uv add "pydantic-schemaforms[fastapi]"     # or [flask]
pip install "pydantic-schemaforms[fastapi]"

Requires Python 3.14+ (the library uses t-strings) and Pydantic 2.13+; tested on 3.14 and 3.15. Add the email extra if your forms use EmailStr.

Documentation

The docs at https://devsetgo.github.io/pydantic-schemaforms/ have:

  • Tutorial: from a first form to nested forms, layouts, styling and CSRF protection, with FastAPI and Flask versions of every example.
  • Advanced User Guide: live validation, data tables, JSON APIs, forms built at runtime, assets and plugin hooks.
  • Recipes: complete apps for contact forms, login and registration, edit forms, line items, file uploads, wizards and more.
  • Reference: every input, layout, field option and function.

The live demo shows every input, layout and kind of validation.

Using an AI coding assistant?

The package ships Agent Skills that match the installed version, so assistants don't suggest removed APIs. Install them into your project with library-skills:

uvx library-skills --claude

You get pydantic-schemaforms (build and fix forms), schemaforms-create ("create a login form"), schemaforms-convert (from Pydantic, WTForms, Django or JSON Schema), schemaforms-upgrade (from removed APIs) and schemaforms-document (document your forms). For assistants without skills support, python -m pydantic_schemaforms.ai_instructions claude --write writes the same guidance to CLAUDE.md; see the AI Assistants and Agent Skills page.

Accessibility

axe-core 4.14 runs against every example page, under Bootstrap and Material, in light and dark, and in the error state after a failed submit, and any serious or critical violation fails CI. This is testing, not a compliance claim: conformance depends on your whole application. See the Accessibility reference.

Contributing

Contributions are welcome; see the Contributing Guide and the Roadmap.

git clone https://github.com/devsetgo/pydantic-schemaforms.git
cd pydantic-schemaforms
make install
make tests

License

This project is licensed under the MIT License - see the LICENSE file for details: https://github.com/devsetgo/pydantic-schemaforms/blob/main/LICENSE