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":
Extract the target version parameter from the prompt (e.g.
v1.0->v1.0).Execute the generator script exactly once for that target version:
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).Format generated Python code:
cd python/a2ui_core uv run pyink .Verify the generated files by running pytest:
cd python/a2ui_core uv run pytest tests/test_codegen_pydantic.pyStop 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:
python/a2ui_core/src/a2ui/core/schema/<version>/:constants.pycommon_types.py: strongly typed shared models and theCOMMON_TYPES_DEFSmanifest, which maps each spec$defsname 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,ChildListand theDynamic*unions are registered asAnnotated[..., 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 areturnTypeconst, the branch isAnnotated[FunctionCall, ReturnType("<type>")], which validates the return type and emits the spec'sallOfin both modes. Any other branch shape fails generation. - Every model extends
SpecBaseModel(hand-written inschema/common_types.py) and has no generated methods. Keywords that fields cannot produce are declared in the model config asjson_schema_extra=SchemaKeywords(...): it dropsadditionalPropertieswhere the spec leaves it out and addsreturnType,unevaluatedProperties,title,allowedParentsandoneOfrequired-alternatives (see_SPEC_KEYWORDS). The keywords apply only to the declaring model, not to subclasses.SpecBaseModelvalidates a declaredoneOfwhose branches only list required fields (for exampleFunctionResponse'svalue/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'sFunctionCalloneOf, v1.0'sFunctionCallallOfoverFunctionCommonandanyFunction(replace=True, since the spec def is pure composition), and v0.9's preciseargsshape (a schema-onlyJsonSchemaAsannotation requested through thex-python-typeproperty override). Catalogs keep the flat model shape there. References inside declared keywords are the markersdef_ref("<Def>")andcatalog_functions()from the internala2ui.core.schema._json_schemamodule, which the schema builder resolves to$refs.FunctionCallitself 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 exampleComponentCommonMetadata,IndexSystemFunctionArgs,FunctionResponseError), which schemas inline. Wrapper unions such asActionareTypeAliasTypes, so fields reference them by def name. Each branch gets a<Def><Property>Wrappermodel, 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
additionalPropertiesand nounevaluatedProperties: false) allows extra keys.ComponentCommonis the exception (_SUBCLASSED_DEFS): generated catalog components subclass it and must stay closed. - Optional fields are typed
X | Noneso they can be absent.SpecBaseModelrejects an explicit null for such a field unlessXaccepts 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 throughComponentCommon. v0.9'sFunctionCall.argsalso rejects null values. - Primitive defs such as
CallIdareTypeAliasTypes, so local references keep their$ref. References from other documents to a primitive def map to its Python type through_CROSS_DOCUMENT_REF_TYPESinengine.py. patternPropertiesobjects (Extensions) areTypeAliasTypes over a key-checking validator, and their pattern is published in the spec schema and in catalogs. Python'srecannot compile\p{...}, so the SDK validates JSON schemas witha2ui.core.validation.SchemaValidator(powered byregex). TheDynamicValueliteral-object branch carries the spec'spropertyNamesandnotclauses through aSchemaKeywordsannotation in both modes.- Common types keep
componentproperties (Surface) and emit required consts without defaults (skip_component_propertyandrequired_const_defaulton the engine). Spec defaults are emitted as JSON schemadefaultvalues (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 toproperties, 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.
- Type aliases such as
agent_to_renderer.py/server_to_client.py: strongly typed outbound message models and theAGENT_TO_RENDERER_DEFSmanifest, which maps each spec$defs(or v0.8properties) name to its symbol in spec order soget_agent_to_renderer_schema_map/get_agent_to_renderer_schema_jsoncan rebuildserver_to_client.json/agent_to_renderer.jsonfrom the models. Nested payload objects and array item objects become helper models marked withINLINE_DEF_MARKER(for exampleCreateSurfaceMetadata,SurfaceUpdateComponentsItem), and non-message$defs(Component,ComponentsList) are emitted asTypeAliasTypes withSchemaKeywords.renderer_to_agent.py/client_to_server.pyrenderer_capabilities.py/client_capabilities.pyagent_capabilities.py/server_capabilities.py(when present in spec)catalog_definition.py(when present in spec)__init__.py
python/a2ui_core/src/a2ui/core/basic_catalog/<version>/:components.py(strongly typed components &ModelComponentApiregistrations)function_apis.py(strongly typed function schemas &FunctionApiclasses)styles.py(theme schema, generated when the catalog definesstylesor an unreferenced$defs.theme/$defs.Theme)__init__.py- The models and the generated
BasicCatalogcarry everythingCatalog.to_json()needs to rebuild the published catalog document from them, with no catalog JSON copied into Python or read at runtime:BasicCatalogpasses the document's top-level fields toCatalog:$schema,$id,title,description,protocolVersion(None when the document declares none),catalogIdwhen 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 astheme_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_schemaandCatalog.to_json()need to rebuild the specification'scatalog.jsonshape from them:- A component's
allOfreferences to common types defs (for exampleCheckable) become base classes, and catalog defs (CatalogComponentCommon) become base models. A component with more than one base setsextra="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.descriptionattribute. Keywords on theargsobject that fields cannot produce (unevaluatedProperties,additionalProperties, required-alternativeanyOf) are declared withSchemaKeywordsas the model'sjson_schema_extra, and an unknown keyword fails generation. - Field constraints (
minItems,minimum, ...) are emitted asFieldarguments, so they are validated and published;formatanddefaultare published throughjson_schema_extra. AnallOfmember that only adds keywords becomes aSpecAllOfannotation.
- A component's
- The conformance cases
test_v08_basic_catalog_to_json,test_v09_basic_catalog_to_jsonandtest_v10_basic_catalog_to_json, andpython/a2ui_core/tests/test_basic_catalog_documents.py, compareBasicCatalog().to_json()with the published files, so any drift fails the tests.
python/a2ui_core/src/a2ui/core/schema/__init__.py:- Registers the version in
A2uiProtocolVersionenum and updates envelope unions.
- Registers the version in