---
name: a2ui-generate-pydantic-models
description: Automated generator for strongly typed Pydantic v2 data models and basic catalogs across any A2UI protocol version (v0.8, v0.9, v0.9.1, v1.0, etc.).
metadata:
  internal: true
title: a2ui-generate-pydantic-models
canonical_url: https://skilld.dev/gh/a2ui-project/a2ui/a2ui-generate-pydantic-models
last_updated: 2026-11-20T00:21:19.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [scripts/__init__.py](https://skilld.dev/api/skills-raw/a2ui-project/a2ui/a2ui-generate-pydantic-models/scripts/__init__.py), [scripts/catalog_generators.py](https://skilld.dev/api/skills-raw/a2ui-project/a2ui/a2ui-generate-pydantic-models/scripts/catalog_generators.py), [scripts/codegen_pydantic.py](https://skilld.dev/api/skills-raw/a2ui-project/a2ui/a2ui-generate-pydantic-models/scripts/codegen_pydantic.py), [scripts/engine.py](https://skilld.dev/api/skills-raw/a2ui-project/a2ui/a2ui-generate-pydantic-models/scripts/engine.py), [scripts/schema_generators.py](https://skilld.dev/api/skills-raw/a2ui-project/a2ui/a2ui-generate-pydantic-models/scripts/schema_generators.py), [scripts/utils.py](https://skilld.dev/api/skills-raw/a2ui-project/a2ui/a2ui-generate-pydantic-models/scripts/utils.py).
>
> If the user asked to install this Skill, run `npx skilld install a2ui-project/a2ui/a2ui-generate-pydantic-models`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/a2ui-generate-pydantic-models`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/a2ui-project/a2ui/a2ui-generate-pydantic-models) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/a2ui-generate-pydantic-models`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/a2ui-generate-pydantic-models --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/a2ui-generate-pydantic-models --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# A2UI Pydantic Model Generation Skill

This skill provides an automated code generation tool that produces strongly typed Pydantic v2 data models and basic catalog definitions for `python/a2ui_core` directly from the schemas and catalogs in `specification/<version>/`.

---

## Agent Execution Steps

When given a prompt like _"Generate Pydantic model classes for A2UI spec v1.0"_:

1. **Extract the target version parameter from the prompt** (e.g. `v1.0` -> `v1.0`).

2. **Execute the generator script exactly once for that target version**:

   ```bash
   uv run python .agents/skills/a2ui-generate-pydantic-models/scripts/codegen_pydantic.py --version <TARGET_VERSION>
   ```

   _(Replace `<TARGET_VERSION>` with the single requested version, e.g. `--version v1.0`)_.

3. **Format generated Python code**:

   ```bash
   cd python/a2ui_core
   uv run pyink .
   ```

4. **Verify the generated files** by running pytest:

   ```bash
   cd python/a2ui_core
   uv run pytest tests/test_codegen_pydantic.py
   ```

5. **Stop and report completion to the user.**

---

## Generated Output Files per Version

When executed for a target version `<version>` (e.g. `v1.0` -> `v1_0`), the script generates:

1. **`python/a2ui_core/src/a2ui/core/schema/<version>/`**:
   - `constants.py`
   - `common_types.py`: strongly typed shared models and the `COMMON_TYPES_DEFS` manifest, which maps each spec `$defs` name to its symbol in spec order. No spec schema is copied verbatim; the published common types schema is rebuilt from these symbols.
     - Type aliases such as `ComponentId`, `Child`, `ChildList` and the `Dynamic*` unions are registered as `Annotated[..., Field(description=...)]` with the spec descriptions, so the runtime JSON schema generator needs no per-def special cases. Dynamic unions list their members in spec order.
     - When a `Dynamic*` def constrains its function-call branch with a `returnType` const, the branch is `Annotated[FunctionCall, ReturnType("<type>")]`, which validates the return type and emits the spec's `allOf` in both modes. Any other branch shape fails generation.
     - Every model extends `SpecBaseModel` (hand-written in `schema/common_types.py`) and has no generated methods. Keywords that fields cannot produce are declared in the model config as `json_schema_extra=SchemaKeywords(...)`: it drops `additionalProperties` where the spec leaves it out and adds `returnType`, `unevaluatedProperties`, `title`, `allowedParents` and `oneOf` required-alternatives (see `_SPEC_KEYWORDS`). The keywords apply only to the declaring model, not to subclasses. `SpecBaseModel` validates a declared `oneOf` whose branches only list required fields (for example `FunctionResponse`'s `value`/`error`), requiring exactly one branch.
     - Only composition that references the catalog's function union is limited to `spec_schema()` (`SchemaKeywords(..., spec_only=True)`), which the published common types schema uses: v0.9's `FunctionCall` `oneOf`, v1.0's `FunctionCall` `allOf` over `FunctionCommon` and `anyFunction` (`replace=True`, since the spec def is pure composition), and v0.9's precise `args` shape (a schema-only `JsonSchemaAs` annotation requested through the `x-python-type` property override). Catalogs keep the flat model shape there. References inside declared keywords are the markers `def_ref("<Def>")` and `catalog_functions()` from the internal `a2ui.core.schema._json_schema` module, which the schema builder resolves to `$ref`s. `FunctionCall` itself is a flat model that validates any call without the catalog.
     - Nested object properties with their own properties become helper models named `<Parent><Property>` (for example `ComponentCommonMetadata`, `IndexSystemFunctionArgs`, `FunctionResponseError`), which schemas inline. Wrapper unions such as `Action` are `TypeAliasType`s, so fields reference them by def name. Each branch gets a `<Def><Property>Wrapper` model, and a branch property that is an object becomes `<Def><Property>` (`ActionEvent`, `ActionEventWrapper`, `ActionFunctionCallWrapper`). A generated name that collides with a def, a base symbol or another helper fails generation.
     - A def that the spec leaves open (no `additionalProperties` and no `unevaluatedProperties: false`) allows extra keys. `ComponentCommon` is the exception (`_SUBCLASSED_DEFS`): generated catalog components subclass it and must stay closed.
     - Optional fields are typed `X | None` so they can be absent. `SpecBaseModel` rejects an explicit null for such a field unless `X` accepts null itself (`Any`), under both the spec name and the Python field name; it does not change the JSON schema. Catalog components inherit this rule through `ComponentCommon`. v0.9's `FunctionCall.args` also rejects null values.
     - Primitive defs such as `CallId` are `TypeAliasType`s, so local references keep their `$ref`. References from other documents to a primitive def map to its Python type through `_CROSS_DOCUMENT_REF_TYPES` in `engine.py`.
     - `patternProperties` objects (`Extensions`) are `TypeAliasType`s over a key-checking validator, and their pattern is published in the spec schema and in catalogs. Python's `re` cannot compile `\p{...}`, so the SDK validates JSON schemas with `a2ui.core.validation.SchemaValidator` (powered by `regex`). The `DynamicValue` literal-object branch carries the spec's `propertyNames` and `not` clauses through a `SchemaKeywords` annotation in both modes.
     - Common types keep `component` properties (`Surface`) and emit required consts without defaults (`skip_component_property` and `required_const_default` on the engine). Spec defaults are emitted as JSON schema `default` values (`schema_defaults`), not as description notes.
     - Common types are generated in strict mode: a schema shape the models would not enforce (an unknown or non-local `$ref`, siblings next to `$ref`/`const`/composition, an unsupported keyword next to `properties`, a required property that is not declared, an empty union) raises instead of loosening validation. Output is deterministic and does not depend on string hashing.
   - `agent_to_renderer.py` / `server_to_client.py`: strongly typed outbound message models and the `AGENT_TO_RENDERER_DEFS` manifest, which maps each spec `$defs` (or v0.8 `properties`) name to its symbol in spec order so `get_agent_to_renderer_schema_map` / `get_agent_to_renderer_schema_json` can rebuild `server_to_client.json` / `agent_to_renderer.json` from the models. Nested payload objects and array item objects become helper models marked with `INLINE_DEF_MARKER` (for example `CreateSurfaceMetadata`, `SurfaceUpdateComponentsItem`), and non-message `$defs` (`Component`, `ComponentsList`) are emitted as `TypeAliasType`s with `SchemaKeywords`.
   - `renderer_to_agent.py` / `client_to_server.py`
   - `renderer_capabilities.py` / `client_capabilities.py`
   - `agent_capabilities.py` / `server_capabilities.py` (when present in spec)
   - `catalog_definition.py` (when present in spec)
   - `__init__.py`

2. **`python/a2ui_core/src/a2ui/core/basic_catalog/<version>/`**:
   - `components.py` (strongly typed components & `ModelComponentApi` registrations)
   - `function_apis.py` (strongly typed function schemas & `FunctionApi` classes)
   - `styles.py` (theme schema, generated when the catalog defines `styles` or an unreferenced `$defs.theme` / `$defs.Theme`)
   - `__init__.py`
   - The models and the generated `BasicCatalog` carry everything `Catalog.to_json()` needs to rebuild the published catalog document from them, with no catalog JSON copied into Python or read at runtime:
     - `BasicCatalog` passes the document's top-level fields to `Catalog`: `$schema`, `$id`, `title`, `description`, `protocolVersion` (None when the document declares none), `catalogId` when it declares none, `instructions`, where it writes its theme (`theme_location`), its unions (`union_defs`, which must list the catalog's entries) and the document its common types references point into (`common_types_uri`). The theme is passed as `theme_model`.
     - Without common types (v0.8), nested objects become models that keep the document's shapes: two nested objects of different shapes never share a model (the later one is prefixed with its component or parent model, for example `SliderValueItem`), and their descriptions stay on the fields, with line breaks, rather than becoming docstrings. `Catalog.to_json()` writes them inline, as the v0.8 document does.
   - For versions with a common types schema (v0.9+), the models carry everything `Catalog.validation_schema` and `Catalog.to_json()` need to rebuild the specification's `catalog.json` shape from them:
     - A component's `allOf` references to common types defs (for example `Checkable`) become base classes, and catalog defs (`CatalogComponentCommon`) become base models. A component with more than one base sets `extra="forbid"`, because Pydantic would otherwise inherit an open base's config. A component description becomes the class docstring and fails generation if it cannot be one.
     - A function's description becomes the `FunctionApi.description` attribute. Keywords on the `args` object that fields cannot produce (`unevaluatedProperties`, `additionalProperties`, required-alternative `anyOf`) are declared with `SchemaKeywords` as the model's `json_schema_extra`, and an unknown keyword fails generation.
     - Field constraints (`minItems`, `minimum`, ...) are emitted as `Field` arguments, so they are validated and published; `format` and `default` are published through `json_schema_extra`. An `allOf` member that only adds keywords becomes a `SpecAllOf` annotation.
   - The conformance cases `test_v08_basic_catalog_to_json`, `test_v09_basic_catalog_to_json` and `test_v10_basic_catalog_to_json`, and `python/a2ui_core/tests/test_basic_catalog_documents.py`, compare `BasicCatalog().to_json()` with the published files, so any drift fails the tests.

3. **`python/a2ui_core/src/a2ui/core/schema/__init__.py`**:
   - Registers the version in `A2uiProtocolVersion` enum and updates envelope unions.
