[
  {
    "id": "behavior.naming-hint",
    "kind": "behavior",
    "message": "The hint at --recommend-options that a command line generation shows when many class names are numbered collisions is experimental; when it is shown and its text may change.",
    "note": "A command line generation warns with datamodel_code_generator.NamingHintWarning when at least 10 class names, and at least one in five, are numbered collisions: names the model resolver numbered because the name without the number was taken, such as Pet1 beside Pet. It is shown at most once per command and never by generate(). An explicit --naming-strategy, --model-name-map, or deprecated --parent-scoped-naming, on the command line or in pyproject.toml, --check, --diff-against, --output-format json, --disable-warnings, and the options --recommend-options refuses (--watch, --all-jobs, and more than one --job) leave it out; a filter that turns warnings into errors drops it. It never changes the generated files, the result of --check, or the exit code.",
    "since_version": "0.86.0",
    "target": "NamingHintWarning",
    "tracking_issue": null
  },
  {
    "id": "behavior.batch-generation-jobs",
    "kind": "behavior",
    "message": "Named batch jobs are experimental; their configuration schema, batch output, and transactional/watch execution contracts may change.",
    "note": "Define named generation jobs in [tool.datamodel-codegen.jobs] and select them with --job or --all-jobs. Each selected job has its own input and output, and the full selection is validated before generation begins.",
    "since_version": "0.72.3",
    "target": "[tool.datamodel-codegen.jobs], --job, --all-jobs",
    "tracking_issue": null
  },
  {
    "id": "behavior.remote-reference-lock",
    "kind": "behavior",
    "message": "Remote reference integrity locking is experimental: the lock document schema and request-identity compatibility may evolve, but integrity mismatches remain fail-closed and credentials are never persisted.",
    "note": "The lock stores opaque SHA-256 request-identity digests and SHA-256 body digests, never response bodies or request values directly. Each saved display origin contains only the scheme, host, and explicit port\u2014never a path, query, or request headers.",
    "since_version": "0.72.3",
    "target": "datamodel-codegen.lock, --lockfile, --update-lock, and --locked",
    "tracking_issue": null
  },
  {
    "id": "cli-option.generate-client",
    "kind": "cli-option",
    "message": "HTTPX2 client generation from the CLI is experimental; its options and generated package may change.",
    "note": "`--generate-client httpx2` generates the models at `--output` and a client package at `--client-output`; `--client-package` and `--client-model-package` name their import paths, and the other `--client-*` options configure the package. Like model options, they can be set in `[tool.datamodel-codegen]` of `pyproject.toml`, in its profiles, and in its jobs. `--check`, `--diff-against`, `--watch`, `--output-format json`, and the `uv add` and next-step notice on stderr work as with `--generate-server`. `generate()` takes them as `generate_client` and the `client_*` options, and returns every generated file without an output. It needs Python 3.11 or later, both to run and as `--target-python-version`, `--use-missing-sentinel` for `pydantic_v2.dataclass` models, `--target-pydantic-version 2.14` with `--use-missing-sentinel`, and `--use-msgspec-tagged-unions` and `--use-msgspec-nullable-enum-alias` for `msgspec.Struct` models; one left unset takes that value, as with `--generate-server`.",
    "since_version": "0.84.0",
    "target": "--generate-client httpx2 and the --client-* options (and their [tool.datamodel-codegen] keys and generate() options)",
    "tracking_issue": null
  },
  {
    "id": "cli-option.generate-schema-validators",
    "kind": "cli-option",
    "message": "Schema-derived runtime validators are experimental and may change as JSON Schema coverage is expanded.",
    "note": "The option currently targets Pydantic v2 BaseModel output and covers selected object-level rules such as patternProperties, required-only oneOf/anyOf/not groups, and simple if/then/else required-property conditions.",
    "since_version": "0.66.1",
    "target": "--generate-schema-validators",
    "tracking_issue": null
  },
  {
    "id": "cli-option.generate-server",
    "kind": "cli-option",
    "message": "FastAPI server generation from the CLI is experimental; its options and generated package may change.",
    "note": "`--generate-server fastapi` generates the models at `--output` and a server package at `--server-output`, whose `main.py` serves the application with the implementations in the `services` package beside it; generation writes each missing module of `services` once, with stubs, and never overwrites one. `--server-package` and `--server-model-package` name their import paths, and the other `--server-*` options configure the package. Like model options, they can be set in `[tool.datamodel-codegen]` of `pyproject.toml`, in its profiles, and in its jobs. `--check` compares without writing, `--diff-against` compares the files two inputs render, `--watch` regenerates after input changes, `--output-format json` uses the model generation, check, and input-diff payloads, and generation prints a `uv add` command and the next steps to stderr. `generate()` takes them as `generate_server` and the `server_*` options, and returns every generated file without an output, writing no stubs. It needs Python 3.11 or later, both to run and as `--target-python-version`, `--use-missing-sentinel` for `pydantic_v2.dataclass` models, `--target-pydantic-version 2.14` with `--use-missing-sentinel`, and `--openapi-scopes` with `api`. A setting left unset, by the options, `pyproject.toml`, `generate()`, and the preset, takes that value, and the command line prints how to set it; one set otherwise is refused.",
    "since_version": "0.84.0",
    "target": "--generate-server fastapi and the --server-* options (and their [tool.datamodel-codegen] keys and generate() options)",
    "tracking_issue": null
  },
  {
    "id": "cli-option.install-skill",
    "kind": "cli-option",
    "message": "Bundled Agent Skill installation is experimental; supported clients, scopes, and installed skill contents may change.",
    "note": "Use --install-skill with codex or claude-code. --skill-scope selects a project or user installation, and --overwrite-skill safely replaces an existing regular skill directory.",
    "since_version": "0.76.0",
    "target": "--install-skill, --skill-scope, and --overwrite-skill",
    "tracking_issue": null
  },
  {
    "id": "cli-option.recommend-options",
    "kind": "cli-option",
    "message": "Option recommendations are experimental; the rules, the schema signals they read, the class-name metrics, the report, and the JSON payload may change.",
    "note": "--recommend-options reads the input schema, measures naming-relevant signals of OpenAPI, AsyncAPI, and JSON Schema documents, and prints the latest dated preset to start from with the options to add, as a command and a pyproject.toml block. Options set on the command line or in pyproject.toml are kept. For schemas of up to 3000 estimated models, it also generates the candidate configurations in memory and recommends the one whose class names score best; nothing is written. With --generate-prompt, the prompt embeds the report, and its JSON output carries the recommend-options payload as recommendation.",
    "since_version": "0.86.0",
    "target": "--recommend-options, its rule data, its candidate comparison, its JSON payload, and --generate-prompt --recommend-options with the prompt JSON field recommendation",
    "tracking_issue": null
  },
  {
    "id": "cli-option.schema-validator-type",
    "kind": "cli-option",
    "message": "Schema-derived runtime validator backend selection is experimental and may change as validation backends are added.",
    "note": "The only currently implemented backend is 'pydantic-v2', which preserves the existing generated Pydantic v2 validator behavior.",
    "since_version": "0.66.1",
    "target": "--schema-validator-type",
    "tracking_issue": null
  },
  {
    "id": "cli-option.use-missing-sentinel",
    "kind": "cli-option",
    "message": "Pydantic MISSING sentinel output is experimental because it depends on pydantic.experimental.missing_sentinel, or on pydantic.MISSING for a 2.14 target.",
    "note": "The option requires Pydantic v2 BaseModel or dataclass output and a target Pydantic version that supports the MISSING sentinel. Server and client generation require it for Pydantic v2 dataclass output, and `--target-pydantic-version 2.14` with it.",
    "since_version": "0.66.1",
    "target": "--use-missing-sentinel",
    "tracking_issue": null
  },
  {
    "id": "cli-option.use-type-alias",
    "kind": "cli-option",
    "message": "Type alias output is experimental and may change as Python typing support evolves.",
    "note": "The option replaces root model classes with type aliases where possible. Pydantic v2 output may use TypeAliasType or Python 3.12 type statements depending on the target Python version.",
    "since_version": "0.36.0",
    "target": "--use-type-alias",
    "tracking_issue": null
  },
  {
    "id": "cli-option.use-type-alias-type",
    "kind": "cli-option",
    "message": "Runtime TypeAliasType output is experimental and may change as Python typing support evolves.",
    "note": "The option implies --use-type-alias and selects TypeAliasType for Python 3.10 and 3.11. Python 3.12 and newer continue to use native type statements.",
    "since_version": "0.71.1",
    "target": "--use-type-alias-type",
    "tracking_issue": null
  },
  {
    "id": "extra.httpx2",
    "kind": "extra",
    "message": "The HTTPX2-backed HTTP client is experimental and may change as compatibility is validated.",
    "note": "`datamodel-code-generator[http]` remains the stable HTTPX backend and is not deprecated; `datamodel-code-generator[httpx2]` is experimental. The default HTTP backend policy is auto: stable httpx is selected when its client module is installed, including when both pairs are installed, and experimental httpx2 is selected only when that module is absent. Use `--http-backend httpx2` or `HTTPBackend.HTTPX2` to require the experimental pair. Explicit selections and paired dependency errors do not fall back.",
    "since_version": "0.71.1",
    "target": "datamodel-code-generator[httpx2]",
    "tracking_issue": null
  },
  {
    "id": "formatter.builtin",
    "kind": "formatter",
    "message": "The internal formatter is experimental and may change as generated-output coverage is expanded.",
    "note": "The formatter is designed for generated model modules and is not a general-purpose Python formatter.",
    "since_version": "0.59.0",
    "target": "--formatters builtin",
    "tracking_issue": null
  },
  {
    "id": "input-format.asyncapi",
    "kind": "input-format",
    "message": "AsyncAPI input support is experimental and may change as real-world usage is validated.",
    "note": "The parser focuses on message payload model generation from AsyncAPI documents.",
    "since_version": "0.59.0",
    "target": "--input-file-type asyncapi",
    "tracking_issue": null
  },
  {
    "id": "input-format.avro",
    "kind": "input-format",
    "message": "Apache Avro schema input support is experimental and may change as real-world usage is validated.",
    "note": "The parser generates Python models from Avro schemas; it does not provide Avro runtime validation.",
    "since_version": "0.59.0",
    "target": "--input-file-type avro",
    "tracking_issue": null
  },
  {
    "id": "input-format.mcp-tools",
    "kind": "input-format",
    "message": "MCP tool schema profile input support is experimental and may change as MCP schemas evolve.",
    "note": "The input is converted from MCP tool inputSchema/outputSchema entries into JSON Schema definitions before model generation.",
    "since_version": "0.60.0",
    "target": "--input-file-type mcp-tools",
    "tracking_issue": null
  },
  {
    "id": "input-format.protobuf",
    "kind": "input-format",
    "message": "Protocol Buffers input support is experimental and may change as real-world usage is validated.",
    "note": "The parser generates Python models from .proto schemas; it does not provide protobuf runtime validation or gRPC code generation.",
    "since_version": "0.59.0",
    "target": "--input-file-type protobuf",
    "tracking_issue": null
  },
  {
    "id": "input-format.xmlschema",
    "kind": "input-format",
    "message": "XML Schema input support is experimental and may change as real-world usage is validated.",
    "note": "The parser focuses on model generation from XSD documents, not full XML instance validation.",
    "since_version": "0.59.0",
    "target": "--input-file-type xmlschema",
    "tracking_issue": null
  }
]
