Type Mappings and Custom Types¶

datamodel-code-generator allows you to customize how schema types are mapped to Python types. This is essential for projects with specific type requirements, datetime handling preferences, or third-party library integrations.

Quick Overview¶

--type-mappings¶

Maps schema type+format combinations to other format names. This allows you to override how specific formats are interpreted.

Format¶

--type-mappings <type+format>=<target_format> [<type+format>=<target_format> ...]

Basic Examples¶

# Map binary format to string (generates str instead of bytes)
datamodel-codegen --input schema.json --output models.py \
  --type-mappings "binary=string"

# Map email format to string (generates str instead of EmailStr)
datamodel-codegen --input schema.json --output models.py \
  --type-mappings "string+email=string"

# Multiple mappings
datamodel-codegen --input schema.json --output models.py \
  --type-mappings "string+email=string" "string+uuid=string"

Mapping Syntax¶

Avoiding Pydantic Optional Extras¶

Some Pydantic types require optional dependencies. Use --type-mappings to generate plain types instead:

# Avoid pydantic[email] dependency (EmailStr requires email-validator)
--type-mappings "string+email=string" "string+idn-email=string"

# Generate str instead of UUID for uuid format
--type-mappings "string+uuid=string"

Available Target Formats¶

pyproject.toml Configuration¶

[tool.datamodel-codegen]
type-mappings = [
    "string+email=string",
    "string+idn-email=string",
    "binary=string",
]

--strict-types¶

Generates Pydantic strict types that don't perform type coercion during validation.

Available Strict Types¶

Without --strict-types¶

class User(BaseModel):
    id: int        # Accepts "123" and converts to 123
    name: str      # Accepts 123 and converts to "123"
    active: bool   # Accepts 1 and converts to True

With --strict-types¶

datamodel-codegen --input schema.json --output models.py \
  --strict-types str int bool

from pydantic import StrictBool, StrictInt, StrictStr

class User(BaseModel):
    id: StrictInt      # Rejects "123", requires integer
    name: StrictStr    # Rejects 123, requires string
    active: StrictBool # Rejects 1, requires boolean

When to use¶

• API validation where type coercion is undesirable
• Data pipelines requiring exact types
• Security-sensitive applications
• Testing environments requiring strict type checking

--output-datetime-class¶

Controls the Python type used for date-time formatted strings.

Default behavior¶

from datetime import datetime

class Event(BaseModel):
    created_at: datetime  # Accepts both aware and naive

AwareDatetime (recommended for APIs)¶

datamodel-codegen --input schema.json --output models.py \
  --output-datetime-class AwareDatetime

from pydantic import AwareDatetime

class Event(BaseModel):
    created_at: AwareDatetime  # Requires timezone, e.g., 2024-01-01T00:00:00Z

NaiveDatetime¶

datamodel-codegen --input schema.json --output models.py \
  --output-datetime-class NaiveDatetime

from pydantic import NaiveDatetime

class Event(BaseModel):
    created_at: NaiveDatetime  # Rejects timezone, e.g., 2024-01-01T00:00:00

When to use each¶

--use-pendulum¶

Uses Pendulum library types instead of standard library datetime.

pip install pendulum
datamodel-codegen --input schema.json --output models.py --use-pendulum

Output¶

import pendulum

class Event(BaseModel):
    created_at: pendulum.DateTime
    date: pendulum.Date
    time: pendulum.Time

Benefits of Pendulum¶

• Timezone handling is simpler and more intuitive
• Human-friendly datetime manipulation
• Better serialization defaults
• Immutable by default

When to use¶

• Projects already using Pendulum
• Applications requiring complex datetime manipulation
• When timezone handling is a priority

--use-decimal-for-multiple-of¶

Uses Decimal type for numbers with multipleOf constraints to avoid floating-point precision issues.

The Problem¶

properties:
  price:
    type: number
    multipleOf: 0.01  # Currency precision

Without this option, floating-point arithmetic can cause validation issues:

# 0.1 + 0.2 = 0.30000000000000004 in floating-point
price = 0.30000000000000004  # May fail multipleOf validation

Solution¶

datamodel-codegen --input schema.json --output models.py \
  --use-decimal-for-multiple-of

from decimal import Decimal

class Product(BaseModel):
    price: Decimal  # Exact decimal arithmetic

When to use¶

• Financial applications
• Scientific calculations requiring precision
• Any schema with multipleOf constraints

Common Patterns¶

Pattern 1: Minimal dependencies¶

Avoid optional Pydantic dependencies by mapping special formats to plain types:

datamodel-codegen --input schema.json --output models.py \
  --type-mappings "string+email=string" "string+idn-email=string"

Pattern 2: Strict API validation¶

datamodel-codegen --input schema.json --output models.py \
  --strict-types str int float bool \
  --output-datetime-class AwareDatetime \
  --field-constraints

Pattern 3: Financial application¶

datamodel-codegen --input schema.json --output models.py \
  --use-decimal-for-multiple-of \
  --strict-types str int

Pattern 4: Pendulum datetime handling¶

datamodel-codegen --input schema.json --output models.py \
  --use-pendulum \
  --strict-types str int

Type Mapping Reference¶

Common Format Mappings¶

See Also¶

• CLI Reference: --type-mappings
• CLI Reference: --strict-types
• CLI Reference: --output-datetime-class
• CLI Reference: --use-pendulum
• Field Constraints
• Python Version Compatibility