Architecture¶

datamodel-code-generator is organized around one central idea: many input formats are normalized into a shared generation graph, then rendered through output-model-specific backends.

This page is partly generated from source code. The generated inventory is intentionally small so the narrative can stay hand-written while release-time details such as parser routes and output backends stay synchronized.

Generation Pipeline¶

flowchart TD
    subgraph entry["Entry points"]
        direction TB
        cli["CLI\n__main__.py"]
        api["Python API\ngenerate()"]
    end

    subgraph setup["Configuration and input handling"]
        direction TB
        config["GenerateConfig\nParserConfig"]
        normalize["Input normalization\ninfer / fetch / convert"]
    end

    subgraph parsing["Parsing"]
        direction TB
        parser["Parser.parse()"]
        raw["parse_raw()\nformat-specific parser"]
        model_graph["Generation graph\nDataModel / DataType / Reference"]
    end

    subgraph rendering["Rendering"]
        direction TB
        render["Templates\nmodel/template"]
        format["CodeFormatter"]
        output["Python files\nstdout / return value"]
    end

    cli --> api --> config --> normalize --> parser
    parser --> raw --> model_graph
    parser --> model_graph
    model_graph --> render --> format --> output

The CLI builds a Config from command-line arguments, pyproject.toml, and presets. It then calls the same generate() API that library users can call directly. generate() selects the parser, runs it, and either returns code or writes files. Model Processing Passes lists the passes inside Parser.parse().

Entry Points¶

The executable entry point is defined in pyproject.toml:

datamodel-codegen = "datamodel_code_generator.__main__:main"

src/datamodel_code_generator/__main__.py owns CLI-only behavior:

• fast paths for --version, --help, prompt helpers, and JSON Schema output
• argument parsing and shell completion
• pyproject.toml profile loading and inheritance
• --check diff generation
• --watch regeneration
• structured JSON command output
• --input-model loading before normal generation

src/datamodel_code_generator/__init__.py owns the public generation API:

• generate()
• input type inference
• raw JSON/YAML/CSV/Dict conversion through genson
• MCP tool schema conversion
• parser construction
• generated headers and output file writing
• optional model metadata emission

Parser Model¶

Each parser turns its input into DataModel objects. The parser-specific part is parse_raw(). The shared part is Parser.parse(), which handles sorting, module layout, imports, rendering, exports, formatting, and optional metadata.

flowchart TD
    parse["Parser.parse()"]
    raw["parse_raw()\nimplemented by subclasses"]
    sort["sort_data_models()"]
    modules["_build_module_structure()"]
    process["_process_single_module()"]
    render["_generate_module_output()"]
    metadata["_build_model_metadata()"]
    result["str or module map"]

    parse --> raw --> sort --> modules --> process --> render --> metadata --> result

JSON Schema is the main reusable parser surface. OpenAPI and AsyncAPI extend it. Avro, XML Schema, Protocol Buffers, raw data, and MCP tools convert to a JSON Schema-shaped document before using the same model-building machinery. GraphQL is the main parser that builds models directly from its own schema API.

Ordering and module splitting use small graph helpers. _scc.py finds strongly connected components with an iterative Tarjan traversal so large graphs do not hit Python recursion limits. _graph.py provides stable topological ordering, the stack walk over what some starts reach (reach) and the nodes that reach some seeds (reaching). Together they keep sort_data_models() deterministic and let _build_module_structure() move circular module SCCs into _internal.py forwarder modules when imports would otherwise cycle. _mro.py gives the C3 order of classes and their bases over any item, also without recursion. The passes that read cycles or an order among models (module dependencies, class body order, circular root models, keep model order, alias cycles, nested model default factories, the structs below tagged bases, alias loops) each take a snapshot of one reference graph, _reference_graph.py: the models by model key and the edges between them by kind, which answers their components, orders and loops. The references between models come from the generation store (GenerationIndex.reference_graph). The edges between groups of models, such as the modules of a quotient and the import cycles that the _internal merges check, are a GroupGraph, which answers their components and orders the same way. The predicates that models answer on demand by walking base classes, root types or mapping defaults (inherited fields, ancestors, cyclic ancestry, the C3 order of bases, msgspec struct tags, pydantic protected namespaces, preservable root constraints, recursive dataclass mapping defaults) take a snapshot of the models they reach when asked and answer from it, each model once. Hashability (model/_decisions/hashability.py) reads the chain of each set item model, and of each root model a dict key names, from such a snapshot over base classes.

Generated Inventory¶

Parser Inheritance¶

classDiagram
    JsonSchemaParser <|-- AvroParser
    JsonSchemaParser <|-- OpenAPIParser
    JsonSchemaParser <|-- ProtobufParser
    JsonSchemaParser <|-- XMLSchemaParser
    OpenAPIParser <|-- ApiOpenAPIParser
    OpenAPIParser <|-- AsyncAPIParser
    Parser <|-- GraphQLParser
    Parser <|-- JsonSchemaParser

Input Routes¶

Output Backends¶

Configuration Surface¶

Formatter Names¶

Intermediate Model Graph¶

The generation graph is built from a small set of core objects:

• DataModel: a generated class, root model, type alias, enum, scalar alias, or union alias.
• DataModelFieldBase: one field on a generated model, including defaults, aliases, constraints, and metadata.
• DataType: a Python type annotation tree, including containers, unions, literals, generated-model references, and imports.
• Reference: a schema reference path and generated Python name.
• GenerationStore: the parser-owned model list plus a query index over model and type dependencies.

classDiagram
    class Parser
    class GenerationStore
    class GenerationIndex
    class ModelResolver
    class DataModel
    class DataModelFieldBase
    class DataType
    class Reference

    Parser --> GenerationStore
    Parser --> ModelResolver
    GenerationStore --> GenerationIndex
    GenerationStore --> DataModel
    DataModel --> DataModelFieldBase
    DataModelFieldBase --> DataType
    DataModel --> Reference
    DataType --> Reference
    ModelResolver --> Reference

GenerationStore is the preferred mutation boundary for parser-side changes that affect dependency facts. Parser code should register models and update references, fields, bases, names, and paths through store methods instead of mutating the live objects directly. GenerationIndex keeps stable facts about the model list and gives later phases efficient queries such as "which data types point at this reference?". A refresh records only the models that were appended or that store mutations changed, and rebuilds every fact only when the model list changes otherwise or discard_derived_facts() drops them.

Model Processing Passes¶

Parser.parse() runs a fixed sequence of passes between parse_raw() and rendering. Most of them change models, fields and data types in place, so a fact that one pass reads may still be changed by a later pass. This section lists the passes in execution order, says when each fact becomes final, and shows where a new decision belongs. Paths are relative to src/datamodel_code_generator/; names are given as file:function so they can be found with git grep.

Layers¶

__init__.py:_parse_generation may run L0–L8 again with a fresh parser (root-model collapse that stops before a data type cycle, yielding names that class-keyed options name, untyped nullable maps, invalid dotted stdout modules, and a run that fails after a reference held a document it had prepared as an OpenAPI object of another role, which parses again with every role known at L0: document_roles_to_seed). These are retries around the whole pipeline, not passes inside it.

