Add standard preset (#3422)

* Add standard preset

* style: auto-fix by pre-commit.ci

* Update skill CLI reference

* Address preset review findings

* Fix preset tests on older black

* Cover preset metadata helpers

* Cover preset override branches

* Address preset docs review

* Address preset review comments

* Preserve related CLI doc links

* Use typed config for presets

* Derive preset config from groups

* Lazy load preset resolver

* Handle preset tests with older black

* Cover unknown preset pyproject errors

* Inline typed preset config

* Return explicit preset updates

* Address preset review feedback

* Avoid mixed preset render returns

* Initialize preset render output

* Use typed preset config updates

* Tighten preset config typing

* Use BaseGenerateConfig for preset config

* Use literal for single enum preset

* Fix preset literal test target

* Add strict nullable to standard preset

* Add practical preset

* Document preset workflows

* Refine preset quick start

* Update preset date

* Add target-specific presets

* Cover preset enum config values

* Refine preset options

* Update preset formatter fixtures

* Infer target from preset

* style: auto-fix by pre-commit.ci

* Refine preset target validation

* Remove target version from preset examples

* Clarify expanded preset examples

* Improve preset docs navigation

* Simplify preset quick start

* Reorder README sections

* Clarify Python baseline in quick start

* Refresh preset quick start examples

* Refine preset quick start docs

* Type preset names as literals

* Strengthen preset name typing

* Add preset to generate API

* Generate typed preset config dict

* Share preset config resolution

* Remove duplicate preset resolvers

* Cover preset config branches

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: koxudaxi

.github/CODEOWNERS

@@ -7,6 +7,7 @@
 /scripts/update_command_help_on_markdown.py @koxudaxi
 /scripts/build_cli_docs.py @koxudaxi
 /scripts/build_prompt_data.py @koxudaxi
+/scripts/build_preset_docs.py @koxudaxi
 /scripts/build_schema_docs.py @koxudaxi
 /scripts/build_llms_txt.py @koxudaxi
 /scripts/update_docs_version.py @koxudaxi

.github/workflows/cli-docs.yaml

@@ -35,7 +35,7 @@ jobs:
         env:
           UV_PYTHON_PREFERENCE: "only-managed"
       - name: Collect CLI doc metadata
-        run: .tox/cli-docs/bin/pytest --collect-cli-docs -p no:xdist -q
+        run: .tox/cli-docs/bin/pytest tests --collect-cli-docs -p no:xdist -q
       - name: Build CLI docs
         run: .tox/cli-docs/bin/python scripts/build_cli_docs.py
       - name: Build prompt data

.github/workflows/generated-docs-sync.yaml

@@ -7,9 +7,11 @@ on:
     paths:
       - 'src/datamodel_code_generator/**'
       - 'tests/main/**'
+      - 'tests/data/jsonschema/tutorial_pet.json'
       - 'tests/test_main_kr.py'
       - 'scripts/build_cli_docs.py'
       - 'scripts/build_prompt_data.py'
+      - 'scripts/build_preset_docs.py'
       - 'scripts/build_schema_docs.py'
       - 'scripts/build_conformance_docs.py'
       - 'scripts/build_llms_txt.py'
@@ -60,6 +62,7 @@ jobs:
           generated_paths=(
             README.md
             docs/index.md
+            docs/presets.md
             docs/conformance.md
             docs/cli-reference/
             docs/llms.txt

.github/workflows/llms-txt.yaml

@@ -6,9 +6,11 @@ on:
     paths:
       - 'src/datamodel_code_generator/**'
       - 'tests/main/**'
+      - 'tests/data/jsonschema/tutorial_pet.json'
       - 'tests/test_main_kr.py'
       - 'scripts/build_cli_docs.py'
       - 'scripts/build_prompt_data.py'
+      - 'scripts/build_preset_docs.py'
       - 'src/datamodel_code_generator/parser/schema_version.py'
       - 'scripts/build_schema_docs.py'
       - 'docs/**/*.md'
@@ -45,19 +47,25 @@ jobs:
         run: tox run -vv --notest --skip-missing-interpreters false -e schema-docs
         env:
           UV_PYTHON_PREFERENCE: "only-managed"
+      - name: Setup preset docs environment
+        run: tox run -vv --notest --skip-missing-interpreters false -e preset-docs
+        env:
+          UV_PYTHON_PREFERENCE: "only-managed"
       - name: Setup llms.txt environment
         run: tox run -vv --notest --skip-missing-interpreters false -e llms-txt
         env:
           UV_PYTHON_PREFERENCE: "only-managed"
       - name: Update README
         run: .tox/readme/bin/python scripts/update_command_help_on_markdown.py
       - name: Collect CLI doc metadata
-        run: .tox/cli-docs/bin/pytest --collect-cli-docs -p no:xdist -q
+        run: .tox/cli-docs/bin/pytest tests --collect-cli-docs -p no:xdist -q
       - name: Build CLI docs
         run: .tox/cli-docs/bin/python scripts/build_cli_docs.py
       - name: Build prompt data
         run: .tox/cli-docs/bin/python scripts/build_prompt_data.py
       - name: Build schema docs
         run: .tox/schema-docs/bin/python scripts/build_schema_docs.py
+      - name: Build preset docs
+        run: .tox/preset-docs/bin/python scripts/build_preset_docs.py
       - name: Build llms.txt
         run: .tox/llms-txt/bin/python scripts/build_llms_txt.py

.github/workflows/readme.yaml

@@ -7,6 +7,9 @@ on:
       - 'src/datamodel_code_generator/**'
       - 'README.md'
       - 'docs/index.md'
+      - 'docs/presets.md'
+      - 'scripts/build_preset_docs.py'
+      - 'tests/data/jsonschema/tutorial_pet.json'
 
 permissions:
   contents: read
@@ -29,5 +32,11 @@ jobs:
         run: tox run -vv --notest --skip-missing-interpreters false -e readme
         env:
           UV_PYTHON_PREFERENCE: "only-managed"
+      - name: Setup preset docs environment
+        run: tox run -vv --notest --skip-missing-interpreters false -e preset-docs
+        env:
+          UV_PYTHON_PREFERENCE: "only-managed"
       - name: Update README
         run: .tox/readme/bin/python scripts/update_command_help_on_markdown.py
+      - name: Check preset docs
+        run: .tox/preset-docs/bin/python scripts/build_preset_docs.py --check

README.md

@@ -41,44 +41,6 @@ in another Python file to a different output type.
 
 ---
 
-## 📖 Documentation
-
-**👉 [datamodel-code-generator.koxudaxi.dev](https://datamodel-code-generator.koxudaxi.dev)**
-
-- 🖥️ [CLI Reference](https://datamodel-code-generator.koxudaxi.dev/cli-reference/) - All command-line options
-- 🧪 [Playground](https://datamodel-code-generator.koxudaxi.dev/playground/) - Try generation in your browser
-- ⚙️ [pyproject.toml](https://datamodel-code-generator.koxudaxi.dev/pyproject_toml/) - Configuration file
-- 🔄 [CI/CD Integration](https://datamodel-code-generator.koxudaxi.dev/ci-cd/) - GitHub Actions, pre-commit hooks
-- ✅ [Conformance Dashboard](https://datamodel-code-generator.koxudaxi.dev/conformance/) - External corpus coverage signals
-- 🚀 [One-liner Usage](https://datamodel-code-generator.koxudaxi.dev/oneliner/) - uvx, pipx, clipboard integration
-- ❓ [FAQ](https://datamodel-code-generator.koxudaxi.dev/faq/) - Common questions
-
----
-
-## Coding agent skill
-
-This repository includes an experimental Agent Skill that teaches compatible coding agents to run `datamodel-codegen` when generating Python models from OpenAPI, AsyncAPI, JSON Schema, GraphQL, JSON/YAML/CSV sample data, MCP tool schemas, Protocol Buffers, XML Schema, Apache Avro, or existing Python model objects.
-
-See [Coding Agent Skill](docs/coding-agent-skill.md) for detailed guidance and troubleshooting.
-
-Install the directory for your agent:
-
-```bash
-# Codex, project-local
-mkdir -p .agents/skills
-cp -R skills/datamodel-code-generator .agents/skills/datamodel-code-generator
-
-# Claude Code, project-local
-mkdir -p .claude/skills
-cp -R skills/datamodel-code-generator .claude/skills/datamodel-code-generator
-```
-
-For a personal install, copy the same directory to `$HOME/.agents/skills/datamodel-code-generator/` for Codex or `~/.claude/skills/datamodel-code-generator/` for Claude Code.
-
-Check your agent's current documentation for exact search paths.
-
----
-
 ## 📦 Installation
 
 Recommended for standalone CLI use:
@@ -137,27 +99,46 @@ docker pull koxudaxi/datamodel-code-generator
 
 ## 🏃 Quick Start
 
+<!-- BEGIN AUTO-GENERATED PRESET QUICK START -->
+**Command**
+
 ```bash
-datamodel-codegen --input schema.json --input-file-type jsonschema --output-model-type pydantic_v2.BaseModel --output model.py
+datamodel-codegen \
+  --input schema.json \
+  --input-file-type jsonschema \
+  --output-model-type pydantic_v2.BaseModel \
+  --preset standard-py312-20260619 \
+  --output model.py
 ```
 
+This quick start uses `standard-py312-20260619` as the modern Python 3.12 baseline.
+Preset names include the target Python version: `py312` means Python 3.12.
+
+See [CLI Reference](https://datamodel-code-generator.koxudaxi.dev/cli-reference/) for all options. See [Presets](https://datamodel-code-generator.koxudaxi.dev/presets/),
+[`--preset`](https://datamodel-code-generator.koxudaxi.dev/cli-reference/base-options/#preset), [`--input-file-type`](https://datamodel-code-generator.koxudaxi.dev/cli-reference/base-options/#input-file-type), and
+[`--output-model-type`](https://datamodel-code-generator.koxudaxi.dev/cli-reference/model-customization/#output-model-type) for this command.
+
+For more schema-aware output that preserves schema-authored names, reuses models, and embeds generated
+documentation, use [`practical-py312-20260619`](https://datamodel-code-generator.koxudaxi.dev/presets/#practical-py312-20260619).
+
 <details>
-<summary>📄 schema.json (input)</summary>
+<summary>Input (<code>schema.json</code>)</summary>
 
 ```json
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Pet",
   "type": "object",
-  "required": ["name", "species"],
+  "required": ["name"],
   "properties": {
     "name": {
       "type": "string",
       "description": "The pet's name"
     },
     "species": {
       "type": "string",
-      "enum": ["dog", "cat", "bird", "fish"]
+      "enum": ["dog", "cat", "bird", "fish"],
+      "default": "dog"
     },
     "age": {
       "type": "integer",
@@ -174,36 +155,52 @@ datamodel-codegen --input schema.json --input-file-type jsonschema --output-mode
 
 </details>
 
-<details>
-<summary>🐍 model.py (output)</summary>
+**Output (`model.py`)**
 
 ```python
 # generated by datamodel-codegen:
 #   filename:  schema.json
 
 from __future__ import annotations
 
-from enum import Enum
-from typing import Optional
+from enum import StrEnum
+from typing import Annotated
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field
 
 
-class Species(Enum):
+class Species(StrEnum):
     dog = 'dog'
     cat = 'cat'
     bird = 'bird'
     fish = 'fish'
 
 
 class Pet(BaseModel):
-    name: str = Field(..., description="The pet's name")
-    species: Species
-    age: Optional[int] = Field(None, description='Age in years', ge=0)
-    vaccinated: Optional[bool] = False
+    model_config = ConfigDict(
+        populate_by_name=True,
+    )
+    name: Annotated[str, Field(description="The pet's name")]
+    species: Species = Species.dog
+    age: Annotated[int | None, Field(description='Age in years', ge=0)] = None
+    vaccinated: bool = False
 ```
+<!-- END AUTO-GENERATED PRESET QUICK START -->
 
-</details>
+---
+
+## 📖 Documentation
+
+**👉 [datamodel-code-generator.koxudaxi.dev](https://datamodel-code-generator.koxudaxi.dev)**
+
+- 🧰 [Presets](https://datamodel-code-generator.koxudaxi.dev/presets/) - Recommended option bundles for modern output
+- 🖥️ [CLI Reference](https://datamodel-code-generator.koxudaxi.dev/cli-reference/) - All command-line options
+- 🧪 [Playground](https://datamodel-code-generator.koxudaxi.dev/playground/) - Try generation in your browser
+- ⚙️ [pyproject.toml](https://datamodel-code-generator.koxudaxi.dev/pyproject_toml/) - Configuration file
+- 🔄 [CI/CD Integration](https://datamodel-code-generator.koxudaxi.dev/ci-cd/) - GitHub Actions, pre-commit hooks
+- ✅ [Conformance Dashboard](https://datamodel-code-generator.koxudaxi.dev/conformance/) - External corpus coverage signals
+- 🚀 [One-liner Usage](https://datamodel-code-generator.koxudaxi.dev/oneliner/) - uvx, pipx, clipboard integration
+- ❓ [FAQ](https://datamodel-code-generator.koxudaxi.dev/faq/) - Common questions
 
 ---
 
@@ -221,12 +218,6 @@ class Pet(BaseModel):
 - Python types (Pydantic, dataclass, TypedDict) via `--input-model`
 - Python dictionary
 
-## ✅ Conformance Signals
-
-CI exercises datamodel-code-generator against pinned external corpora for XML Schema, JSON Schema, AsyncAPI, Apache
-Avro, and Protocol Buffers. See the [Conformance Dashboard](https://datamodel-code-generator.koxudaxi.dev/conformance/)
-for the generated summary of runner scripts, tox environments, CI jobs, expected corpus counts, and upstream sources.
-
 ## 📤 Supported Output
 
 - [pydantic v2](https://docs.pydantic.dev/) BaseModel
@@ -235,6 +226,12 @@ for the generated summary of runner scripts, tox environments, CI jobs, expected
 - [TypedDict](https://docs.python.org/3/library/typing.html#typing.TypedDict)
 - [msgspec](https://github.com/jcrist/msgspec) Struct
 
+## ✅ Conformance Signals
+
+CI exercises datamodel-code-generator against pinned external corpora for XML Schema, JSON Schema, AsyncAPI, Apache
+Avro, and Protocol Buffers. See the [Conformance Dashboard](https://datamodel-code-generator.koxudaxi.dev/conformance/)
+for the generated summary of runner scripts, tox environments, CI jobs, expected corpus counts, and upstream sources.
+
 ---
 
 ## 🍳 Common Recipes
@@ -288,6 +285,30 @@ See [CI/CD Integration](https://datamodel-code-generator.koxudaxi.dev/ci-cd/) fo
 
 ---
 
+## Coding agent skill
+
+This repository includes an experimental Agent Skill that teaches compatible coding agents to run `datamodel-codegen` when generating Python models from OpenAPI, AsyncAPI, JSON Schema, GraphQL, JSON/YAML/CSV sample data, MCP tool schemas, Protocol Buffers, XML Schema, Apache Avro, or existing Python model objects.
+
+See [Coding Agent Skill](docs/coding-agent-skill.md) for detailed guidance and troubleshooting.
+
+Install the directory for your agent:
+
+```bash
+# Codex, project-local
+mkdir -p .agents/skills
+cp -R skills/datamodel-code-generator .agents/skills/datamodel-code-generator
+
+# Claude Code, project-local
+mkdir -p .claude/skills
+cp -R skills/datamodel-code-generator .claude/skills/datamodel-code-generator
+```
+
+For a personal install, copy the same directory to `$HOME/.agents/skills/datamodel-code-generator/` for Codex or `~/.claude/skills/datamodel-code-generator/` for Claude Code.
+
+Check your agent's current documentation for exact search paths.
+
+---
+
 ## 💖 Sponsors
 
 <table>