Skip to content

base-options.md

Latest commit

 

History

History
388 lines (269 loc) · 8.82 KB

base-options.md

File metadata and controls

388 lines (269 loc) · 8.82 KB

📁 Base Options

📋 Options

Option Description
--encoding Specify character encoding for input and output files.
--input Specify the input schema file path.
--input-file-type Specify the input file type for code generation.
--input-model Import a Python type or dict schema from a module.
--input-model-ref-strategy Strategy for referenced types when using --input-model.
--output Specify the destination path for generated Python code.
--url Fetch schema from URL with custom HTTP headers.

--encoding {#encoding}

Specify character encoding for input and output files.

The --encoding flag sets the character encoding used when reading the schema file and writing the generated Python code. This is useful for schemas containing non-ASCII characters (e.g., Japanese, Chinese). Default is UTF-8, which is the standard encoding for JSON and most modern text files.

!!! tip "Usage"

```bash
datamodel-codegen --input schema.json --encoding utf-8 # (1)!
```

1. :material-arrow-left: `--encoding` - the option documented here

??? example "Examples"

**Input Schema:**

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "日本語Model",
  "description": "モデルの説明文",
  "type": "object",
  "properties": {
    "名前": {
      "type": "string",
      "description": "ユーザー名"
    },
    "年齢": {
      "type": "integer"
    }
  }
}
```

**Output:**

```python
# generated by datamodel-codegen:
#   filename:  encoding_test.json
#   timestamp: 2019-07-26T00:00:00+00:00

from __future__ import annotations

from pydantic import BaseModel, Field


class 日本語Model(BaseModel):
    名前: str | None = Field(None, description='ユーザー名')
    年齢: int | None = None
```

--input {#input}

Specify the input schema file path.

The --input flag specifies the path to the schema file (JSON Schema, OpenAPI, GraphQL, etc.). Multiple input files can be specified to merge schemas. Required unless using --url to fetch schema from a URL.

!!! tip "Usage"

```bash
datamodel-codegen --input schema.json --input pet_simple.json --output output.py # (1)!
```

1. :material-arrow-left: `--input` - the option documented here

??? example "Examples"

**Input Schema:**

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Pet",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer"
    },
    "name": {
      "type": "string"
    },
    "tag": {
      "type": "string"
    }
  }
}
```

**Output:**

```python
# generated by datamodel-codegen:
#   filename:  pet_simple.json
#   timestamp: 2019-07-26T00:00:00+00:00

from __future__ import annotations

from pydantic import BaseModel


class Pet(BaseModel):
    id: int | None = None
    name: str | None = None
    tag: str | None = None
```

--input-file-type {#input-file-type}

Specify the input file type for code generation.

The --input-file-type flag explicitly sets the input format.

Important distinction:

  • Use jsonschema, openapi, or graphql for schema definition files
  • Use json, yaml, or csv for raw sample data to automatically infer a schema

For example, if you have a JSON Schema written in YAML format, use --input-file-type jsonschema, not --input-file-type yaml. The yaml type treats the file as raw data and infers a schema from it.

!!! tip "Usage"

```bash
datamodel-codegen --input schema.json --input-file-type json # (1)!
```

1. :material-arrow-left: `--input-file-type` - the option documented here

??? example "Examples"

=== "JSON"

    **Input Schema:**

    ```json
    {
      "Pet": {
        "name": "dog",
        "age": 2
      }
    }
    ```

    **Output:**

    ```python
    # generated by datamodel-codegen:
    #   filename:  pet.json
    #   timestamp: 2019-07-26T00:00:00+00:00
    
    from __future__ import annotations
    
    from pydantic import BaseModel
    
    
    class Pet(BaseModel):
        name: str
        age: int
    
    
    class Model(BaseModel):
        Pet: Pet
    ```

=== "YAML"

    **Input Schema:**

    ```yaml
    Pet:
      name: cat
      age: 3
    ```

    **Output:**

    ```python
    # generated by datamodel-codegen:
    #   filename:  pet.yaml
    #   timestamp: 2019-07-26T00:00:00+00:00
    
    from __future__ import annotations
    
    from pydantic import BaseModel
    
    
    class Pet(BaseModel):
        name: str
        age: int
    
    
    class Model(BaseModel):
        Pet: Pet
    ```

--input-model {#input-model}

Import a Python type or dict schema from a module.

Use the format module:Object or path/to/file.py:Object to specify the type.

!!! tip "Usage"

```bash
datamodel-codegen --input schema.json --input-model mymodule:MyModel # (1)!
```

1. :material-arrow-left: `--input-model` - the option documented here

??? example "Examples"

**Output:**

--input-model-ref-strategy {#input-model-ref-strategy}

Strategy for referenced types when using --input-model.

The --input-model-ref-strategy option determines whether to regenerate or import referenced types. Use regenerate-all (default) to regenerate all types, reuse-foreign to import types from different families (like enums when generating dataclasses) while regenerating same-family types, or reuse-all to import all referenced types directly.

!!! tip "Usage"

```bash
datamodel-codegen --input schema.json --input-model-ref-strategy reuse-foreign # (1)!
```

1. :material-arrow-left: `--input-model-ref-strategy` - the option documented here

??? example "Examples"

**Output:**

--output {#output}

Specify the destination path for generated Python code.

The --output flag specifies where to write the generated Python code. It can be either a file path (single-file output) or a directory path (multi-file output for modular schemas). If omitted, the generated code is written to stdout.

!!! tip "Usage"

```bash
datamodel-codegen --input schema.json --input pet_simple.json --output output.py # (1)!
```

1. :material-arrow-left: `--output` - the option documented here

??? example "Examples"

**Input Schema:**

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Pet",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer"
    },
    "name": {
      "type": "string"
    },
    "tag": {
      "type": "string"
    }
  }
}
```

**Output:**

```python
# generated by datamodel-codegen:
#   filename:  pet_simple.json
#   timestamp: 2019-07-26T00:00:00+00:00

from __future__ import annotations

from pydantic import BaseModel


class Pet(BaseModel):
    id: int | None = None
    name: str | None = None
    tag: str | None = None
```

--url {#url}

Fetch schema from URL with custom HTTP headers.

The --url flag specifies a remote URL to fetch the schema from instead of a local file. The --http-headers flag adds custom HTTP headers to the request, useful for authentication (e.g., Bearer tokens) or custom API requirements. Format: HeaderName:HeaderValue.

!!! tip "Usage"

```bash
datamodel-codegen --input schema.json --url https://api.example.com/schema.json --http-headers "Authorization:Bearer token" # (1)!
```

1. :material-arrow-left: `--url` - the option documented here

??? example "Examples"

**Input Schema:**

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Pet",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer"
    },
    "name": {
      "type": "string"
    },
    "tag": {
      "type": "string"
    }
  }
}
```

**Output:**

```python
# generated by datamodel-codegen:
#   filename:  https://api.example.com/schema.json
#   timestamp: 2019-07-26T00:00:00+00:00

from __future__ import annotations

from pydantic import BaseModel


class Pet(BaseModel):
    id: int | None = None
    name: str | None = None
    tag: str | None = None
```