Kubernetes and most CI tools accept both YAML and JSON for configuration, since valid JSON is (almost) valid YAML. When would you actually choose one over the other?

YAML is generally preferred for human-authored, human-maintained configuration files, since it supports comments, has less punctuation-heavy syntax (no required braces/brackets/trailing commas), and its anchor/alias mechanism enables reuse JSON doesn't have — the trade-off is YAML's own footguns (the boolean/type-coercion issues, indentation sensitivity) that JSON's stricter, more explicit syntax avoids entirely. JSON is generally preferred for machine-generated or machine-consumed configuration, and for any context where its "no ambiguity" property (every value's type is explicit and unambiguous by syntax) matters more than human readability.

The comparison is fundamentally about optimizing for human authorship versus machine precision, and the right choice depends on who's actually writing and maintaining the specific configuration in question.

YAML optimizes for human readability and maintainability: comments (#) let you document why a specific value is set a certain way directly in the config file, which JSON has no native support for at all; less required punctuation (no braces, brackets, or trailing commas needed for the common block style) reduces visual noise for a human reading or hand-editing the file; and anchors/aliases (see the related question) enable DRY reuse within a document that JSON has no equivalent for.

JSON optimizes for unambiguous, machine-precise parsing: every value's type is explicit by syntax — a string is always quoted, there's no scalar type-inference ambiguity the way YAML's bare no/yes/on/off tokens create — and JSON's stricter grammar means there's exactly one valid way to express a given structure, which matters for anything generating or comparing configuration programmatically, where YAML's flexibility (multiple equivalent ways to express the same value) can actually be a liability rather than a convenience.

YAML's human-friendliness comes with real footguns machine-generated JSON avoids entirely: the boolean/type coercion issues (the "Norway problem" covered in the related question), indentation sensitivity, and multiple equivalent ways to express the same value are all direct consequences of YAML's more permissive, human-oriented syntax — a program generating configuration doesn't benefit from YAML's readability features and only inherits its ambiguity risks, which is a real reason to prefer JSON for machine-generated config.

Practical guidance: use YAML for configuration files primarily authored and maintained by humans (Kubernetes manifests written by engineers, CI pipeline definitions, application config files edited directly) where comments and readability provide real ongoing value; use JSON for configuration that's primarily generated or consumed programmatically (an API response, a machine-to-machine config payload, output from a templating or code-generation tool) where unambiguous parsing matters more than human readability, and where a human isn't expected to hand-edit the file directly.

Kubernetes' own convention reflects this: while the Kubernetes API genuinely accepts both formats, the overwhelming real-world convention is YAML for manifests written and maintained by engineers, precisely because that's the human-authored, human-maintained case — JSON shows up more in generated output (like kubectl get -o json) or programmatic API interactions, matching the same human-versus-machine distinction.

• YAML optimizes for human authorship: comments, less required punctuation, and anchor/alias reuse that JSON has no equivalent for.
• JSON optimizes for unambiguous, machine-precise parsing: every value's type is explicit by syntax, with exactly one valid way to express a given structure.
• YAML's human-friendliness directly causes its footguns (boolean coercion, indentation sensitivity) — a program generating config gets none of YAML's readability benefit while still inheriting its ambiguity risk.
• Choose YAML for human-authored, human-maintained configuration; choose JSON for machine-generated or machine-consumed configuration where unambiguous parsing matters more than readability.

• YAML Specification: Relation to JSON
• JSON specification (RFC 8259)