Skip to content

Commit 61e08d4

Browse files
koxudaxipre-commit-ci[bot]
koxudaxi
and
pre-commit-ci[bot]
authored
Add model name mapping (#3444)
* Add model name mapping * style: auto-fix by pre-commit.ci * Update generated references * Quote inline JSON in CLI docs --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
1 parent 2ca6954 commit 61e08d4

34 files changed

Lines changed: 563 additions & 17 deletions

‎docs/cli-reference/index.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ This documentation is auto-generated from test cases.
1111
| 📁 [Base Options](base-options.md) | 12 | Input/output configuration |
1212
| 🔧 [Typing Customization](typing-customization.md) | 30 | Type annotation and import behavior |
1313
| 🏷️ [Field Customization](field-customization.md) | 27 | Field naming and docstring behavior |
14-
| 🏗️ [Model Customization](model-customization.md) | 41 | Model generation behavior |
14+
| 🏗️ [Model Customization](model-customization.md) | 42 | Model generation behavior |
1515
| 🎨 [Template Customization](template-customization.md) | 22 | Output formatting and custom rendering |
1616
| 📘 [OpenAPI-only Options](openapi-only-options.md) | 8 | OpenAPI-specific features |
1717
| 📋 [GraphQL-only Options](graphql-only-options.md) | 1 | |
@@ -139,6 +139,7 @@ This documentation is auto-generated from test cases.
139139

140140
- [`--model-extra-keys`](model-customization.md#model-extra-keys)
141141
- [`--model-extra-keys-without-x-prefix`](model-customization.md#model-extra-keys-without-x-prefix)
142+
- [`--model-name-map`](model-customization.md#model-name-map)
142143
- [`--module-split-mode`](general-options.md#module-split-mode)
143144

144145
### N {#n}

‎docs/cli-reference/model-customization.md‎

Lines changed: 106 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626
| [`--keyword-only`](#keyword-only) | Generate dataclasses with keyword-only fields (Python 3.10+)... |
2727
| [`--model-extra-keys`](#model-extra-keys) | Add model-level schema extensions to ConfigDict json_schema_... |
2828
| [`--model-extra-keys-without-x-prefix`](#model-extra-keys-without-x-prefix) | Strip x- prefix from model-level schema extensions and add t... |
29+
| [`--model-name-map`](#model-name-map) | Rename generated model classes from a JSON mapping. |
2930
| [`--naming-strategy`](#naming-strategy) | Use parent-prefixed naming strategy for duplicate model name... |
3031
| [`--output-model-type`](#output-model-type) | Select the output model type (Pydantic v2, Pydantic v2 datac... |
3132
| [`--parent-scoped-naming`](#parent-scoped-naming) | Namespace models by their parent scope to avoid naming confl... |
@@ -1091,7 +1092,7 @@ adding `BaseModel`. Ensure your mixins inherit from `BaseModel` if needed.
10911092
!!! tip "Usage"
10921093

10931094
```bash
1094-
datamodel-codegen --input schema.json --base-class-map "{"Person": "custom.bases.PersonBase", "Animal": "custom.bases.AnimalBase"}" # (1)!
1095+
datamodel-codegen --input schema.json --base-class-map '{"Person": "custom.bases.PersonBase", "Animal": "custom.bases.AnimalBase"}' # (1)!
10951096
```
10961097

10971098
1. :material-arrow-left: `--base-class-map` - the option documented here
@@ -1785,7 +1786,7 @@ control over dataclass generation.
17851786
!!! tip "Usage"
17861787

17871788
```bash
1788-
datamodel-codegen --input schema.json --output-model-type dataclasses.dataclass --dataclass-arguments "{"slots": true, "order": true}" # (1)!
1789+
datamodel-codegen --input schema.json --output-model-type dataclasses.dataclass --dataclass-arguments '{"slots": true, "order": true}' # (1)!
17891790
```
17901791

17911792
1. :material-arrow-left: `--dataclass-arguments` - the option documented here
@@ -2119,7 +2120,7 @@ For example, `{"model": "Schema"}` changes `Item1` to `ItemSchema`.
21192120
!!! tip "Usage"
21202121

21212122
```bash
2122-
datamodel-codegen --input schema.json --duplicate-name-suffix "{"model": "Schema"}" # (1)!
2123+
datamodel-codegen --input schema.json --duplicate-name-suffix '{"model": "Schema"}' # (1)!
21232124
```
21242125

21252126
1. :material-arrow-left: `--duplicate-name-suffix` - the option documented here
@@ -3533,6 +3534,108 @@ from the schema to the model's ConfigDict json_schema_extra with the x- prefix s
35333534

35343535
---
35353536

3537+
## `--model-name-map` {#model-name-map}
3538+
3539+
Rename generated model classes from a JSON mapping.
3540+
3541+
The `--model-name-map` option applies explicit class names to generated models.
3542+
Mapping keys can be canonical schema refs such as `#/definitions/Foo` or the
3543+
current generated class name such as `Foo1`. Values are final Python class names.
3544+
3545+
This is useful when a schema cannot be edited but generated model names must be
3546+
stable for public APIs or downstream code. Colliding mapped names fail instead
3547+
of being silently suffixed.
3548+
3549+
**Related:** [`--naming-strategy`](model-customization.md#naming-strategy), [`--use-title-as-name`](field-customization.md#use-title-as-name)
3550+
3551+
!!! tip "Usage"
3552+
3553+
```bash
3554+
datamodel-codegen --input schema.json --model-name-map '{"#/definitions/Foo": "RenamedFoo", "Bar": "RenamedBar", "model-name": "OriginalMapped"}' # (1)!
3555+
```
3556+
3557+
1. :material-arrow-left: `--model-name-map` - the option documented here
3558+
3559+
??? example "Examples"
3560+
3561+
**Input Schema:**
3562+
3563+
```json
3564+
{
3565+
"$schema": "http://json-schema.org/draft-07/schema#",
3566+
"type": "object",
3567+
"properties": {
3568+
"item": {
3569+
"$ref": "#/definitions/Foo"
3570+
},
3571+
"related": {
3572+
"$ref": "#/definitions/Bar"
3573+
},
3574+
"original": {
3575+
"$ref": "#/definitions/model-name"
3576+
}
3577+
},
3578+
"definitions": {
3579+
"Foo": {
3580+
"type": "object",
3581+
"properties": {
3582+
"value": {
3583+
"type": "string"
3584+
}
3585+
}
3586+
},
3587+
"Bar": {
3588+
"type": "object",
3589+
"properties": {
3590+
"foo": {
3591+
"$ref": "#/definitions/Foo"
3592+
}
3593+
}
3594+
},
3595+
"model-name": {
3596+
"type": "object",
3597+
"properties": {
3598+
"bar": {
3599+
"$ref": "#/definitions/Bar"
3600+
}
3601+
}
3602+
}
3603+
}
3604+
}
3605+
```
3606+
3607+
**Output:**
3608+
3609+
```python
3610+
# generated by datamodel-codegen:
3611+
# filename: model_name_map.json
3612+
# timestamp: 2019-07-26T00:00:00+00:00
3613+
3614+
from __future__ import annotations
3615+
3616+
from pydantic import BaseModel
3617+
3618+
3619+
class RenamedFoo(BaseModel):
3620+
value: str | None = None
3621+
3622+
3623+
class RenamedBar(BaseModel):
3624+
foo: RenamedFoo | None = None
3625+
3626+
3627+
class OriginalMapped(BaseModel):
3628+
bar: RenamedBar | None = None
3629+
3630+
3631+
class Model(BaseModel):
3632+
item: RenamedFoo | None = None
3633+
related: RenamedBar | None = None
3634+
original: OriginalMapped | None = None
3635+
```
3636+
3637+
---
3638+
35363639
## `--naming-strategy` {#naming-strategy}
35373640

35383641
Use parent-prefixed naming strategy for duplicate model names.

‎docs/cli-reference/quick-reference.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,7 @@ datamodel-codegen [OPTIONS]
122122
| [`--keyword-only`](model-customization.md#keyword-only) | Generate dataclasses with keyword-only fields (Python 3.10+). |
123123
| [`--model-extra-keys`](model-customization.md#model-extra-keys) | Add model-level schema extensions to ConfigDict json_schema_extra. |
124124
| [`--model-extra-keys-without-x-prefix`](model-customization.md#model-extra-keys-without-x-prefix) | Strip x- prefix from model-level schema extensions and add to ConfigDict json_sc... |
125+
| [`--model-name-map`](model-customization.md#model-name-map) | Rename generated model classes from a JSON mapping. |
125126
| [`--naming-strategy`](model-customization.md#naming-strategy) | Use parent-prefixed naming strategy for duplicate model names. |
126127
| [`--output-model-type`](model-customization.md#output-model-type) | Select the output model type (Pydantic v2, Pydantic v2 dataclass, dataclasses, T... |
127128
| [`--parent-scoped-naming`](model-customization.md#parent-scoped-naming) | Namespace models by their parent scope to avoid naming conflicts. |
@@ -313,6 +314,7 @@ All options sorted alphabetically:
313314
- [`--list-experimental`](utility-options.md#list-experimental) - List registered experimental features
314315
- [`--model-extra-keys`](model-customization.md#model-extra-keys) - Add model-level schema extensions to ConfigDict json_schema_...
315316
- [`--model-extra-keys-without-x-prefix`](model-customization.md#model-extra-keys-without-x-prefix) - Strip x- prefix from model-level schema extensions and add t...
317+
- [`--model-name-map`](model-customization.md#model-name-map) - Rename generated model classes from a JSON mapping.
316318
- [`--module-split-mode`](general-options.md#module-split-mode) - Split generated models into separate files, one per model cl...
317319
- [`--naming-strategy`](model-customization.md#naming-strategy) - Use parent-prefixed naming strategy for duplicate model name...
318320
- [`--no-alias`](field-customization.md#no-alias) - Disable Field alias generation for non-Python-safe property ...

‎docs/cli-reference/typing-customization.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1541,7 +1541,7 @@ You can pass the mapping either inline as JSON or as a path to a JSON file.
15411541
!!! tip "Usage"
15421542

15431543
```bash
1544-
datamodel-codegen --input schema.json --enum-field-as-literal-map "{"status": "literal"}" # (1)!
1544+
datamodel-codegen --input schema.json --enum-field-as-literal-map '{"status": "literal"}' # (1)!
15451545
```
15461546

15471547
1. :material-arrow-left: `--enum-field-as-literal-map` - the option documented here
@@ -2812,7 +2812,7 @@ instead of generating them.
28122812
!!! tip "Usage"
28132813

28142814
```bash
2815-
datamodel-codegen --input schema.json --type-overrides "{"CustomType": "my_app.types.CustomType"}" # (1)!
2815+
datamodel-codegen --input schema.json --type-overrides '{"CustomType": "my_app.types.CustomType"}' # (1)!
28162816
```
28172817

28182818
1. :material-arrow-left: `--type-overrides` - the option documented here

‎docs/llms-full.txt‎

Lines changed: 112 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1102,7 +1102,7 @@ This documentation is auto-generated from test cases.
11021102
| 📁 [Base Options](base-options.md) | 12 | Input/output configuration |
11031103
| 🔧 [Typing Customization](typing-customization.md) | 30 | Type annotation and import behavior |
11041104
| 🏷️ [Field Customization](field-customization.md) | 27 | Field naming and docstring behavior |
1105-
| 🏗️ [Model Customization](model-customization.md) | 41 | Model generation behavior |
1105+
| 🏗️ [Model Customization](model-customization.md) | 42 | Model generation behavior |
11061106
| 🎨 [Template Customization](template-customization.md) | 22 | Output formatting and custom rendering |
11071107
| 📘 [OpenAPI-only Options](openapi-only-options.md) | 8 | OpenAPI-specific features |
11081108
| 📋 [GraphQL-only Options](graphql-only-options.md) | 1 | |
@@ -1230,6 +1230,7 @@ This documentation is auto-generated from test cases.
12301230

12311231
- [`--model-extra-keys`](model-customization.md#model-extra-keys)
12321232
- [`--model-extra-keys-without-x-prefix`](model-customization.md#model-extra-keys-without-x-prefix)
1233+
- [`--model-name-map`](model-customization.md#model-name-map)
12331234
- [`--module-split-mode`](general-options.md#module-split-mode)
12341235

12351236
### N {#n}
@@ -2344,6 +2345,7 @@ Source: https://datamodel-code-generator.koxudaxi.dev/cli-reference/model-custom
23442345
| [`--keyword-only`](#keyword-only) | Generate dataclasses with keyword-only fields (Python 3.10+)... |
23452346
| [`--model-extra-keys`](#model-extra-keys) | Add model-level schema extensions to ConfigDict json_schema_... |
23462347
| [`--model-extra-keys-without-x-prefix`](#model-extra-keys-without-x-prefix) | Strip x- prefix from model-level schema extensions and add t... |
2348+
| [`--model-name-map`](#model-name-map) | Rename generated model classes from a JSON mapping. |
23472349
| [`--naming-strategy`](#naming-strategy) | Use parent-prefixed naming strategy for duplicate model name... |
23482350
| [`--output-model-type`](#output-model-type) | Select the output model type (Pydantic v2, Pydantic v2 datac... |
23492351
| [`--parent-scoped-naming`](#parent-scoped-naming) | Namespace models by their parent scope to avoid naming confl... |
@@ -3409,7 +3411,7 @@ adding `BaseModel`. Ensure your mixins inherit from `BaseModel` if needed.
34093411
!!! tip "Usage"
34103412

34113413
```bash
3412-
datamodel-codegen --input schema.json --base-class-map "{"Person": "custom.bases.PersonBase", "Animal": "custom.bases.AnimalBase"}" # (1)!
3414+
datamodel-codegen --input schema.json --base-class-map '{"Person": "custom.bases.PersonBase", "Animal": "custom.bases.AnimalBase"}' # (1)!
34133415
```
34143416

34153417
1. :material-arrow-left: `--base-class-map` - the option documented here
@@ -4103,7 +4105,7 @@ control over dataclass generation.
41034105
!!! tip "Usage"
41044106

41054107
```bash
4106-
datamodel-codegen --input schema.json --output-model-type dataclasses.dataclass --dataclass-arguments "{"slots": true, "order": true}" # (1)!
4108+
datamodel-codegen --input schema.json --output-model-type dataclasses.dataclass --dataclass-arguments '{"slots": true, "order": true}' # (1)!
41074109
```
41084110

41094111
1. :material-arrow-left: `--dataclass-arguments` - the option documented here
@@ -4437,7 +4439,7 @@ For example, `{"model": "Schema"}` changes `Item1` to `ItemSchema`.
44374439
!!! tip "Usage"
44384440

44394441
```bash
4440-
datamodel-codegen --input schema.json --duplicate-name-suffix "{"model": "Schema"}" # (1)!
4442+
datamodel-codegen --input schema.json --duplicate-name-suffix '{"model": "Schema"}' # (1)!
44414443
```
44424444

44434445
1. :material-arrow-left: `--duplicate-name-suffix` - the option documented here
@@ -5851,6 +5853,108 @@ from the schema to the model's ConfigDict json_schema_extra with the x- prefix s
58515853

58525854
---
58535855

5856+
## `--model-name-map` {#model-name-map}
5857+
5858+
Rename generated model classes from a JSON mapping.
5859+
5860+
The `--model-name-map` option applies explicit class names to generated models.
5861+
Mapping keys can be canonical schema refs such as `#/definitions/Foo` or the
5862+
current generated class name such as `Foo1`. Values are final Python class names.
5863+
5864+
This is useful when a schema cannot be edited but generated model names must be
5865+
stable for public APIs or downstream code. Colliding mapped names fail instead
5866+
of being silently suffixed.
5867+
5868+
**Related:** [`--naming-strategy`](model-customization.md#naming-strategy), [`--use-title-as-name`](field-customization.md#use-title-as-name)
5869+
5870+
!!! tip "Usage"
5871+
5872+
```bash
5873+
datamodel-codegen --input schema.json --model-name-map '{"#/definitions/Foo": "RenamedFoo", "Bar": "RenamedBar", "model-name": "OriginalMapped"}' # (1)!
5874+
```
5875+
5876+
1. :material-arrow-left: `--model-name-map` - the option documented here
5877+
5878+
??? example "Examples"
5879+
5880+
**Input Schema:**
5881+
5882+
```json
5883+
{
5884+
"$schema": "http://json-schema.org/draft-07/schema#",
5885+
"type": "object",
5886+
"properties": {
5887+
"item": {
5888+
"$ref": "#/definitions/Foo"
5889+
},
5890+
"related": {
5891+
"$ref": "#/definitions/Bar"
5892+
},
5893+
"original": {
5894+
"$ref": "#/definitions/model-name"
5895+
}
5896+
},
5897+
"definitions": {
5898+
"Foo": {
5899+
"type": "object",
5900+
"properties": {
5901+
"value": {
5902+
"type": "string"
5903+
}
5904+
}
5905+
},
5906+
"Bar": {
5907+
"type": "object",
5908+
"properties": {
5909+
"foo": {
5910+
"$ref": "#/definitions/Foo"
5911+
}
5912+
}
5913+
},
5914+
"model-name": {
5915+
"type": "object",
5916+
"properties": {
5917+
"bar": {
5918+
"$ref": "#/definitions/Bar"
5919+
}
5920+
}
5921+
}
5922+
}
5923+
}
5924+
```
5925+
5926+
**Output:**
5927+
5928+
```python
5929+
# generated by datamodel-codegen:
5930+
# filename: model_name_map.json
5931+
# timestamp: 2019-07-26T00:00:00+00:00
5932+
5933+
from __future__ import annotations
5934+
5935+
from pydantic import BaseModel
5936+
5937+
5938+
class RenamedFoo(BaseModel):
5939+
value: str | None = None
5940+
5941+
5942+
class RenamedBar(BaseModel):
5943+
foo: RenamedFoo | None = None
5944+
5945+
5946+
class OriginalMapped(BaseModel):
5947+
bar: RenamedBar | None = None
5948+
5949+
5950+
class Model(BaseModel):
5951+
item: RenamedFoo | None = None
5952+
related: RenamedBar | None = None
5953+
original: OriginalMapped | None = None
5954+
```
5955+
5956+
---
5957+
58545958
## `--naming-strategy` {#naming-strategy}
58555959

58565960
Use parent-prefixed naming strategy for duplicate model names.
@@ -14480,7 +14584,7 @@ You can pass the mapping either inline as JSON or as a path to a JSON file.
1448014584
!!! tip "Usage"
1448114585

1448214586
```bash
14483-
datamodel-codegen --input schema.json --enum-field-as-literal-map "{"status": "literal"}" # (1)!
14587+
datamodel-codegen --input schema.json --enum-field-as-literal-map '{"status": "literal"}' # (1)!
1448414588
```
1448514589

1448614590
1. :material-arrow-left: `--enum-field-as-literal-map` - the option documented here
@@ -15751,7 +15855,7 @@ instead of generating them.
1575115855
!!! tip "Usage"
1575215856

1575315857
```bash
15754-
datamodel-codegen --input schema.json --type-overrides "{"CustomType": "my_app.types.CustomType"}" # (1)!
15858+
datamodel-codegen --input schema.json --type-overrides '{"CustomType": "my_app.types.CustomType"}' # (1)!
1575515859
```
1575615860

1575715861
1. :material-arrow-left: `--type-overrides` - the option documented here
@@ -26723,6 +26827,7 @@ datamodel-codegen [OPTIONS]
2672326827
| [`--keyword-only`](model-customization.md#keyword-only) | Generate dataclasses with keyword-only fields (Python 3.10+). |
2672426828
| [`--model-extra-keys`](model-customization.md#model-extra-keys) | Add model-level schema extensions to ConfigDict json_schema_extra. |
2672526829
| [`--model-extra-keys-without-x-prefix`](model-customization.md#model-extra-keys-without-x-prefix) | Strip x- prefix from model-level schema extensions and add to ConfigDict json_sc... |
26830+
| [`--model-name-map`](model-customization.md#model-name-map) | Rename generated model classes from a JSON mapping. |
2672626831
| [`--naming-strategy`](model-customization.md#naming-strategy) | Use parent-prefixed naming strategy for duplicate model names. |
2672726832
| [`--output-model-type`](model-customization.md#output-model-type) | Select the output model type (Pydantic v2, Pydantic v2 dataclass, dataclasses, T... |
2672826833
| [`--parent-scoped-naming`](model-customization.md#parent-scoped-naming) | Namespace models by their parent scope to avoid naming conflicts. |
@@ -26914,6 +27019,7 @@ All options sorted alphabetically:
2691427019
- [`--list-experimental`](utility-options.md#list-experimental) - List registered experimental features
2691527020
- [`--model-extra-keys`](model-customization.md#model-extra-keys) - Add model-level schema extensions to ConfigDict json_schema_...
2691627021
- [`--model-extra-keys-without-x-prefix`](model-customization.md#model-extra-keys-without-x-prefix) - Strip x- prefix from model-level schema extensions and add t...
27022+
- [`--model-name-map`](model-customization.md#model-name-map) - Rename generated model classes from a JSON mapping.
2691727023
- [`--module-split-mode`](general-options.md#module-split-mode) - Split generated models into separate files, one per model cl...
2691827024
- [`--naming-strategy`](model-customization.md#naming-strategy) - Use parent-prefixed naming strategy for duplicate model name...
2691927025
- [`--no-alias`](field-customization.md#no-alias) - Disable Field alias generation for non-Python-safe property ...

0 commit comments

Comments
 (0)