YAML Formatter

YAML syntax essentials — the parts that trip people up

YAML (YAML Ain't Markup Language) uses indentation instead of brackets to denote structure. This makes it human-readable but sensitive to whitespace errors. Understanding the indentation rules prevents the most common YAML bugs.

Indentation must be consistent within a block. YAML requires spaces (not tabs) for indentation — a tab character in YAML indentation is a parse error. Two spaces per level is the most common convention. You cannot mix two-space and four-space indentation within the same file.

Scalar values have implicit types. The string true, false, yes, no, on, off are interpreted as booleans in YAML 1.1 (and in many implementations). The string 0644 is interpreted as an octal integer. Strings that look like numbers or booleans must be quoted: '"true"' or "'yes'" to force string interpretation. This is a common source of bugs in Kubernetes and GitHub Actions configuration.

Multi-line strings use two block scalar indicators: the literal block scalar (|) preserves newlines; the folded block scalar (>) folds newlines into spaces. A trailing newline is added by default (strip it with |- or >-).

Anchors (&name) and aliases (*name) allow reuse: define a value once with an anchor and reference it elsewhere with an alias. The alias expands to a copy of the anchored value at parse time.

YAML in DevOps — where it appears and common pitfalls

YAML has become the dominant configuration format in the DevOps ecosystem, appearing across all major platforms.

Kubernetes: nearly all resource definitions (Pods, Deployments, Services, ConfigMaps, Secrets) are written in YAML. The indentation sensitivity causes frequent errors — a misaligned key changes a resource's field or produces a parse error that Kubernetes reports as a cryptic validation failure. Use kubectl apply --dry-run=client -f file.yaml to validate before applying.

GitHub Actions: workflow files (.github/workflows/*.yml) define CI/CD pipelines. YAML anchors are useful for reusing step sequences. The on: trigger key requires quoting in some YAML parsers (on is a boolean-like value in YAML 1.1). GitHub Actions uses a YAML 1.1-compatible parser.

Docker Compose: compose.yml files define multi-container applications. Version-specific field names (services, volumes, networks) use consistent two-space indentation. Environment variable values should be quoted to prevent type coercion.

Helm charts: Helm uses Go templating inside YAML files, creating a challenging combination — Go template expressions ({{ }}) must be syntactically valid when the template language is stripped. Multi-line values in Helm often use the | block scalar to preserve content that would otherwise need extensive escaping.

YAML to JSON and back — lossless vs lossy conversion

YAML is a superset of JSON, which means all valid JSON is valid YAML. This makes YAML → JSON conversion reliable and lossless for the JSON-compatible subset of YAML.

However, YAML features that have no JSON equivalent create conversion challenges. Comments are lost: JSON has no comment syntax, so all YAML comments are discarded during conversion. Anchors and aliases are expanded: the referenced value is inlined, and the anchor/alias relationship is lost. Multi-document streams (--- separators) cannot be represented in a single JSON object — only the first document can be converted.

YAML's additional scalar types (dates, timestamps, explicit type tags like !!binary) either map to JSON strings or fail conversion depending on the parser. The YAML date 2024-01-15 may become the JSON string "2024-01-15" — the semantic meaning is preserved in the string but the type information is not.

JSON → YAML conversion is fully lossless: JSON's subset of types (string, number, boolean, null, array, object) all have direct YAML equivalents. JSON objects become YAML mappings, JSON arrays become YAML sequences. The only transformation is formatting — JSON's brace syntax becomes YAML's indented block syntax.