JSON to YAML: How to Convert Between Data Formats

JSON and YAML are two of the most widely used data serialization formats. JSON dominates APIs and data exchange, while YAML has become the standard for configuration files in modern DevOps tooling.

This guide compares both formats, shows conversion examples in code, and explains when to use each one.

If you want to test a conversion while reading, try the JSON to YAML Converter and use the JSON Formatter & Validator first when your input needs cleanup.

What Is JSON?

JSON (JavaScript Object Notation) is a lightweight data interchange format that uses key-value pairs and arrays. It uses curly braces for objects, square brackets for arrays, and requires quotes around all keys and string values.

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "features": ["auth", "logging", "cache"]
  },
  "database": {
    "url": "postgres://localhost:5432/mydb",
    "pool_size": 10
  }
}

What Is YAML?

YAML (YAML Ain’t Markup Language) is a human-readable data serialization format that uses indentation to structure data. It was designed to be easy for humans to read and write.

server:
  host: localhost
  port: 8080
  features:
    - auth
    - logging
    - cache
database:
  url: postgres://localhost:5432/mydb
  pool_size: 10

The same data in both formats — YAML is noticeably cleaner and easier to read.

Key Differences

When to Use JSON

• APIs — JSON is the universal format for REST and GraphQL APIs.
• Data exchange — When transferring data between systems or services.
• Web storage — localStorage, sessionStorage, and cookies all use JSON.
• Configuration in code — When you need programmatic access to config data.

When to Use YAML

• Configuration files — Docker Compose, Kubernetes manifests, GitHub Actions, Ansible playbooks.
• Human-editable settings — YAML’s readability makes it ideal for files people edit by hand.
• Documentation — YAML frontmatter is used in static site generators like Astro, Jekyll, and Hugo.
• Complex nested structures — YAML’s indentation makes deep nesting more readable than JSON.

Converting JSON to YAML

Python

import json
import yaml

with open('config.json', 'r') as f:
    data = json.load(f)

with open('config.yaml', 'w') as f:
    yaml.dump(data, f, default_flow_style=False, sort_keys=False)

JavaScript (Node.js)

const fs = require('fs');
const yaml = require('js-yaml');

const data = JSON.parse(fs.readFileSync('config.json', 'utf8'));
const output = yaml.dump(data, { lineWidth: -1, noRefs: true });
fs.writeFileSync('config.yaml', output);

Ruby

require 'json'
require 'yaml'

data = JSON.parse(File.read('config.json'))
File.write('config.yaml', data.to_yaml)

PHP

// Using Symfony YAML component
use Symfony\Component\Yaml\Yaml;

$data = json_decode(file_get_contents('config.json'), true);
$yaml = Yaml::dump($data, 4);
file_put_contents('config.yaml', $yaml);

Converting YAML to JSON

Python

import yaml
import json

with open('config.yaml', 'r') as f:
    data = yaml.safe_load(f)

with open('config.json', 'w') as f:
    json.dump(data, f, indent=2)

JavaScript (Node.js)

const fs = require('fs');
const yaml = require('js-yaml');

const data = yaml.load(fs.readFileSync('config.yaml', 'utf8'));
fs.writeFileSync('config.json', JSON.stringify(data, null, 2));

Common YAML Pitfalls

1. Use spaces, not tabs Tabs cause parsing errors. Stick to 2 spaces per indent level.

2. Colons inside values need quotes If a value contains a colon, wrap it in quotes:

url: 'https://example.com'

3. Strings that look like other types Values like true, false, null, yes, no, and bare numbers are parsed as their native types — not strings. Quote them to keep them as strings:

enabled: 'yes' # string, not boolean true

4. Trailing spaces Invisible trailing spaces can cause unexpected behavior. Use a linter to catch them.

5. Anchors and aliases YAML supports & anchors and * aliases for reuse, but they have no JSON equivalent and can confuse readers unfamiliar with the syntax.

YAML Multiline Strings

One of YAML’s clear advantages over JSON is native multiline string support:

# Literal block: preserves line breaks exactly
description: |
  This is a multiline string
  that preserves line breaks
  exactly as written.

# Folded block: line breaks become spaces
summary: >
  This is a folded string
  where line breaks become spaces
  unless there's a blank line.

In JSON, the same content requires \n escape sequences, making it much harder to read:

{
  "description": "This is a multiline string\nthat preserves line breaks\nexactly as written."
}

Conversion Risks to Review

Most JSON objects convert to YAML cleanly, but a few details deserve a manual check.

Strings that look like booleans Values such as "on", "off", "yes", "no", and "false" can be interpreted differently depending on the YAML parser and version. If the value must remain a string, quote it.

Large numbers and identifiers Long account IDs, tracking numbers, and database IDs should often stay strings. A YAML parser may preserve them, but downstream systems may not. Quote identifiers when precision matters.

Empty values JSON has explicit null. YAML can express null in several ways, including null, ~, or an empty value after a colon. Pick one style and keep it consistent.

Comments YAML supports comments, but JSON does not. If you convert YAML back to JSON, comments are usually lost. Do not store required instructions only in comments if the file will move between formats.

Review Checklist After Conversion

After converting JSON to YAML, inspect the output before committing it to a repository or deployment pipeline.

• Is indentation consistent?
• Are string identifiers still strings?
• Are URLs, cron expressions, and values with colons quoted when needed?
• Did arrays remain arrays?
• Did null values keep the intended meaning?
• Is the file still accepted by the destination tool?

For configuration files, test the converted YAML with the exact system that will read it. A file that is valid YAML can still be invalid for Docker Compose, Kubernetes, GitHub Actions, or a static site generator.

If the YAML will be committed to a repository, review the diff after conversion. YAML is indentation-sensitive, so a small visual change can represent a structural change. Confirm that lists are still lists, nested objects are still nested, and multiline strings did not collapse into a format the destination tool handles differently.

Popular Tools That Use YAML

Conclusion

JSON and YAML each have their strengths. Use JSON for APIs and data exchange where machine parsing speed matters. Use YAML for configuration files where human readability is the priority.

Understanding both formats is essential for modern web development and DevOps workflows.

Related QuickToolFlow Tools

• JSON to YAML Converter for converting configuration data between both formats.
• JSON Formatter & Validator for validating JSON before conversion.
• Whitespace Remover for cleaning copied configuration snippets.