Self referencing classes leading to undefined-name (F821)

[aschamberger]

Describe the bug
Undefined name ISA95PropertyDataType for subproperties. The ISA95PropertyDataType should be replaced by Self

To Reproduce

Example schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "ISA95PropertyDataType": {
      "type": "object",
      "properties": {
        "ID": {
          "type": "string",
          "description": "Unique identifier for a property within the scope of the associated resource"
        },
        "Value": {
          "description": "Value for the property"
        },
        "Description": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/LocalizedText"
          },
          "description": "An optional description of the parameter."
        },
        "EngineeringUnits": {
          "$ref": "#/$defs/EUInformation",
          "description": "The Unit Of Measure of the value"
        },
        "Subproperties": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ISA95PropertyDataType"
          }
        }
      },
      "description": "A subtype of OPC UA Structure that defines two linked data items: an ID, which is a unique identifier for a property within the scope of the associated resource, and the value, which is the data for the property.\nhttps://reference.opcfoundation.org/ISA95JOBCONTROL/v200/docs/7.3.9"
    }
}

Result:

@dataclass(kw_only=True)
class ISA95PropertyDataType:
    """
    A subtype of OPC UA Structure that defines two linked data items: an ID, which is a unique identifier for a property within the scope of the associated resource, and the value, which is the data for the property.
    https://reference.opcfoundation.org/ISA95JOBCONTROL/v200/docs/7.3.9
    """

    id: str | None = None
    """
    Unique identifier for a property within the scope of the associated resource
    """
    value: Any | None = None
    """
    Value for the property
    """
    description: list[LocalizedText] | None = None
    """
    An optional description of the parameter.
    """
    engineering_units: EUInformation | None = None
    """
    The Unit Of Measure of the value
    """
    subproperties: list[ISA95PropertyDataType] | None = None

Used commandline:

    data_model_types = get_data_model_types(
        DataModelType.DataclassesDataclass, target_python_version=PythonVersion.PY_314
    )
    config = JSONSchemaParserConfig(
        target_python_version=PythonVersion.PY_314,
        use_union_operator=True,
        use_standard_collections=True,
        formatters=[Formatter.RUFF_FORMAT, Formatter.RUFF_CHECK],
        custom_template_dir=pathlib.Path(__file__).parent / "template",
        data_model_type=data_model_types.data_model,
        data_model_root_type=data_model_types.root_model,
        data_model_field_type=data_model_types.field_model,
        data_type_manager_type=data_model_types.data_type_manager,
        dump_resolve_reference_action=data_model_types.dump_resolve_reference_action,
        keyword_only=True,
        use_subclass_enum=True,
        capitalise_enum_members=True,
        snake_case_field=True,
        use_field_description=True,
        use_schema_description=True,
        use_title_as_name=True,
        additional_imports=[
            "app.dataclass.DataClassConfig",
        ],
    )
    parser = JsonSchemaParser(schema_file_path.read_text(), config=config)
    result = parser.parse()

Expected behavior

    # ...
    subproperties: list[Self] | None = None

Version:

• OS: [e.g. iOS] Linux
• Python version: 3.14
• datamodel-code-generator version: 53

Additional context
Add any other context about the problem here.

[acederberg]

Hi!

I reproduced this independently.

Example

For version datamodel-codegen 0.53.0 (found by running datamodel-codegen --version).
See Node in Node unquoted.

Schema

{
  "$schema": "https://json-schema.org/draft-07/schema",
  "title": "Tree",
  "description": "A tree.",
  "definitions": {
    "Node": {
      "type": "object",
      "properties": {
        "children": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Node"
          }
        },
        "value": {
          "type": "string"
        }
      }
    }
  },
  "$ref": "#/definitions/Node"
}

Output

# generated by datamodel-codegen:
#   filename:  demo.json
#   timestamp: 2026-02-02T23:14:13+00:00

from __future__ import annotations

from typing import Annotated

from pydantic import BaseModel, Field, RootModel


class Node(BaseModel):
    children: list[Node] | None = None
    value: str | None = None


class Tree(RootModel[Node]):
    root: Annotated[Node, Field(description='A tree.', title='Tree')]


Node.model_rebuild()

Invocation

python -m datamodel_code_generator \
  --input demo.json \
  --output test.py \
  --output-model-type pydantic_v2.BaseModel \
  --use-annotated

Desired Functionality

Node should be quoted.

class Node(BaseModel):
    children: "list[Node] | None" = None
    value: str | None = None

[aschamberger]

With moving to 3.14 the problem was solved already.

I missed to update my pyproject.toml

[tool.ruff]
target-version = "py314"

For me the issue is solved and I would close it. What do you think?

[ilovelinux]

@aschamberger
Glad you found a workaround! 🙂
However, even if Ruff is able to fix this mistake, those who don't use Ruff still have that problem.
Let's keep this issue open to track the bug 🙁

[aschamberger]

@ilovelinux
If I don't get the release notes wrong it is the new desired way of working and no workaround: https://docs.python.org/3/whatsnew/3.14.html#whatsnew314-deferred-annotations

If you would quote the annotations or add Self it needs to be conditionally <=py3.13 as with py3.14 the current behavior is perfectly fine.

[ilovelinux]

@aschamberger
That's correct. In your specific case (using Python 3.14) the generated code works. However if you run datamodel-code-generator without declaring the target-python-version option (e.g. @acederberg's case described in #2973 (comment)), it uses the lowest supported Python version as target-version: Python 3.10¹².
So, the generated code should be compatible with Python 3.10, but it's not. That's the reason why I think this issue should be kept open. 🙂

Footnotes

1. https://github.com/koxudaxi/datamodel-code-generator/blob/365419ec30ebba7cbad5c1c8c7f66a08cfefacbd/src/datamodel_code_generator/config.py#L237 ↩

2. https://github.com/koxudaxi/datamodel-code-generator/blob/365419ec30ebba7cbad5c1c8c7f66a08cfefacbd/src/datamodel_code_generator/format.py#L160 ↩