Format Atlas

Guides

Choose a configuration file format

Check which formats the target tool accepts first. If several are supported, choose one the team can validate and maintain safely.

Which format should you choose?

Choose by the role each file plays in your workflow.

  • APIs and web data exchange → JSON
  • Readable nested configuration → YAML
  • Configuration centered on keys and values → TOML
  • Tool requires one format → follow its specification

Prioritize tool support

Choose configuration formats according to the application, library, CI system, and hosting environment. Confirm supported formats and specification versions.

Automate syntax validation

JSON, YAML, and TOML can all fail to load because of syntax or type errors. Validate on save or in CI, and keep credentials out of configuration files in the repository.

Formats to consider

JSON

Good for: APIs or settings that accept JSON

Less suitable for: Human-maintained settings that require comments

YAML

Good for: Nested configuration maintained by people

Less suitable for: Simple exchange where indentation errors are a concern

TOML

Good for: Configuration organized around keys and values

Less suitable for: Tools that specifically require JSON or YAML

Before you export

  • Check the format and specification version supported by the target tool.
  • Do not store credentials or private keys in the repository.

Related comparisons

JSON vs TOMLJSON is widely used for APIs and program-to-program data exchange. TOML is designed for human-edited application configuration, with readable keys, values, tables, and arrays.YAML vs TOMLYAML and TOML are both text formats used for human-edited configuration. YAML supports flexible hierarchical structures; TOML emphasizes explicit, readable settings with keys and tables. Choose for the tool and data shape.JSON vs YAMLJSON is a strict text format widely used for APIs and data exchange between programs. YAML offers syntax suited to human-edited configuration and structured data. Choose for the ecosystem and workflow.YAML vs XMLYAML and XML both represent structured data. YAML is often convenient for human-maintained configuration, while XML is common in integrations that depend on elements, attributes, schemas, or namespaces.

Guides

Choosing a Data Exchange FormatStart with the receiving system's specification. Use JSON for structured API data, XML where an integration requires its schema, and CSV for a single table.Choosing Web Data and Configuration FormatsConsider JSON for machine exchange such as APIs, YAML for configuration people edit, and XML for existing schema-based integrations.Where to keep configuration and secretsSeparate ordinary settings from credentials, then choose a suitable place for local development, CI, and production based on access and exposure risk.

References and specifications