Convert JSON and YAML configuration files safely

Problem

JSON and YAML can represent the same basic mappings, sequences, strings, numbers, booleans, and empty values, but the formats are not interchangeable in every detail. YAML comments, anchors, aliases, tags, and document streams do not have equivalent JSON syntax. Duplicate keys and long numeric literals can also disappear or change when a weak converter keeps only the last key or rounds a browser number. This workflow checks the source, identifies syntax that cannot survive, and validates the result in the destination product before it is deployed.

Sources and standards

These authoritative references define the formats or security boundaries used in this workflow. Tool-specific verification is documented separately above.

• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format

  RFC Editor / IETF

• YAML Ain't Markup Language, Version 1.2.2

  YAML Language Development Team

When to use this

• An application settings file must move from JSON to a YAML-based config system.
• A single Kubernetes, Docker Compose, or CI YAML example needs a JSON representation for inspection or tooling.
• A support case needs a small reproducible config in the format preferred by another team.
• A repository change should be reviewed in both JSON and YAML before it is committed or deployed.

Steps

1. Step 1

   Identify the source standard and destination consumer

   Confirm that the YAML is intended for YAML 1.2 behavior and that the source contains one document. Record the product that will consume the result, such as kubectl, Docker Compose, a CI provider, an API client, or an application settings loader. Format conversion cannot replace that product's schema validation.

2. Step 2

   Reduce the file to the configuration that must move

   Remove unrelated secrets, generated sections, disabled examples, and environment-specific values before pasting. Keep a backup of the original file because comments, scalar styles, anchors, and aliases may not have an equivalent representation in the destination format.

3. Step 3

   Convert one document with strict loss checks

   Choose JSON to YAML or YAML to JSON, select two-space or four-space indentation, and use Pretty JSON while reviewing. Fix strict syntax locations, duplicate keys, non-string YAML collection keys, unsupported tags, and numeric literals that would change instead of allowing the converter to guess.

4. Step 4

   Review comments, anchors, aliases, and scalar types

   YAML comments are removed because JSON has no comment syntax. Bounded anchors and aliases are expanded into repeated values, so the relationship itself is lost. Verify quoted date-like strings, leading-zero identifiers, null values, booleans, multiline strings, and every value called out by a warning.

5. Step 5

   Compare the structure and edge values

   Compare top-level keys, nested paths, array lengths, key order where your review process relies on it, and the reported node and maximum-depth counts. Pay special attention to __proto__, constructor, integer-looking key names, large identifiers, negative zero, and decimal values with many significant digits.

6. Step 6

   Validate and test in the destination

   Download the current result and run the destination validator or a dry run. For Kubernetes use its schema-aware tooling, for Docker Compose use its config validation, and for CI or application settings use the provider's own parser. Compare the effective configuration with the original intent before committing or deploying.

Example

{
  "service": {
    "name": "api",
    "ports": [8080, 8081],
    "release": "2026-07-15",
    "enabled": true
  }
}

service:
  name: api
  ports:
    - 8080
    - 8081
  release: 2026-07-15
  enabled: true

Common mistakes

FAQ