## `--output-format` {#output-format}

Choose the command output format.

The default output format is `text`. Use `json` when another program or LLM
agent should inspect structured output.

For backward compatibility, text stdout concatenates generated modules and does
not preserve their paths. Use `--fail-on-multi-module-stdout` to reject that
case, `--output <directory>` to preserve files, or `--output-format json` for
structured stdout. The fail option takes precedence over automatic repair of an
unusable modular stdout result, so an explicitly requested guard always rejects
the modular result instead of coalescing it.

In normal generation mode, `--output-format json` wraps generated modules in a
structured payload on stdout. If `--output` is also supplied, files are still
written to disk and the JSON payload mirrors the generated files. `--check`
also supports JSON output for difference reports. `--watch` keeps its existing
text output contract and does not support `--output-format json`.

Structured JSON is emitted on stdout for successful commands and for `--check`
difference reports. CLI usage errors, validation errors, and runtime generation
errors continue to use text on stderr with a non-zero exit code.

Generation JSON includes the normalized requested output path in top-level
`output` when `--output` is supplied, or `null` for stdout generation.
`files[].path` is the output file name for single-file disk output, and the
path relative to the output directory for directory output. For stdout-only
single-file generation it is `null`, and for multi-module stdout generation it
is the generated module path.

Use `--output-format json` with `--generate-prompt` to emit structured option
metadata instead of Markdown. Use `--output-format-json-schema` when an LLM
agent or tool needs the schema for a JSON payload.

Schema targets are intentionally scoped. `generate-prompt` emits the
`PromptPayload` schema for `--generate-prompt --output-format json`.
`generation` emits only the `GenerationPayload` schema for generated-file JSON.
`model-metadata` emits the schema for files written by `--emit-model-metadata`.
`structured-output` emits the broader `StructuredOutputPayload` schema, a union
covering `GenerationPayload`, `PromptPayload`, `CommandOutputPayload`, and
`CheckOutputPayload`. Structured payloads use `kind` as the discriminator.

!!! tip "Usage"

    ```bash
    datamodel-codegen --input schema.json --output-format text # (1)!
    datamodel-codegen --input schema.json --output-format json # (2)!
    datamodel-codegen --generate-prompt --output-format json # (3)!
    datamodel-codegen --output-format-json-schema generation # (4)!
    datamodel-codegen --output-format-json-schema generate-prompt # (5)!
    datamodel-codegen --output-format-json-schema model-metadata # (6)!
    datamodel-codegen --output-format-json-schema structured-output # (7)!
    ```

    1. :material-arrow-left: Emit the default generated Python text
    2. :material-arrow-left: Emit structured JSON containing generated files
    3. :material-arrow-left: Emit structured JSON with current options and argparse metadata
    4. :material-arrow-left: Emit JSON Schema for generated-file JSON output
    5. :material-arrow-left: Emit JSON Schema for structured prompt JSON
    6. :material-arrow-left: Emit JSON Schema for generated model metadata JSON
    7. :material-arrow-left: Emit JSON Schema for any structured command JSON output

??? example "Generation JSON output"

    ```json
    {
      "version": 1,
      "format": "json",
      "kind": "generation",
      "output": null,
      "files": [
        {
          "path": null,
          "content": "# generated by datamodel-codegen:\n..."
        }
      ]
    }
    ```

??? example "Prompt JSON output"

    ```bash
    datamodel-codegen \
        --input schema.json \
        --output-model-type pydantic_v2.BaseModel \
        --generate-prompt "Choose strict model options." \
        --output-format json
    ```
