# 📋 Generate from JSON Schema

Generate Pydantic models from JSON Schema definitions. See [Supported Data Types](./supported-data-types.md#openapi-3-and-json-schema) for supported JSON Schema features.

## 🚀 Quick Start

```bash
datamodel-codegen \
    --input person.json \
    --input-file-type jsonschema \
    --output-model-type pydantic_v2.BaseModel \
    --use-annotated \
    --output model.py
```

## 📝 Example

**person.json**
```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Person",
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string",
      "description": "The person's first name."
    },
    "lastName": {
      "type": "string",
      "description": "The person's last name."
    },
    "age": {
      "description": "Age in years which must be equal to or greater than zero.",
      "type": "integer",
      "minimum": 0
    },
    "friends": {
      "type": "array"
    },
    "comment": {
      "type": "null"
    }
  }
}
```


**✨ Generated model.py**
```python
# generated by datamodel-codegen:
#   filename:  person.json
#   timestamp: 2020-04-27T16:12:27+00:00

from __future__ import annotations

from typing import Annotated, Any

from pydantic import BaseModel, Field


class Person(BaseModel):
    firstName: Annotated[str | None, Field(description="The person's first name.")] = None
    lastName: Annotated[str | None, Field(description="The person's last name.")] = None
    age: Annotated[
        int | None,
        Field(
            description='Age in years which must be equal to or greater than zero.',
            ge=0,
        ),
    ] = None
    friends: list[Any] | None = None
    comment: Annotated[None, Field(None)] = None
```

## Tuple validation

JSON Schema's [`prefixItems`](https://json-schema.org/understanding-json-schema/reference/array.html#tuple-validation) syntax lets you describe heterogeneous arrays.

When:

- `prefixItems` is present
- no `items` are specified
- `minItems`/`maxItems` match the number of prefix entries

datamodel-code-generator emits precise tuple annotations.

### Example

```json
{
  "$defs": {
    "Span": {
      "type": "object",
      "properties": {
        "value": { "type": "integer" }
      },
      "required": ["value"]
    }
  },
  "title": "defaults",
  "type": "object",
  "properties": {
    "a": {
      "type": "array",
      "prefixItems": [
        { "$ref": "#/$defs/Span" },
        { "type": "string" }
      ],
      "minItems": 2,
      "maxItems": 2
    }
  },
  "required": ["a"]
}
```

```py
from pydantic import BaseModel


class Span(BaseModel):
    value: int


class Defaults(BaseModel):
    a: tuple[Span, str]
```

---

## Custom Base Class with `customBasePath`

You can specify custom base classes directly in your JSON Schema using the `customBasePath` extension. This allows you to define base classes at the schema level without using CLI options.

### Single Base Class

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "User",
  "type": "object",
  "customBasePath": "myapp.models.UserBase",
  "properties": {
    "name": {"type": "string"},
    "email": {"type": "string"}
  },
  "required": ["name", "email"]
}
```

**Generated Output:**

```python
from __future__ import annotations

from myapp.models import UserBase


class User(UserBase):
    name: str
    email: str
```

### Multiple Base Classes (Mixins)

You can also specify multiple base classes as a list to implement mixin patterns:

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "User",
  "type": "object",
  "customBasePath": ["mixins.AuditMixin", "mixins.TimestampMixin"],
  "properties": {
    "name": {"type": "string"},
    "email": {"type": "string"}
  },
  "required": ["name", "email"]
}
```

**Generated Output:**

```python
from __future__ import annotations

from mixins import AuditMixin, TimestampMixin


class User(AuditMixin, TimestampMixin):
    name: str
    email: str
```

!!! note "Mixin Usage"
    When using multiple base classes, the specified classes are used directly without adding `BaseModel`.
    Ensure your mixins inherit from `pydantic.BaseModel` if you need Pydantic model behavior.

### Priority Resolution

When multiple base class configurations are present, they are resolved in this order:

1. **`--base-class-map`** (CLI option) - Highest priority
2. **`customBasePath`** (JSON Schema extension)
3. **`--base-class`** (CLI option) - Lowest priority (default for all models)

This allows you to set a default base class with `--base-class`, override specific models in the schema with `customBasePath`, and further override at the CLI level with `--base-class-map`.

## Supported JSON Schema Features

| Feature | Generation behavior |
|---------|---------------------|
| Object properties and required fields | Generated as model fields |
| `$ref`, `$defs`, and `definitions` | Resolved before model generation |
| `oneOf`, `anyOf`, `allOf` | Converted into unions and composed models where possible |
| Scalar constraints | Generated as `Field(...)` metadata with `--field-constraints` / `--use-annotated` |
| `format` values | Mapped to Python/Pydantic types where supported |
| Custom extensions | `customBasePath` and related options can steer generated base classes |

## Limitations

JSON Schema input generates Python model definitions. It does not perform runtime validation by itself, and some
schema keywords are represented as type hints or field metadata rather than full JSON Schema validator behavior. See
[Schema Version Support](supported_formats.md) for version-specific coverage.

---

## 📖 See Also

- 🚀 [Getting Started](getting-started.md) - Installation and first model
- 🖥️ [CLI Reference](cli-reference/index.md) - Complete CLI options reference
- 🔧 [CLI Reference: Typing Customization](cli-reference/typing-customization.md) - Type annotation options
- 🏷️ [CLI Reference: Field Customization](cli-reference/field-customization.md) - Field naming and constraint options
- 📊 [Supported Data Types](supported-data-types.md) - JSON Schema data type support
- 🏗️ [CLI Reference: Model Customization](cli-reference/model-customization.md) - Base class and model customization options