L0. _load_source_dict calls parser/_schema_documents.py:read_document, which keeps the document as written and, under --use-single-value-enum-as-const, rewrites one-value enum to const copy-on-write, except beside nullable: true when the value is not null (_single_value_enum_as_const, which skips instance-data keywords and extension keys other than x-propertyNames through _document_child_entries). _parse_file then calls _prepare_schema_resources, which adds the document to the schema graph (parser/_schema_graph.py): walk_schema_resources finds which absolute URI names which schema of it (the root, $id or draft-04 id resources, the implicit component resources of OpenAPI, the schemas of the object a reference names the document's root as, $anchor and $dynamicAnchor) and returns one frozen DocumentResources record, from which ResourceRegistry.register fills the registry dicts L1 resolves references through; then $refs that resolve through an embedded $id are rewritten copy-on-write (parser/_schema_documents.py:rewrite_schema_resource_refs), and one walk of the prepared document (SchemaGraphBuilder.index_document, see Metadata Output) indexes the location of every object and makes each $ref and $dynamicRef keyword a ResolvedRef (a str equal to the value, carrying its RefEdge: the holder's location and document; copy-on-write, only at the keywords that hold schemas, never inside instance data, examples, extensions, OAuth scopes, discriminator mappings or unknown keywords; JsonSchemaObject and the OpenAPI ReferenceObject keep the edge through a wrap validator). Referenced documents go through the same steps when resolve_ref loads them: documents enter the graph in the order L1 asks for them, and the graph never loads one by itself. Every reference whose target is static carries an edge: a rewrite of a reference to name its target (canonicalized, lenient or normalized) keeps it (keep_resolved_ref); an object a reference names is read as a schema once (SchemaGraphBuilder.read_as_schema), so a $ref the walk read as data or names there (a nested definitions container) gets one too; schemas converted from another format are mounted with edges to the locations their targets are mounted at (an AsyncAPI payload converted from Protocol Buffers or XML Schema under the internal container of a root the graph owns for its document, SchemaGraphBuilder.mount_root and mount_in, so the loaded document is never written); and a reference the parser derives gets the edge of the reference it stands for (_derived_ref: discriminator mappings and subtypes, x-python-type names, a merged $recursiveRef with a fixed target, an itemSchema projection, an AsyncAPI Reference Object). Only the references of the dynamic-scope rule (parser/_schema_refs.py:dynamic_scope_target: a $recursiveRef, and a plain-name $dynamicRef bound in the dynamic scope or named by the first $dynamicAnchor of its name in the document being parsed) stay plain strings: they resolve against the dynamic scope of the model being parsed, not their own document. Every L1 site takes the key of a reference from its edge (_ref_key, _ref_path): the edge's spelling resolved once, at its first consumption, in the document that holds it (_home_context: its location, root $id and, for an OpenAPI input document or under the api scope, its $self; a schema the parser keeps in a document of its own, an Avro schema of an AsyncAPI document, names that document as its edges' home) through the external mapping, the embedded resource, the normalized spelling and ModelResolver.resolve_ref; a new model is named after that spelling (ModelResolver._add_ref_at). A plain string has no edge and resolves in the context its caller set. A schema copied into another (a merged $ref target, an inherited property) keeps its references as written: a site that asks whether a reference is a fragment of the document parsed now reads its edge (_is_local_ref), and only a merged $recursiveRef with a fixed target is rewritten, to a $ref (parser/_schema_refs.py:pin_recursive_refs). OpenAPI and AsyncAPI register a schema that declares a discriminator, and a component schema whose allOf names one, under the key of the reference that names the schema from its own document (_schema_key), the key the references to it get, whatever document is being parsed when the discriminators are collected. A JSON object of a loaded document is validated once per parse (SchemaGraphBuilder.schema): the targets _load_ref_schema_object, _load_inherited_schema_object and OpenAPI's resolve_object load, the response and request body targets of get_ref_model, and the if, then, else and not branches _get_conditional_schema reads share one object per located value and its type, which no reader writes; DATAMODEL_CODE_GENERATOR_CHECK_SCHEMA_GRAPH, which tests/conftest.py sets for the test suite, compares each shared object at the end of L1 with the fingerprint taken when it was validated (tests/checks/schema_graph.py). The client and server bindings read the schemas of an API document by location, one site per location (ApiOpenAPIParser._site_facts, see Fact Finality), which the same check reads anew at every read. The walks that follow references from a schema (field flags, literal and null checks, inherited properties and overrides, validation sources, uniqueItems rules, merged allOf values) visit each schema graph node once (SchemaNodeId, the location of the object a reference names: _key_node), and a $ref target merged with its sibling keywords is dumped once per node and document being parsed (_ref_target_dump). A local reference whose model a document has not parsed yet is reserved for that document (reserved_refs). _parse_file, _resolve_unparsed_json_pointer and AsyncAPI's _resolve_asyncapi_unparsed_json_pointer take the targets from one worklist (_reserved_targets: a ReservedTarget with the document, the key and the node the key names in the document's prepared tree), in key order, repeating while a round reserves more keys (_parse_file) or adds models (the others), and parse each target from the prepared tree. The $dynamicRef analysis (parser/_schema_refs.py:dynamic_anchors_used, dynamic_ref_edges) and the models specialized for a dynamic scope are keyed by the schema graph node a reference names, so references that spell one schema differently share its analysis and its specialized model. The fallbacks of the dynamic-scope rule still read the anchors L1 has registered so far (_build_anchor_indexes and _parse_file: the root, the definitions and each schema parsed through _parse_raw_or_validated_obj): parser/_schema_refs.py:resolve_dynamic_ref, _resolve_recursive_ref and recursive_ref_target: a $recursiveAnchor below properties is never registered, and an OpenAPI component's $dynamicRef parsed before the component that declares its anchor resolves through its edge instead. OpenAPI parses its main document in _parse_specification (merging path-level parameters into shallow copies of operations in _process_path_items) instead of _parse_file. Converted inputs (Avro, XML Schema, Protocol Buffers) build a JSON Schema dict and call _parse_file without parser/_schema_documents.py:read_document, so document rewrites do not apply to them.

L1. Each place where the parser meets a schema object chooses its parse method from one table of parser/_schema_dispatch.py: _DEFINITION_TABLE in _parse_schema_obj (definitions, roots, reserved targets, AsyncAPI payloads and the api scope), _FIELD_TABLE in parse_item (fields, items and map values) and _OPENAPI_OPERATION_TABLE in OpenAPIParser.parse_schema (the bodies, responses and parameters of the legacy scopes). A table holds, in order, the steps that rewrite the site (a $ref with sibling keywords merged with its target, _merge_ref_with_schema) and the rows whose predicates choose parse_array, parse_all_of, parse_one_of or parse_any_of (both through parse_combined_schema), parse_object, parse_enum, parse_root_type and the other builders; the rows of an object-kind schema (_OBJECT_KIND_ROWS) are shared by the definition table and the object-kind table that _parse_object_kind_schema chooses from. A predicate or builder that rows of several tables share is one module function of parser/jsonschema.py (_array_applies, _parse_root_type_site, ...), which parser/openapi.py imports: a row holds the function itself, and a function of a concern module (parser/_<concern>.py) that takes the parser first is the --debug tracer's wrapper in a module that imports it after snooper_to_methods ran. Rows that differ only in data are one function too, bound to it without a frame of their own: the field rows any-of and one-of are made by _field_union_row for their keyword, and the one-of-any-of rows of definitions and operation schemas are _parse_combined_root, which a definition binds (functools.partial) to read a oneOf or anyOf of consts as its Enum or Literal root model first. Rows call the public hooks through the parser, so overriding subclasses keep working; a change of what a position parses is a row edit. A table also declares what its sites type (TypedChild: the child schemas and the models their types name): DispatchTable.typed_children returns the declaration of the row chosen for a site (Row.typed), else the table's (DispatchTable.typed); the field table's python-type and custom-type rows type nothing, its constrained-item row the root model of the site's schema (TypedChild root: it holds one type and no fields, so an object's properties type nothing, and its additionalProperties type the values of a dict only where _parse_root_type_with_context builds an object map, its rows object-map and typed-nullable-map of _root_type_row, whatever properties the schema holds), its other rows the model of the site's schema, and the definition table's sites what _typed_model_children lists. The row is chosen as parse_item chooses it, after the steps of the table (title-name, ref-siblings) rewrite the site and with the parent parse_item gets (the array of an item, the schema of a oneOf or anyOf member, the schema of an additionalProperties value where the output writes field constraints); a property reads a $ref merged with its siblings before the table chooses (parse_object_fields), so the walk passes the merged site there (typed_children(as_parsed=...)). A oneOf or anyOf member is the branch parse_combined_schema parses (_combined_schema_members: the member mixed with the keywords of its parent, a $ref member merged with its siblings), and an additionalProperties value is what _parse_additional_properties_value builds (_additional_properties_value: the root model of a value with effective constraints, else the site parse_item gets), so the walk reads both from the function that decides them. The request/response split walks a key by asking them (_get_ref_schema_rw_model_reference_facts), not by listing positions itself. DispatchTable.choose returns the chosen row as a Choice and the position's method builds it in its own frame, so a nested schema costs no more stack frames per level than the parse methods it reaches (test_main_nesting_within_recursion_limit fails when it does). A definition written as a $ref whose sibling keywords cannot merge into its circular target gets no model outside a definitions container (the ref row; --openapi-as-definitions ref-components counts the components of an OpenAPI specification as one, OpenAPIParser._definition_entry_prefixes); once every schema is parsed (_end_schema_parsing), the users of its reference move to the reference that $ref names (_type_references_to_definitions_without_model), so a reference to it is typed by its target, as such a $ref is at a field. Then a schema that an allOf base names, that got no model and that a field naming it would be typed by an import, the class --external-ref-mapping imports for a schema of a mapped document or the class x-python-import names (not a type expression in its place), is parsed into a stand-in (_parse_base_stand_ins): its model, parsed in its own document under the reference the base names (parse_json_pointer, past the x-python-import shortcut, and the targets that parse reserves there), in the module of the first model that names it, with the import kept by model key (Parser._base_stand_in_imports). Only that schema is a stand-in: the other models the parse adds are written, as a generated base gives them. A stand-in may name further such bases and definitions parsed as their $ref alone, so the parse and the redirect repeat until no new stand-in appears. Then the import types every other user of a stand-in, one that a reference its document does not map names, as it types a mapped $ref, and the parse adds nothing to the imports every module shares: a stand-in is never written, and the models the parse writes import what their types name. A stand-in never splits into read/write variants (parser/_rw_split.py:get_separate_model_fields, _register_root_model_as), takes part in no reuse (_ReuseOptimizationContext), name uniqueness, module dependency or import (L3, L5 change_from_import), and leaves its module where model-level type overrides remove models; a stand-in of x-python-import is never dropped as a generated root model is (L3 delete_duplicate_models), as the class it declares is the base whatever its schema describes. Once every module is processed, the import replaces the bases that name a stand-in (apply_base_stand_in_imports), so every pass before reads it as a generated base, in every module whatever their order. Then a model that uses a $ref that --external-ref-mapping maps and whose fragment names no schema stops with an error (_reject_mapped_references_without_schema), and the late hook _generate_forced_base_models runs. That merge, the inherited $ref property merge (_resolve_inherited_parent_property) and a property that overrides an inherited one (_merge_properties_with_parent_constraints through _inherited_override_schema, unless --allof-merge-mode none) stand for the intersection of their parts: the earlier merge (parser/_intersection.py: concatenating_row, inherited_override_row) stays wherever it enforces what the intersection enforces, and parser/_intersection.py:intersect_keywords writes the tightest bounds, the least common multipleOf, the common type and enum values, the union of required and a false that a part sets where the merge does not; nested schemas follow the same rule. Where the document's dialect (draft 7 or earlier, OpenAPI 3.0) does not read $ref siblings as parts, a sibling enum that the document writes does not narrow the referenced schema (the legacy sibling enum row; an inherited property override is a part in every dialect). Null comes from the site's own nullable, type list or null value, else only if every part admits it (parser/_null_facts.py, site all-of-parts). A keyword whose parts have no value in common keeps the earlier value and warns (warn_unsatisfiable); pattern, format, tuple positions, combinators and allOf members are not intersected there yet. A oneOf/anyOf of constants can become a synthetic enum (parser/_value_keywords.py:extract_const_enum_from_combined). An enum class takes a value base (IntEnum, StrEnum, --use-subclass-enum's (T, Enum)) only when that base keeps every member value (T(v) == v, NaN equal to itself), and is a plain Enum otherwise (model/_decisions/enum_kind.py:decide_enum_kind). A const that admits some but not all values of the enum beside it leaves every enum class as written; parse_enum records the const for the model it builds (_note_const_narrowing), the end of L1 marks every value that names that model, and L5 type_const_narrowed_values types those values. A Literal enum route (_enum_value_type), a propertyNames key and a Literal root type keep only the admitted values (_const_narrowed_enum); a const equal to none of the values only warns. Under --read-const-beside-enum and --use-single-value-enum-as-const each enum route reads an enum that admits the const beside it as that const, without an enum class (_reads_enum_as_const); like the L0 rewrite, it keeps an enum beside nullable: true and a const other than null, and a model built for the schema object itself then holds only the admitted values (_definition_enum). An object map, an object without properties whose keys and values patternProperties, propertyNames or additionalProperties type, is built by one builder at every position (_parse_object_map): one dict whose value type is the union of the value types of its key classes, never a union of dicts. The dict itself admits the null of a type array of object and null, or of nullable: true under --strict-nullable as _get_data_type does for other types, so property counts stay on it, and the other types of a type array join it in a union. A nullable that parse_combined_schema copies from an anyOf or oneOf parent into a branch is marked on the branch, and the dict of that branch leaves it to the union. Without --use-single-dict-for-object-maps the builder keeps the 0.86.0 forms as its legacy-map-* rows (see "Legacy rows"). Names come from ModelResolver.add. Each model records the location of the schema object it is built from on its Reference (_record_schema_object). Every use of a reference gets a new DataType that points to the one shared Reference. allOf $ref items become base classes; inherited fields whose parent is not parsed yet stay as placeholders that L5 resolves. Discriminators are only captured here (field.extras["discriminator"]), each mapping path with the location the parser resolves it to from the document that declares the mapping (parser/_union_tags.py:located_mapping_paths over the references of discriminator_mapping_refs, which an OpenAPI union built from a mapping reads too); the tag passes match a variant by that location where it is the schema of one (parser/_tag_plan.py:located_mapping). Field construction already decides const handling: DataModelFieldBase.__init__ calls process_const(), which types the const and decides its default and nullability (model/_decisions/literal_default.py). Dataclass-like models (dataclasses, Pydantic dataclasses, msgspec Structs) sort their fields when they are built, by DataModel.FIELD_CONSTRUCTION_ORDER_KEY. The key reads only facts known then: on a Pydantic dataclass, a None default that --strip-default-none may keep counts as no default, while a msgspec Struct counts every optional field as having one, as it never strips its defaults. fix_constructor_field_ordering (parser/_passes/render_prep.py), after the decision phase, decides with the output model's assignment facts (DataModel._field_assignment_facts, the row FIELD_ASSIGNMENT_CHECKER is a view of), which state what the template writes, and moves fields whose default the template keeps after the fields without one. An inherited field that two bases put after a default, which dataclasses rejects while creating the class, gets a keyword-only copy in the class (get_constructor_ordering_conflicts of parser/_passes/_shared.py), whose types name their models from its module.

L2–L4.

Module order is not dependency order: _internal modules of import cycles come first, then the tree-scope shared module, then _group_models_by_module's sort (longest module path first, reverse lexical). Single-file output has one module, so "per module" then means the whole graph.

L5, per module, in this order:

Once every module is processed, write_rule_aliases_as_classes (parser/_passes/modules.py, --generate-schema-validators) writes each type alias that holds schema validator rules and that collapse left written as the RootModel class, under its model key: an alias has no class body for the rules, and whether collapse inlines it into all its holders is final only then. The class imports the models of other modules that its rules name, as change_from_import does for a class. Last, apply_base_stand_in_imports (parser/_passes/modules.py) replaces the bases that name a stand-in (L1) by the import of the class it stands for, as apply_base_class_type_overrides replaces bases: until then the passes of every module read the stand-in as a generated base when they walk the bases of a model of another module, whatever the order of the modules. Then settle_discriminated_unions (parser/_passes/modules.py, Pydantic models and dataclasses) writes no discriminator= for the union of a lone $ref variant that no tag reaches: apply_discriminator_type writes the tags of the variants a union lists, not of one it names alone, and a union of any module may still tag that variant, so a variant without a tag is final only once every module is processed. It writes none either for a lone variant that is no model (a scalar, Any or None, as --collapse-root-models leaves a scalar alias in its holder, or as an inline schema is), which Pydantic rejects as a variant, nor for a union that takes a root model, or a type alias, with a default as a variant (--force-optional gives a root one), as Pydantic reads the root as a default schema, which no tagged union holds; the default is what the root writes (Field(None, ...), the assignment after its annotation, a default factory), not what its facts hold. A type alias that holds the default of its schema writes it only once set_validate_default_on_fields adds validate_default=True to the Field() call, so the check reads the facts that pass reads (validates_structured_default: required state, default, type); under --use-annotated the call holds no default, so the alias writes none.

L6, after the module loop:

Render preparation, for the models each module had at the end of L5:

Then, over every model:

Three L6 passes repair results built from facts that changed afterwards: import_removed_reuse_canonicals and import_renamed_types (reuse and renames in a later module, including the parent collapse rename) and fix_tag_opt_out_field_ordering (constructor ordering counts an opted-out struct's own field named like the tag at the place of the base's tag class variable).

Constructor ordering and render preparation run once, after the decision phase, for every model: ordering reads the facts every module and decision left, and the assignment form of every module, and orders each model after the models it inherits from, so a model's constructor no longer depends on whether the module of its base is processed before or after its own (since 0.87.0). Code that overrides _process_single_module and runs after super() sees the module before its constructor order and render preparation; the generic base class, the decision phase and that render preparation run in the pipeline before _finalize_modules, so an override of _finalize_modules that does not call super() no longer skips them, and a direct call of _finalize_modules no longer applies the generic base class.

Module imports. The passes from L1 to L7 write the imports of a module (ModuleContext.imports) and the imports all modules share (Parser.imports) only through parser/_imports_plan.py:ModuleImportLedger, which applies each write to the live Imports at once and keeps it as an entry with its producer: the pass (ImportPass), and the model and field it wrote for. The live Imports is the replay of its entries (replay). imports.py reads every import the same way: by its module and name (_import_key, the key every alias map uses), a stored X as Y split into the name and the alias kept apart (_stored_import), the module --import-overrides moves a name to (_override_module, never a __future__ name), whether an Imports holds an import or drops every count of it (_holds, _remove_all), the names an import block binds (_iter_import_bindings), and the alias <name>_aliased an import takes where a name of its module hides it (_aliased_name, each caller numbering it by its released row, legacy.alias-order) with the import that binds the identity under it (_aliased_as). How a module imports a model of another module and writes the expression that names it is parser/_passes/_import_binding.py: the rule (reference_import_target, under an ImportPathRow; a model is imported from its module, not through the module its package imports, where the module is named like an import every module shares, such as an --additional-imports name, since the package binds that name too; the import then takes an alias where a shared import binds the model's name as well), the import it adds (register_reference_import), the import of the generated base class, by the same rule (generic_base_class_import), and the writes through the generation store (set_reference_expression, set_reference_expressions, import_references), and the re-import of what a module imported under a stale import (reimport_references: drop it, release the names it leaves, write the expression again, under a ReimportRow named after the pass: collapsed holders, renamed types, removed reuse duplicates); the relative import text it writes, which the forwarders of parser/base.py write too, is _module_paths.py (relative, join_module, exact_import, is_ancestor_package_reference, absolute). The aliases imports take where a field name of the module hides the names they bind are parser/_passes/_import_aliases.py (alias_shadowed_imports), which writes them into every type, runtime expression, additional import and base class that carries the import. The import block that _generate_module_output writes is ModuleImportLedger.rendered: a copy of the live Imports minus what the entries wrote of their models' unrendered imports (DataModel._unrendered_imports), counted as the difference between the replay of the entries and their replay without those imports, so the module lines keep their order and imports written outside the ledger stay. The named row legacy.enum-member-import-bindings uses it: an Enum's imports keep the imports of its member declarations (pydantic's Field for described members), so the module binds their names for class names and reuse keys as in 0.86.0, while the import block leaves them out. The output model's resolve_module_import_conflicts gets the live Imports; ModuleImportLedger.external records what it changed. DATAMODEL_CODE_GENERATOR_CHECK_MODULE_IMPORTS compares each module's imports with the replay of their entries when the import text is written, so a write that bypasses the ledger fails the check, which the test suite turns on. The names the module's ModelResolver gives its imports are asked for through the ledger too (NameLog). After the last rename, tests/checks/module_imports.py plans the models each module names from the final names (NameTable): ModuleImportPlan holds the imports of other modules' models, named by allocate_bindings in the order the module asked for them (row legacy.alias-order), and what the module writes for each model. Nothing is written from the plan yet; under the same check, the module must write what the plan writes and its imports must bind every planned import.

L7. _generate_module_output builds the import block, calls the backend's render_module_code, renders each model and formats the body. It first refuses each relative import block it writes (the module's, the --all-exports-scope exports and a forwarder's, parser/_passes/imports.py:reject_unimportable_imports) that names a module by a part that is a keyword (a directory or file named class) or, under --treat-dot-as-module, not an identifier (1.0 is the packages _1 and 0), which the output would write as a syntax error. It reads the final blocks, so an import a pass dropped (a collapsed root model) is not refused, and it leaves the layout of the modules as released. DataModel.render uses the compiled renderer in model/_compiled_templates/ for built-in templates and Jinja2 when a custom template directory is set. Type-alias styles are chosen when the parser is built (model/__init__.py:get_data_model_types). Rendering a type hint and collecting a field's imports write no nullability: type_hint renders the None of the type, of the nullable model it names and, for a union, of the members whose hints strip it (types.py:DataType._hint_null_source), and import collection reads types.py:DataType.admits_none. Render preparation writes rendered nullability once, in its first pass (parser/_passes/render_prep.py:finalize_rendered_nullability, after the module bodies, whose type-alias updates write the union operators and quotes the members' hints read), through types.py:DataType._materialize_render_state, which marks the None it adds; msgspec's top-level None and the Field() default plan read the value without it (legacy-msgspec-top-level-null-as-written; the Field() default plan of a Pydantic field reads the None as written the same way, which no row names). Before it, only parser/_passes/render_prep.py:_flatten_union_members (render preparation), which moves member nullability onto the union, and L3's DataModel._write_pre_render_nullability (legacy-l3-import-nullability, which overrides and constructor ordering read; DataModel._prepare_dedup_key writes it for every field whose hint renders its own type before a dedup key renders, so such a type keeps the None of the nullable model it named when duplicate deletion points it at a model without one) write it; msgspec's _strip_null writes it on the copies its render plans hold. A decision before render preparation reads types.py:DataType.admits_none, which computes the rendered nullability with model/_decisions/nullability.py:rendered_nullability without writing it. A field of every built-in output model (Pydantic BaseModel, RootModel and dataclass, msgspec Struct, stdlib dataclass, TypedDict, enum, type alias) renders from one frozen render plan (model/_render_plan.py:FieldRenderPlan): its annotation form, its calls (Field(), field(), msgspec Meta()) with each argument and the declared items it writes, its default, the imports the calls need, every declared item it does not write (Omitted, with its reason), each with a Why, and for msgspec the copy of the field's type its annotation writes (its Annotated type, or its union with UnsetType), which imports, annotated and type_hint read. The field's backend builds it: model/pydantic_base.py:DataModelField (a Pydantic dataclass field adds the Field(...) of a forced assignment and the plain annotation of a call the dataclass must see, model/pydantic_v2/dataclass.py), model/msgspec.py:DataModelField (Meta(...) inside Annotated, then field(...) or the default alone), model/dataclass.py:DataModelField (field(...) or the default alone) and model/typed_dict.py:DataModelField (the ReadOnly, Required and NotRequired qualifiers of the key); an enum member is a field of the output's backend, whose plan gives the member's imports. The last render preparation pass freezes one per field in the parse's RenderReady (B2), and field, annotated, type_hint, represented_default, has_default_factory_in_field, the import collection and the dropped-constraints warnings read the frozen plan; before B2 they read the plan the parse's memo keeps for the field (model/base.py:live_render_plan), which B2 freezes. Each frozen plan keeps the revisions of its field (ParseMemo.revision), or, for a field, model or parser class outside the package or under custom templates, what it read from its field (DataModelFieldBase._render_inputs: the field's attributes, and inside its types, constraints and containers), and when the model renders (DataModel._template_fields) the plan of a field whose revisions moved or where any of what it read changed, replaced or edited in place, is rebuilt (RenderReady.refreshed), so a model whose render changes its fields first writes the change, as a pass that changes a field after render preparation does. The plan holds values and writes its text when it is read, so the names it holds are the final ones. Custom templates get the raw fields, which answer from the same plan. DATAMODEL_CODE_GENERATOR_CHECK_RENDER_PLANS checks that each frozen or rebuilt plan writes or omits every item its field declares and that it renders as the plan rebuilt when the modules are written, and that the type expression of the field's type hint frozen with it renders as the type hint then. Row legacy.L-NF: the nested models' default factories are decided when render preparation ends, but the import snapshot reads each field as if the factory were written (a second plan, RenderReady.import_view), and the models that render without frozen plans (GraphQL unions, custom output models) read the decision only once _set_nested_model_default_factory_metadata publishes it after the warnings. A RootModel's config items (its regex engine and freezing, the literal values it validates and the neutral extra of the validator helpers) are decided by pass decide_config_items once the helpers are planned (model/pydantic_v2/root_model.py:RootModel._decide_config_items); the ConfigDict import comes with the writer of each item's source, so the module imports collect it. A RootModel rendered outside a parse decides them, and its ConfigDict import, when it renders.

Pass Declarations¶

Every pass is declared in scripts/pass_decls.py as a PassDecl: its name, phase, scope (once over every model, or once per output module over that module's models), kind (transform, plan, repair, check, setup, bookkeeping), the Fact and RenderFact members of scripts/fact_tables.py it reads and writes, explicit order edges (after), the change that removes a repair (removed_by) and the phase it moves to (target). The package holds no declaration: only the checks read them, and they join a declaration to its pass by name. scripts/check_fact_finality.py (run by the test suite) checks that names are unique, phases never go back in execution order, a repair names what removes it, and setup, check and bookkeeping passes write no fact (a check pass may write the pseudo-fact STDERR, the warnings it emits, so that two passes that warn are ordered).

Parser.parse() runs the passes from the tables of parser/_passes/_tables.py (PIPELINE, with the bodies STRUCTURE_BODY, MODULE_BODY and FINALIZE_SEGMENTS of the overridable hooks _build_module_structure, _process_single_module and _finalize_modules), built from the steps of parser/_pipeline.py: a PassSpec runs one pass, named as its declaration, when its condition holds; a ForEachModule runs passes module by module; a HookCall calls an overridable method whose default runs a sub-table; a Segment enters a phase on the store (GenerationStore.enter_phase, read as GenerationStore.phase), then runs its steps. The labels that only the checks read live in scripts/pass_decls.py: the boundary each segment enters (BOUNDARY_BEFORE: PARSED, B1, DECIDED, B2), the pass scope of a segment's guarded writes (SCOPE_NAMES) and the sub-table of each hook (HOOK_BODIES). The Runner is the only caller of a pass; the finality check of the test suite (tests/checks/parse.py) runs each one inside the scope of its declaration with the models it compares (CHECKED_MODELS); steps call passes through the parser instance, so overrides and --debug tracing apply as to any method. The two diagnostics warnings that name the code calling parse() find that frame however deep the pipeline is (stacklevel_at_parse_caller).

The order rule (scripts/check_pass_pipeline.py:check_order): two passes of one segment conflict when one writes what the other reads or both write the same fact. Where only the earlier writes what the later reads, a derived edge orders them; every other conflicting pair needs explicit after edges, with their reasons, that connect it directly or through other edges. An explicit edge replaces the derived edge of its pair; one that runs a reader before a writer of what it reads is a provisional read, listed below the table. scripts/check_pass_pipeline.py (run by the test suite) checks that the tables run every declaration once in PASS_DECLS order, in the phase of its segment and with its scope, that the segments enter the boundaries in order and satisfy the order rule, that the repair set only shrinks, that every decision registry follows the rules of the Decision Phase, that only GenerationStore.seal_facts builds FinalFacts, that no code outside Parser reaches its name-mangled members, and lists the warnings whose stacklevel reaches past their caller. A pass trace (scripts/check_pass_pipeline.py --trace) records each pass that runs; the test suite keeps the traces of a few inputs and checks that some input runs every declared pass. The finality check (Fact Finality) compares the writes of fact rows with the declarations while the generator runs; reads and the writes of presentation rows are declared from the code. A new pass gets a declaration and a table entry.

Provisional reads, from the explicit edges:

• sort_data_models reads BASES before sort_base_classes_for_mro writes it: the model order reads the bases as parsed; the MRO order of bases follows it.
• delete_duplicate_models reads CLASS_NAMES, NULLABLE before replace_duplicate_name_in_module writes it: renames the duplicates that deletion keeps.
• replace_duplicate_name_in_module reads CLASS_NAMES before apply_forced_invalid_dotted_stdout_repair writes it: flattens invalid roots under the names deduplication gave.
• apply_forced_invalid_dotted_stdout_repair reads MODULE_MEMBERSHIP before reuse_model_tree_scope writes it: shares the duplicates of the repaired module layout.
• reuse_model_tree_scope reads MODULE_MEMBERSHIP before resolve_circular_imports writes it: breaks the cycles of the modules tree-scope reuse leaves, its shared module included.
• flatten_conflicting_base_layouts reads FIELD_TYPES before unconstrain_union_members writes it: layouts are flattened with the union members as parsed.
• override_required_field reads DEFAULTS before replace_unique_list_to_set writes it: converts the defaults that inherited required fields bring.
• alias_shadowed_imports reads MODULE_IMPORTS before change_from_import writes it: imports referenced models after shadowed imports took their aliases.
• replace_unique_list_to_set reads DEFAULTS before set_reference_default_value_to_field writes it: turns defaults into references after unique lists became sets.
• set_reference_default_value_to_field reads FIELD_TYPES before reuse_model writes it: compares models with their final defaults.
• extract_inherited_enum reads BASES, FIELD_SET before reuse_model writes it: compares models after inherited enums became models of their own.
• reuse_model reads CONTAINERS, DEFAULTS, FIELD_TYPES before replace_type_list_unique_list_to_set writes it: converts the array of a type list once every merge into its model is known.
• reuse_model reads CONSTRAINTS, DEFAULTS, DISCRIMINATOR_TAGS, FIELD_TYPES, METADATA, MODELS_EXIST, NULLABLE, REQUIRED before collapse_root_models writes it: inlines the root models that reuse keeps.
• replace_type_list_unique_list_to_set reads CONSTRAINTS, DEFAULTS, FIELD_TYPES, MODELS_EXIST before collapse_root_models writes it: inlines root models into the sets of type lists.
• replace_type_list_unique_list_to_set reads DEFAULTS before set_default_enum_member writes it: writes enum members as defaults of the sets of type lists.
• collapse_root_models reads FIELD_TYPES before change_field_name writes it: renames fields against the class names collapse settled.
• record_decimal_alias_models reads FIELD_NAMES before change_field_name writes it: the Decimal check reads the field names as parsed.
• set_default_enum_member reads FIELD_TYPES before change_field_name writes it: enum defaults read the types before a rename gives a keyless one its model's.
• sort_models reads FIELD_TYPES before change_field_name writes it: models are ordered by their types before a rename gives a keyless one its model's.
• change_field_name reads FIELD_NAMES before restore_inherited_field_names_for_unique_aliases writes it: restores the inherited names that renaming changed.
• sort_models reads FIELD_TYPES before apply_discriminator_type writes it: models are ordered by their types before tags rewrite the variant types.
• set_default_enum_member reads DEFAULTS, FIELD_TYPES before apply_discriminator_type writes it: enum defaults read the types before tags rewrite them.
• apply_discriminator_type reads FIELD_TYPES before type_const_narrowed_values writes it: narrows the types that tags wrote.
• refresh_field_config reads FIELD_ALIASES before rename_fields_hiding_types writes it: the field config is refreshed with the aliases before renaming.
• remove_overridden_models reads TYPE_OVERRIDES before apply_field_type_overrides writes it: overrides apply to the models kept after model-level overrides (#4958).
• type_dict_keys_by_root_types reads FIELD_TYPES before settle_kept_parent_roots writes it: the holders it redirects name object models, which no dict key names.
• fix_constructor_field_ordering_early reads FIELD_TYPES before settle_kept_parent_roots writes it: a redirected holder keeps its name, default and requiredness; only its type names the same-named inner model.
• type_dict_keys_by_root_types reads MODEL_KIND before write_rule_aliases_as_classes writes it: the aliases written as classes are object maps, which no dict key names.
• fix_constructor_field_ordering_early reads FIELD_TYPES before name_inner_models_in_rules writes it: the types of rules are no constructor fields.
• tag_fields_of_tagged_bases reads MODULE_IMPORTS before import_removed_reuse_canonicals writes it: repairs the imports of every module once the fields reused structs copy from their bases import theirs.
• tag_fields_of_tagged_bases reads MODULE_IMPORTS before import_renamed_types writes it: imports renamed types once the fields reused structs copy from their bases import theirs.
• import_removed_reuse_canonicals reads MODULE_IMPORTS before import_renamed_types writes it: imports renamed types next to the canonicals of removed reuse duplicates.
• import_renamed_types reads MODULE_IMPORTS before import_enum_member_literal_classes writes it: imports literal classes next to the renamed types.
• warn_enums_admitting_other_values reads FIELD_TYPES before import_enum_member_literal_classes writes it: the warning reads the enum types before literal classes replace them.
• assign_forward_reference_fields reads FIELD_ORDER before fix_constructor_field_ordering writes it: a field written by assignment is a dataclass default, which ordering reads from the bases of every module.
• fix_constructor_field_ordering reads FIELD_TYPES, NULLABLE before update_type_aliases writes it: ordering reads the field types before aliases quote them.
• assign_forward_reference_fields reads FIELD_TYPES before update_type_aliases writes it: the forward-reference assignment reads the field types unquoted.
• assign_forward_reference_fields reads DEFAULTS before set_validate_default_on_fields writes it: the forward-reference assignment reads which fields have a default, which deserializing it keeps.
• warn_required_assignments_after_defaults reads KEYWORD_ONLY before fix_tag_opt_out_field_ordering writes it: the pydantic warning and this msgspec repair never read or write the same models.
• snapshot_model_imports reads MODELS_EXIST before remove_unused_models writes it: the snapshot holds the imports of unused models, which leave with them.
• remove_unused_imports reads MODULE_IMPORTS before resolve_module_import_conflicts writes it: resolves the conflicts of the imports that are used.
• resolve_module_import_conflicts reads MODULE_IMPORTS before alias_builtin_shadowing_module_imports writes it: aliases the module imports once their names are final.
• alias_builtin_shadowing_module_imports reads IMPORT_ALIASES, MODULE_IMPORTS before alias_builtins_hidden_by_submodules writes it: aliases the builtins once the module imports are aliased.
• alias_builtin_shadowing_module_imports reads IMPORT_ALIASES before bind_module_field_names writes it: binds field names against the aliases of module imports.
• alias_builtins_hidden_by_submodules reads IMPORT_ALIASES before bind_module_field_names writes it: binds field names against the aliases of hidden builtins.
• change_imported_model_name reads MODULE_IMPORTS before import_models_of_hidden_submodules writes it: decides on the final class names; the new imports take names that no class holds.
• bind_module_field_names reads MODULE_IMPORTS before import_models_of_hidden_submodules writes it: imports the models anew once field names are bound; the new imports take names that no field holds.
• import_models_of_hidden_submodules reads BACKEND_CONFIG before name_final_classes_of_additional_properties writes it: names the classes of other modules through their final imports; backend config is written after the hidden submodules are decided, as decide_config_items writes it later.
• import_models_of_hidden_submodules reads BACKEND_CONFIG before refresh_sequence_interface_after_renames writes it: backend config is written after the hidden submodules are decided, as decide_config_items writes it later.
• change_imported_model_name reads MODULE_IMPORTS before replan_schema_validators_after_renames writes it: plans the validator helpers again for the renamed models.
• bind_module_field_names reads MODULE_IMPORTS before replan_schema_validators_after_renames writes it: binding reads the module imports before the helpers are planned again.
• import_models_of_hidden_submodules reads MODULE_IMPORTS before replan_schema_validators_after_renames writes it: adds the imports of the helpers once the models of hidden submodules are imported.
• import_models_of_hidden_submodules reads MODULE_IMPORTS before remap_import_overrides writes it: import overrides move the final imports.

Decision Phase¶

The decide segment (DECIDE, entered at B1 right after apply_generic_base_class) runs the decisions of the parser's registry, Parser._DECISION_PASSES (parser/_phases.py). The registry holds two decisions. omit_held_null (parser/_held_null.py, --omit-redundant-reference-null, #5081): a type that names a model holding null itself (a root model or type alias whose type admits None, or an enum with a None member) drops the None it restates of that model; the None it writes itself stays. omit_untaken_union_constraints (parser/_union_constraints.py, --field-constraints, #6022): a keyword a schema declares beside a union, which the call of the field that holds the union writes as a Field() argument (written_constraints, what the renderer writes), leaves the field when the value of a member cannot take it (DataTypeManager.member_constraint_keywords) and every member keeps the check without it in the output (the call of its own field writes the keyword, the keyword applies to none of its values, or it is None); otherwise the field keeps it. A decision is a DecisionPass: a DecisionSpec (the name of its PassDecl in DECISION_DECLS of scripts/pass_decls.py, a global transform of DECIDE that reads and writes Fact members only, and the issue it fixes), the writer protocol of its writes (a DecisionWriter), run(facts, writer) and, for a decision behind an option, when(parser). When a decision runs, GenerationStore.seal_facts builds the one FinalFacts of the parse: per output module, the models that render (unused models, which leave their modules later, are left out), as the read-only views of model/_views.py (ModelView, FieldView, DataTypeView, ReferenceView), and the keywords the value of a union member takes in the output model (member_keywords). The views list the facts final at B1 and rendered nullability through admits_none, never the is_optional that render preparation writes; presentation attributes are not part of them, and type checking rejects writes through a view. Every decision writes through _DecisionWriter, the one implementation of the writer protocols over the store, which records the models it changes (DecisionOutcome). A writer never changes a data type node that other fields share: it replaces the node in the one field with a copy first.

The decisions run in registry order, which must be the order the order rule computes from their declarations (decision_order): a decision that reads what another writes runs after it, every other conflicting pair needs an After edge in the after of its declaration (the only explicit edges a decision has), and the registration order breaks ties. The finality check runs each inside the scope of its declaration, so it holds its writes to the facts it declares. With the finality check on, FinalFacts holds guarded views that report each read of a render fact as render-read (Fact Finality). scripts/check_pass_pipeline.py checks every registry: unique names that no table pass has, global transforms of DECIDE that read and write facts only, an issue each, writer protocols that _DecisionWriter implements, and the order rule, whose order the registry lists.

Hidden Couplings¶

Per-module passes that change models in other modules. L5 receives only the current module's models, but reaches other modules through references. A model in another module may already be processed (its ordering, defaults and quoting are done) or not yet (its overrides, collapse and reuse have not run).

Nodes with more than one holder. A DataType normally has one owner (parent). These create more holders, and an in-place write to such a node changes every holder:

• Same-module root-model collapse inlines root_type_field.data_type.model_copy(), a shallow copy that shares the root type's data_types list and dict_key with the root model and with every other site that inlined it. Cross-module collapse uses _copy_data_type, a tree copy. The shared members keep parent in the root model's tree, so a later collapse that replaces one (replace_nested_data_type, then set_nested_data_types on that parent) rebinds only the root model's list and detaches the old member, which the other holders still contain.
• _create_set_from_list returns a model_copy() that shares its members with the list node, and for nested lists the store's swap_data_type rebinds the parent's data_types to a new list.
• apply_generic_base_class puts one BaseClassDataType object into the base list of every target model.
• extract_inherited_enum builds the merged Enum from the base enums' field objects and gives it the original model's Reference.
• Reuse, collapse-reuse redirects and Reference objects are shared by design: a rename or an edit of a canonical model is seen by every user.

Known in-place writers on such nodes: forward-reference quoting in update_type_aliases, model-level type overrides (_apply_override_to_data_type), import aliases (change_from_import and the L6 import repairs), and root-model collapse replacing a member of a shared list.

Fact Finality¶

"Final after" names the last pass that can still change the fact. A decision that reads the fact belongs after it. scripts/fact_tables.py holds the same information per attribute (final_after, frozen_at) for the checkers.

In practice, the fields, types, defaults, tags and bases of every model are final once apply_generic_base_class has run in _finalize_modules, except pydantic v2 type-alias bodies (prepare_type_alias_fields). Models that collapse left unused stay in the module lists until unused-model removal, so a pass placed there skips unused_models (run_unused_models). Removal finds a model through the module index built before L3 merges import cycles, so it does not reach a merged _internal module, except for a root model that the parent strategy replaced by its inner model, which is removed from the module that holds it: unused roots of other collapses stay in merged modules. Later passes change presentation or derive from those facts.

The finality check (tests/checks/finality.py, DATAMODEL_CODE_GENERATOR_CHECK_FACT_FINALITY, on in every test) checks this table and the pass declarations while the generator runs. It keeps a fingerprint per model: the values of the fact rows of scripts/fact_tables.py on the model, its fields and the data types of their types and of its bases, holding the objects it keys. When a pass ends, it compares the models the pass touched (the models of its module and the models they reference, for a module pass; the models that guarded writes and store operations reached; the models the pass reported changed with GenerationStore.note_changed_models or a field's invalidate_semantic_caches) and reports a changed row as

• undeclared when the pass declares none of the row's facts,
• other-module when a module pass changed a model of another module (whether that module is done is in the report),
• frozen when every declared fact of the row is final at a freeze point the pipeline has passed: B1 (entering DECIDE, right after apply_generic_base_class) for facts, B2 (entering IMPORTS) for the rendered nullability rows and the render facts that RENDER_FACT_FREEZE_POINTS freezes there,
• after-final when the phase is later than the row's final_after; a decision writes the facts it declares until DECIDE ends, whatever the row's final_after.

A change that no pass covers is unattributed, found at the next comparison of its model: when a pass touches it, when the next pass starts (for a guarded write outside every pass), at the start and the end of each module and when the pipeline leaves a phase: entering a phase (GenerationStore.enter_phase, which includes B1 and B2) compares every model. With DATAMODEL_CODE_GENERATOR_CHECK_FACT_FINALITY_SWEEP on as well (the test suite on the newest Python), a global pass that transforms or repairs compares every model too. A pass that runs in another phase than it declares is wrong-phase. At B2 the ordering-input check compares the fields of bases that constructor ordering read after the decision phase (get_inherited_constructor_info of parser/_passes/_shared.py), with the facts fix_constructor_field_ordering declares as reads, with those fields at B2 (ordering-input): render preparation of a later module must not change what an earlier module's ordering read. KNOWN_WRITES in tests/checks/finality.py lists the violations of today's pipeline, each with the roadmap item that removes it and a witness, the datamodel-codegen arguments of one run that makes it; they are reported with report:<path> and never raise. python scripts/check_fact_finality.py --witnesses (and the test suite) run the witnesses and report the entries whose witness no longer makes them, so the list only shrinks. Presentation rows, parser state, module imports and computed rows (a property of the model class) are not fingerprinted, and only type aliases hold TYPE_ALIAS_BODY in their rows. A row is judged by the freeze points of the facts the pass declares, so a pass that declares only IMPORT_ALIASES (final at render) can change DataType.type, python_type, kwargs, extras or enum_member_literals after B1 without a report, and one that declares only TYPE_ALIAS_BODY (final at B2) can change a type alias's data_type or data_types after B1, although FIELD_TYPES of those rows is final at B1. A decision of the decision phase reads FinalFacts through guarded views: reading a render fact, an attribute (or a key of extras or __dict__) whose row holds facts none of which is a Fact final at B1, is render-read, named after the running decision. The views give the graph objects they reach as views and their lists as tuples, and see only what a decision reads on them, not what the methods and properties of the classes read inside.

The check also seals the graph at the freeze points: once the pipeline has passed B1, each guarded write to an object that a fingerprint holds (an attribute assignment of a fact or presentation row, or a mutation of a guarded list such as fields, base_classes or data_types) is judged when it is made, inside store operations as well, with the same frozen rule: the facts the running pass declares among the row's facts, or all of the row's facts outside every pass. A write that changes no value is not judged, and it covers presentation rows, which no fingerprint holds.

Generation Store¶

GenerationStore (parser/generation.py) owns Parser.results and indexes, per model, its reference and paths and, per DataType occurrence, its owner model, field index and role (field, base, nested, dict key). It also records DataType objects that occur in more than one place (shared_data_type_fact_ids), models by path and by model key, and every reference occurrence of a type tree as a site (parser/_sites.py:RefSite): its owner model, field, position in the tree, node, target model key, kind (type, base, alias_body) and provenance, keyed by the id of its occurrence and listed per target (sites_by_target). Queries refresh the facts when a mutation marked them dirty, either incrementally for appended and changed models or with a full rebuild. Every store mutation states what it does to the sites (SITE_EFFECTS, NO_SITE_EFFECT): a new site takes the provenance of the mutation that made it (redirected with the model it named before and the site at its place, collapsed with the root model and its site, overridden, copied), the sites of the parsed models are parsed, and a site whose occurrence a refresh keeps keeps its provenance; renames touch no site, since sites store no names.

Every mutation goes through the store's GraphBuilder, the capability that GenerationStore.builder() returns (Parser._graph_builder in the parser): one method per mutation of GENERATION_STORE_MUTATION_METHODS, each calling the store's operation of the same name, so that a store subclass that overrides an operation and the debug checks that wrap the operations on the store keep seeing every call. The operations on GenerationStore itself are deprecated for every other caller (@deprecated(category=None): ty lists the callers, and no warning is raised at run time).

A Reference takes a ModelKey when it is built: Reference.model_post_init stores the next value of a process-wide counter in its __dict__, beside its schema location, and _model_keys.py:model_key_of reads it. A reference that no model was built with, such as one a parser extension builds, names the model at its path (names_by_path, row legacy-keyless-reference-by-path), and the tables the passes keep by model key and by path for it are read through keyed_or_path. A rename of the model at that path (rename_named_type) gives the types that name it by such a reference the model's own reference, so that they follow the new name; it reads the model that is emitted there, not a root model that collapse replaced (_replaced_root_models). The store keys model_by_ref_id, sites_by_target and the reference counts of root collapse by it, through GenerationStore.model_key, instead of id(reference), which Python reuses once a Reference is freed. Copies of a Reference (deepcopy, model_copy, pickling) keep the key of their original, so the store would take a copy for the model it was copied from. DATAMODEL_CODE_GENERATOR_CHECK_MODEL_GRAPH reports a Reference object that the store records or is asked about when another one took its key first, and, at the end of L1, a model parsed from a JSON document that has no owner and is not a root. The owner is the model whose builder built this one: the check (tests/checks/model_graph.py) runs each model builder of JsonSchemaParser in a frame whose cell takes the model it built when it returns, and a model records the frames open when it is recorded. A read or write variant stands for its base model in those frames, so it takes the base's owner; a document parse (_parse_file, also for a $ref target) starts with no frame open, so its models are roots. Because the key sits in __dict__, two distinct References with equal fields compare unequal under pydantic before 2.6, whose == compares __dict__; no parser comparison depends on that (GR5 turns the remaining == sites into is). Other parser maps still identify models by path, class name or id().

The store owns the parse's memos (_parse_memo.py:ParseMemo), which Parser.parse makes current while it runs. The model layer keeps there what it derives from the mutable models instead of on them: the dedup keys of a model, the member indexes of an enum (by model key), whether a field's type names its model (by field key) and the members a union node joined when it rendered (by node key). A value is kept with the epoch its owner has in its table; the methods that cleared the caches these memos replace (invalidate_render_caches, invalidate_semantic_caches) bump the epoch, so the memos return what those caches returned. Outside a parse values are computed at each read. The render plan of a field (FIELD_RENDER_PLAN, model/base.py:live_render_plan) and its imports (FIELD_IMPORTS, field_imports, by the plan they read) are derived values: the memo keeps each with the revisions it read, the field's own, its model's own and, for every model its type references, that model's own and its fields' (ParseMemo.derived). The store's mutations bump what they write (bump_field, bump_node, bump_model, and the invalidation methods above); a node bump reaches every field whose value read the node or its member list and the field that holds it. rename_model and update_model_reference bump the model, so the fields that reference it compute again, and so does a model's constructor, which names the model the source of its reference. Every bump moves the memo's clock: a value whose revisions were seen to hold at the current clock is returned without comparing them again, and the references of a field's type walked at the current clock are not walked again. DataModel.imports joins the fields' kept imports with the model's own (_additional_imports) at each read; the snapshot of the IMPORTS phase is where they become final. Fields and models of classes outside the package, and every field of a parse by a parser class outside it, compute both at each read (DataModel.clear_imports_cache is a deprecated no-op). DATAMODEL_CODE_GENERATOR_CHECK_RENDER_MEMOS (tests/checks/memos.py) computes every returned value anew and fails on a difference, except for the dedup keys and self references whose stale values today's output keeps (legacy-stale-dedup-keys, and the self-reference exemption of tests/checks/memos.py), which it records with a report file.

The mutation APIs are the GenerationStore methods listed in GENERATION_STORE_MUTATION_METHODS, for example replace_field_type, replace_nested_data_type, set_fields, set_base_classes, update_model_reference and redirect_reference_users. rename_model is the writer of class and reference names after the L2 settle; its callers apply six schemes (module, flattened module, field type, imported name, internal module and collapsed root), each with its own universe for uniqueness. The resolvers of the module, flattened module and field type schemes come from parser/_passes/_name_allocation.py:scheme_resolver, one row per scheme.

scripts/fact_tables.py says which attribute holds which fact. ATTRIBUTE_FACTS has one row per owner class and attribute, __dict__ key, dict entry (extras["kw_only"]) or cached property, with its kind (fact, presentation, cache or bookkeeping), the Fact and RenderFact members a write changes, the store operations allowed to write it, the Phase whose passes write it last today and its freeze point: the latest freeze point among its facts (every Fact at B1, every RenderFact at its RENDER_FACT_FREEZE_POINTS entry), after which nothing may write it once the pass pipeline is in place. The finality checks still check each Fact at B1 unless a pass declares an exception. Bookkeeping rows name no fact and no store operation. The module docstring lists the three allowed exceptions to the kind rules (plan rows, rendered nullability, the schema-validator plan cache). The module imports only the standard library and typing_extensions (scripts/check_architecture_boundaries.py registers it as the facts leaf layer), so the checkers can read it without importing the package.

scripts/check_generation_store_usage.py (with tests/parser/test_generation_store_usage.py) reads that table and the store mutations (SITE_EFFECTS, NO_SITE_EFFECT) with ast and reports every write that does not go through a store operation:

• in parser/: writes of fact and presentation attributes of model-graph classes (assignment, del, augmented assignment, setattr and object.__setattr__ with a literal name, item writes and list, dict and set mutators, also through a local alias), __dict__ writes, the direct .data_type, .fields, .base_classes and .reference writes, list mutators on model collections and Reference.children reads. A setattr with a computed name is reported too. Writes to the parser itself (self) and to schema objects (parameters annotated JsonSchemaObject, and the copies and SCHEMA_OBJECT_TYPE.model_validate results made from them) are not model writes;
• in model/ and types.py: the same writes inside the parser-facing hooks (PARSER_HOOK_METHODS), the private helpers that write rendered state when a pass reads type_hint or collects imports (RENDER_STATE_WRITERS), and every model function these reach through calls on any receiver, at any depth, including writes to self. The closure stops at construction (CONSTRUCTION_METHODS), reference bookkeeping (REFERENCE_METHODS) and render entry points (RENDER_ENTRY_POINTS, each with its reason);
• in all three: caches kept on model objects: __dict__ entries, cache attributes and cached_property.

Every finding is keyed by path, function and target, without line numbers, and scripts/generation_store_allowlist.toml holds the findings that existed when the checker learned them, with a count each. A new finding fails, and so does an entry that no longer matches, so the list only shrinks: a change that routes a write through the store removes its entry. The checker also fails when a model-graph class sets an attribute (in any method) without a row, when a row names nothing the sources declare or write, when a model method that parser code calls (directly, or by name through getattr/hasattr) reaches a fact write that no hook covers, and when a hook, construction or render-entry list names a function that no model module defines.

The checker does not follow these forms, so they must not be used for model writes: obj.__setattr__("name", value), obj.extras.__setitem__(key, value) and other dunder calls, unbound method calls such as list.append(obj.fields, field), and functools.partial(setattr, obj).

The runtime write guard (tests/checks/finality.py, DATAMODEL_CODE_GENERATOR_CHECK_STORE_WRITES) checks the same rule while the generator runs in the test suite, for writes the scan cannot follow. It arms at the end of L1: DataType, DataModelFieldBase and DataModel get a __setattr__ guard for the fact and presentation attributes of ATTRIBUTE_FACTS, the lists those attributes hold become guarded copies (shared where the originals were shared; they are not list exactly and outlive the parse, acting as plain lists afterwards), each store operation named in a row's store_ops runs in a write scope, and the pipeline of parser/_passes/_tables.py runs in pass scopes (ParseChecks.scope: _build_module_structure in STRUCTURE, the plan segment in PLAN, each _process_single_module in MODULES, the cross_module and generic_base_class segments in CROSS_MODULE, the decide segment in DECIDE, the render_preparation segment, _finalize_modules included, in RENDER_PREPARATION, the finish segment in IMPORTS and the render segment in RENDER; before them, SETTLE; inert without an armed guard). A write outside every store operation is reported once per line and parse with the line that wrote it, the parser method running and the pass scope and phase; the construction of an object (its __init__ and what that calls) writes freely. Any store operation accepts any guarded write, and the phase is not checked: which operation and phase may write which attribute is left to the finality checks. With the area off nothing is installed. The guard does not see writes through object.__setattr__, through __dict__, into dict attributes, or into a list an object got outside a store operation after L1. The guards, the guarded lists and the store-operation scopes belong to the checks of one parse (parse_checks, armed by ParseChecks.arm), which the finality check shares: a parse loads tests/checks/finality.py and installs them only when either area is on, and the guard reports writes only when STORE_WRITES is on, while the finality check uses them to learn which models a pass touched.

The test suite runs the guard in every test (tests/conftest.py:StoreWritesCheck): it reports into a file of the test process, and after each test the checker names each write of the package by the function that contains the reported line and by the target the scan gives that write (runtime_writes), and the test fails for a write the allowlist does not list. Most writes the guard sees are findings of the scan. A write only the guard sees (a method the hook closure does not reach, a write made inside a helper the scan stops at) has an entry whose value is its witness, the datamodel-codegen arguments of one run that makes it; python scripts/check_generation_store_usage.py --witnesses (and the test suite) run them, and an entry whose witness no longer writes it is stale. The entries only shrink, like the counted ones. When the scan learns to find a write a witness covers, the witness becomes a count entry (--write-allowlist makes that move); it is the only move that may raise the counted total.

Current behaviour that a decision reading the index must allow for:

• Index queries answer over the parsed universe: the models parsers registered (Parser.results) plus redirected edges, removed ones included, not the module lists that L3–L6 edit. A model a later pass builds (a reuse subclass, the merged inherited Enum, the generic base class) is registered in the emitted universe only, and retire_model (replace_model for a model built in another's place) records each model that leaves the output (duplicates, reused and overridden models, unused models leaving their written module list). Under DATAMODEL_CODE_GENERATOR_CHECK_MODEL_GRAPH, the written models must equal the emitted universe after render preparation.
• A store operation called with refresh="deferred" notes the models it changes for the next refresh but does not mark the facts dirty, so they stay as they were until another mutation. drop_union_member_constraints (msgspec unconstrain_union_members, slice assignment on data_types), swap_data_type for the nested lists of replace_unique_list_to_set (which stay sets when an unhashable default keeps the field a list), apply_const (process_const() during collapse) and use_assignment_for_forward_references change models this way. Under DATAMODEL_CODE_GENERATOR_CHECK_MODEL_GRAPH, every refresh that records only the noted models compares its facts with a full rebuild.
• The operations that write values the facts do not record neither note models nor mark the facts dirty: a field's default (set_field_default), required (require_field), name, original name and aliases (rename_field, set_field_identity), constraints (set_field_constraints), extras (set_field_extras, set_field_extra, drop_field_discriminator), and the import of a model-level --type-overrides entry (override_type_import, add_model_import), and the Union or Optional that a quoted name asks of the types joining it (drop_union_operator). An entry written into a field's extras, a discriminator dropped from a field's type, an override's import and a dropped union operator are seen by every holder of the dict or type. A copy takes the name, original name and aliases of the placeholder it replaces, and the other values its caller gives, when it is made (_copy_data_model_field with identity and FieldCopyFacts); the writes on a copy's type and raw schema default before it is installed (_copy_resolved_inherited_field, _apply_override_to_field) stay outside the store.
• Most fact writes after parsing still bypass the store; scripts/generation_store_allowlist.toml lists them by function. The checker cannot see writes through a model-list variable (models.sort() on a module's list), writes to module imports (ModuleContext.imports, which go through the import ledger and its runtime check instead, see L6 above), or writes in model methods that the hook closure does not reach; the runtime guard sees the last kind, and the allowlist lists them with a witness.
• Dedup keys (cached on the model, read through ModelShapes.key) and model shapes are separate caches, not store facts.

Placement Guide¶

Procedure for a new decision:

1. List every fact the decision reads, including facts of models reached through references, bases, variants and root models.
2. Look up each fact in the finality table. Put the decision after the pass where the last of them becomes final. If that point is in L6, the decision is a cross-module pass, not a per-module one.
3. If a pass that runs earlier needs the decision's result, move the pass that sets the fact earlier (for example, split it into a plan computed from facts that are final at that point and an apply step), or move the consumer after the decision. Never predict what a later pass will do.
4. Before changing a node, check whether it can have more than one holder. Replace it in its owner through the store's mutation APIs instead of writing to it.

A decision that changes field order, defaults or required state must also run before constructor ordering reads them (fix_constructor_field_ordering and fix_tag_opt_out_field_ordering, after the decision phase); when that conflicts with a row above, step 3 applies.

One home per decision. A decision that several passes or backends need is one pure function in model/_decisions/ over the immutable facts it reads, passed by keyword (or as a frozen record), or, for a decision over dumped schemas or frozen schema facts, in a pure parser core (parser/_intersection.py, parser/_null_facts.py, parser/_model_shapes.py); the adapter that reads those facts is the only code that reads the live objects, and callers are to go through it (readers of the stored is_optional move in a later step). scripts/check_architecture_boundaries.py keeps the package free of concrete backends and the parser cores free of everything but the standard library and the leaves they read (_json_schema.py, _model_keys.py, _records, _regex_syntax). A table that types.py reads while it is imported is a top-level leaf instead, as the model package imports types.py: _requirements.py, _constraint_applicability.py and _container_kinds.py.