JSON to YAML Tutorial: Convert JSON to Readable Config

Q: Is every JSON file valid YAML?

Yes, with a minor caveat. JSON is a valid subset of YAML 1.2, meaning any valid JSON file is also a valid YAML 1.2 document. A YAML 1.2 parser can parse a JSON file without modification. However, YAML 1.1 parsers — which many older tools implement — have a few edge cases where JSON strings with certain escape sequences or Unicode characters are not handled identically. In practice, treating JSON as valid YAML works in the vast majority of environments. Libraries like js-yaml version 4+ default to YAML 1.2 compliance and accept JSON input cleanly.

Q: What gets changed during JSON to YAML conversion?

During JSON to YAML conversion, curly braces {} around objects are replaced with indented key-value pairs. Square brackets [] around arrays are replaced with - prefixed list items. Double-quoted string delimiters are removed from most strings — bare unquoted strings are used when they are unambiguous. The comma delimiter between fields is removed. The overall structure becomes indentation-based rather than bracket-based. String values that look like booleans, numbers, or dates should be kept quoted to avoid type coercion — a good converter does this automatically. Comments cannot be added automatically because comments are a human authoring choice.

Q: How does YAML represent null and boolean?

YAML has multiple ways to represent null: the keyword null, the tilde ~, or an empty value. JSON only has null. YAML booleans can be written as true, false (YAML 1.2) or also yes, no, on, off (YAML 1.1 only). JSON only accepts true and false. When converting JSON to YAML, well-designed converters use the canonical YAML 1.2 forms: null for null and true/false for booleans, which are unambiguous. When converting YAML back to JSON, all null variants and all boolean variants must be normalized to JSON null, true, and false respectively.

Q: What happens to JSON strings with special characters in YAML?

JSON strings with special characters must be quoted in YAML to avoid misinterpretation. A string starting with a colon, dash, or bracket may be misread as YAML structure. A string containing # may have the rest treated as a comment. Strings that look like numbers (e.g., "1.0"), dates (e.g., "2026-01-01"), or booleans (e.g., "true") must be quoted to remain strings. A good JSON-to-YAML converter handles this by quoting any string that could be misread. If you are converting by hand, err on the side of quoting strings that contain any of these characters: : # [ ] { } | > ! & * ? - , @

Q: Can I convert JSON to YAML in Python?

Yes. Python has a simple workflow for JSON to YAML conversion using the built-in json module and the PyYAML library. Install PyYAML with: pip install pyyaml. Then: import json, yaml; data = json.loads(json_string); print(yaml.dump(data, default_flow_style=False, allow_unicode=True)). The default_flow_style=False option produces block-style YAML (indented, multi-line) instead of inline JSON-like syntax. The allow_unicode=True option prevents non-ASCII characters from being escaped. PyYAML generates YAML 1.1 by default. For YAML 1.2 compliance, use the ruamel.yaml library instead.

Q: Does YAML preserve number types from JSON?

Yes, when converting JSON numbers to YAML, integers and floats are preserved as bare unquoted values that YAML parsers will interpret as the correct numeric type. A JSON integer like 42 becomes the YAML bare value 42, and a JSON float like 3.14 becomes the YAML bare value 3.14. The distinction between integer and float is maintained by the presence or absence of a decimal point. However, JSON strings that contain numbers — like the ZIP code "00123" — must remain quoted in YAML, otherwise the leading zero is lost and the value becomes the integer 123. A good converter preserves the JSON type and quotes string representations of numbers.

Last updated: May 11, 2026

Converting JSON to YAML removes all 4 structural tokens — curly braces, square brackets, commas, and most quotes — and replaces them with indentation-based block syntax. The 6 JSON types map 1-to-1: strings become bare scalars (quoted only when they look like a boolean, number, or date), numbers stay as-is, true/falseremain literal, null becomes ~ or null, arrays get a - prefix per item, and objects become indented key-value pairs. JSON is a valid YAML 1.2 subset, so any JSON file parses without changes in js-yaml v4+ and ruamel.yaml, though 5 YAML 1.1 strings (yes, no, on, off, y) coerce to booleans if unquoted. This guide covers object and array conversion examples, type-preservation rules, indentation requirements, Python conversion with PyYAML, and 5 common mistakes.

Convert a JSON object to YAML

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "debug": true
  }
}

server:
  host: localhost
  port: 8080
  debug: true

Convert JSON arrays to YAML lists

JSON arrays become YAML sequences. Arrays of objects become repeated list items with nested fields.

{
  "plugins": [
    { "name": "auth", "enabled": true },
    { "name": "billing", "enabled": false }
  ]
}

plugins:
  - name: auth
    enabled: true
  - name: billing
    enabled: false

Preserve JSON types

JSON values should map to the equivalent YAML type. Strings that look like booleans, numbers, or dates should be quoted if you want them to remain strings.

{
  "enabled": true,
  "retries": 3,
  "version": "1.0",
  "zip": "00123",
  "deletedAt": null
}

enabled: true
retries: 3
version: "1.0"
zip: "00123"
deletedAt: ~

Watch YAML indentation

YAML structure depends on indentation. Use spaces, not tabs, and keep nesting consistent.

# Good
database:
  host: localhost
  pool:
    min: 2
    max: 10

# Bad: inconsistent indentation changes structure or fails parsing
database:
 host: localhost
  pool:
    min: 2

Common JSON to YAML mistakes

Forgetting to quote strings that look like numbers, dates, or booleans.
Mixing tabs and spaces.
Changing nested structure while hand-editing indentation.
Assuming comments from YAML can be converted back to JSON.
Using YAML features that the target tool does not support.

Convert JSON to YAML online

Paste JSON into Jsonic's JSON to YAML converter to produce readable YAML locally in your browser.

Open JSON to YAML

Frequently asked questions

Is every JSON file valid YAML?

Yes. JSON is a valid subset of YAML 1.2 — any valid JSON file is also valid YAML 1.2. Libraries like js-yaml v4+ and ruamel.yaml default to YAML 1.2 compliance and accept JSON input cleanly.

What gets changed during JSON to YAML conversion?

Curly braces become indented key-value pairs. Square brackets become - prefixed list items. Commas and most quotes are removed. Strings that look like booleans, numbers, or dates should stay quoted. Comments cannot be added automatically — they are a human authoring choice.

How does YAML represent null and boolean?

YAML null can be written as null, ~, or an empty value. Booleans are true/false in YAML 1.2 (plus yes/no/on/off in YAML 1.1 only). A good converter uses YAML 1.2 canonical forms to avoid ambiguity when converting back to JSON.

What happens to JSON strings with special characters in YAML?

Strings containing : # [ ] or values that look like numbers, dates, or booleans must be quoted in YAML. A good converter handles this automatically. When converting by hand, err on the side of quoting any string with these characters.

Can I convert JSON to YAML in Python?

Yes. Install PyYAML (pip install pyyaml), then: import json, yaml; data = json.loads(json_string); print(yaml.dump(data, default_flow_style=False, allow_unicode=True)). For YAML 1.2 compliance use ruamel.yaml instead of PyYAML.

Does YAML preserve number types from JSON?

Yes. JSON integers and floats become bare YAML values (42, 3.14) with types inferred from the presence of a decimal point. JSON string numbers like "00123" must remain quoted to avoid losing the leading zero.