Why people convert JSON to YAML
YAML is easier to read and edit by hand: no braces, no quotes around most keys, and comments are allowed. That is why Kubernetes, Docker Compose and GitHub Actions use it for configuration. Converting a JSON export or API response gives you a starting point to edit and annotate.
YAML 1.2 was designed so that almost any JSON file is also valid YAML, so a YAML parser can often read your JSON as it is. The conversion is for people, not for parsers. The price of the friendlier look is that indentation carries meaning, so one misplaced space changes the data.
How values are written
- Plain text is left unquoted:
name: Ana Silva,city: Lisbon,zip: 1000-001. - Numbers, booleans and null keep their types:
age: 31,active: true,zip: null. - Text that looks like another type is quoted:
country: "no",version: "1.10",joined: "2001-12-14",id: "007",price: "1,000". - Keys get the same care:
"on": 1and"2022": 1are quoted, so they are not read as a boolean and a number. - A list uses a dash for each item, a list inside a list is written
- - 1, and an empty list or object is[]or{}. - A string with line breaks becomes a block:
notes: |-followed by the lines, indented.
Why the quotes matter
Older YAML 1.1 readers, which many tools still use, treat the unquoted words yes, no, on and off as booleans, and read values such as 014, 12:30:45 or 1,000 as numbers (1,5 becomes 15). The classic trap is the country code NO for Norway, which comes out as false. A quoted value is text in every YAML version, so the converter quotes anything that an older reader could take for something else. Readers that follow YAML 1.2 give the same result either way.
The quotes are a safe default, not a style choice. If you know your tool follows YAML 1.2 you can remove them by hand.
What to check afterwards
- Repeated keys. If the JSON has the same key twice in one object, only the last value is kept, as JSON readers do.
- Long numbers. Whole numbers with more than 15 digits can be rounded when the JSON is read, and a note warns you. Put such IDs in quotes in the JSON.
- Very large and very small numbers. A number such as 1e-7 or 1e21 is written with a point in front of the exponent (1.0e-7, 1.0e+21), because older readers take 1e-7 for text.
- Repeated data. Anchors and aliases are never written, so data that repeats is repeated in full. You can add anchors by hand.
- What the target accepts. The output is standard YAML. Field names and required keys are the business of the tool that reads it, and this page does not check them.