Skip to content

aliases.md

Latest commit

 

History

History
122 lines (92 loc) · 2.98 KB

aliases.md

File metadata and controls

122 lines (92 loc) · 2.98 KB

🏷️ Field Aliases

The --aliases option allows you to rename fields in the generated models. This is useful when you want to use different Python field names than those defined in the schema while preserving the original names as serialization aliases.

🚀 Basic Usage

datamodel-codegen \
    --input schema.json \
    --output-model-type pydantic_v2.BaseModel \
    --output model.py \
    --aliases aliases.json

📋 Alias File Format

The alias file is a JSON file that maps original field names to their Python aliases.

📝 Flat Format (Traditional)

The simplest format applies aliases to all fields with the matching name, regardless of which class they belong to:

{
  "id": "id_",
  "type": "type_",
  "class": "class_"
}

This will rename all fields named id to id_, all fields named type to type_, etc.

🎯 Scoped Format (Class-Specific)

When you have the same field name in multiple classes but want different aliases for each, use the scoped format with ClassName.field:

{
  "User.name": "user_name",
  "Address.name": "address_name",
  "name": "default_name"
}

⚡ Priority: Scoped aliases take priority over flat aliases. In the example above:

  • User.name will be renamed to user_name
  • Address.name will be renamed to address_name
  • Any other class with a name field will use default_name

📝 Example

📥 Input Schema

{
  "type": "object",
  "title": "Root",
  "properties": {
    "name": {"type": "string"},
    "user": {
      "type": "object",
      "title": "User",
      "properties": {
        "name": {"type": "string"},
        "id": {"type": "integer"}
      }
    },
    "address": {
      "type": "object",
      "title": "Address",
      "properties": {
        "name": {"type": "string"},
        "city": {"type": "string"}
      }
    }
  }
}

🏷️ Alias File

{
  "Root.name": "root_name",
  "User.name": "user_name",
  "Address.name": "address_name"
}

✨ Generated Output

from pydantic import BaseModel, Field

class User(BaseModel):
    user_name: str | None = Field(None, alias='name')
    id: int | None = None

class Address(BaseModel):
    address_name: str | None = Field(None, alias='name')
    city: str | None = None

class Root(BaseModel):
    root_name: str | None = Field(None, alias='name')
    user: User | None = None
    address: Address | None = None

📌 Notes

  • The ClassName in scoped format must match the generated Python class name (after title conversion)
  • When using --use-title-as-name, the class name is derived from the title property in the schema
  • Aliases are applied during code generation, so the original field names are preserved as Pydantic alias values for proper serialization/deserialization

📖 See Also