← Back to TechDriven Tools Hire developers →

Published · 5 min read · By TechDriven Tools editorial team · Utilities

JSON and YAML — when to use which

A practical split between JSON and YAML for configs and APIs, plus how to convert them locally.

JSON and YAML — when to use which

They are both data, not programs

JSON is a strict text format for objects, arrays, strings, numbers, booleans, and null. YAML is a looser format that many teams use for configuration because indentation is easier to read than braces. Neither one should be executed. If a tool offers to “run” your YAML, close it. Conversion is parsing and printing. That is all the YAML and JSON page on this site does.

Use JSON when a program will read the file without a human in the middle: an API body, a package manifest, a payload you log. Use YAML when a person will edit the file by hand and the consumer is a tool that already speaks YAML: a CI config, a Kubernetes manifest, an Ansible play. Do not invent a third format for a single feature flag. The cost of a format is the parser you now have to trust.

Where JSON hurts

JSON has no comments. People fake them with a "_comment" key, which then leaks into production if someone forgets to strip it. JSON forbids trailing commas, so a merge conflict in an array is a syntax error, not a warning. JSON Formatter on this site parses with the browser’s JSON.parse. If you have a trailing comma, it fails. That is the correct failure. A formatter that “fixes” JSON by guessing will also “fix” a string you did not mean to change.

JSON keys are strings. Numbers are not quoted unless you want them to stay strings. A zip code 01101 must be a string or the leading zero dies. CSV to JSON on this site keeps every cell as a string for that reason. If you need numbers, convert them in your code after you have decided which columns are numeric.

Where YAML hurts

YAML’s indentation is the feature and the bug. A space instead of two spaces changes the tree. Tabs are a good way to produce a file that looks aligned and parses as something else. The converter uses a real parser. If the indentation is wrong, you get an error, not a partial object. That is what you want before you paste the result into a cluster.

YAML also has types you did not ask for. The unquoted word yes has historically been read as a boolean in some parsers. Unquoted NO can become false. Country codes and version strings surprise people. Quote strings when the value is a code, a version, or anything that must stay text. country: "NO" is a country. country: NO might not be, depending on the parser version. I will not list every historical footgun. The practical rule is: quote strings that are not obviously prose.

Anchors and merge keys are powerful and they are how a 40-line file becomes unreadable. If you need them, you already know. If you do not, do not copy them from a snippet you half understand. The converter may accept common YAML and reject a tag it does not implement. The error is on the page. Do not bypass it by sending the file to an online linter that stores configs. Config files contain hostnames, and sometimes they contain tokens someone pasted “just for a minute.”

Converting without uploading

The YAML and JSON tool has two directions. YAML to JSON parses then pretty-prints. JSON to YAML demands valid JSON first, then dumps YAML. Key order can change. Do not use key order as meaning. If your consumer depends on order, it is already fragile.

Do the conversion in the browser if the file might contain a secret. The page does not upload the text. Analytics, if you turn them on, are specified not to include what you pasted. That is a policy. It is still a bad idea to paste a production password into any website, including this one, on a shared computer. Reset the box when you are done. Local processing is not the same as “safe to leave on screen.”

JSON to CSV is a different hop. It wants an array of flat objects. Nested objects become a JSON string in one cell so they are not dropped silently. If you needed columns, flatten first. CSV to JSON uses the header row as keys. It will not guess that a semicolon-separated European export is CSV. The delimiter is a comma.

A small example

This YAML:

name: Ada
active: true
ports:
  - 80
  - 443

is the same information as:

{
  "name": "Ada",
  "active": true,
  "ports": [80, 443]
}

The quotes and the commas are the JSON tax. The indentation is the YAML tax. Pick the tax your editor and your runtime already pay. A microservice that speaks JSON should not grow a YAML parser for one admin screen. A deployment repo that is already YAML should not grow a JSON twin of the same file “for the API” unless something actually fetches it.

JWT, hashes, and the same habit

The habit that matters is not the format. It is not sending the payload to a stranger’s formatter. JWT Decoder on this site shows the header and payload and writes signatureChecked: false. A readable token is not a valid token. Hash Generator will hash text locally, including MD5, which Web Crypto does not offer. MD5 is not a password store. It is a checksum you still see in old docs. Use SHA-256 when you have a choice and you are comparing files you trust the procedure for.

If you are choosing a format for a new public API, choose JSON. Document the fields. Reject unknown types instead of coercing them. YAML can stay in the repo next to the CI file, where a human is the one saving the file and a review can see the diff.

Try the related tools

← More guides · All tools