LocalFirstTools.com — data tools that never leave your device
No upload — everything runs on your device

JSON vs YAML vs CSV: which format for which job?

Last updated

The short version: JSON for APIs and anything programs exchange, YAML for configuration humans edit, CSV for flat tables going to or from spreadsheets. All three describe data, but they make opposite trade-offs — and because their data models overlap, you can usually convert between them: JSON ↔ YAML and JSON ↔ CSV both run in your browser.

The same record in all three

JSON: {"name": "Ada", "role": "admin", "active": true}

YAML: name: Ada
      role: admin
      active: true

CSV:  name,role,active
      Ada,admin,true

What actually differs

  • Data model. JSON (RFC 8259) and YAML share objects, arrays, strings, numbers, booleans and null — YAML adds anchors, tags and multi-document files. CSV (RFC 4180) has exactly one shape: rows of untyped text fields. In CSV, true and 01234 are just characters.
  • Comments. YAML has them (#); JSON and CSV do not. This alone explains YAML's dominance in config files — humans annotate configs.
  • Ambiguity. JSON has essentially none. YAML has famous foot-guns: unquoted no parses as a boolean (the “Norway problem”, country code NO), leading zeros turn into numbers. CSV's ambiguity is dialects: delimiters, quoting and encodings vary by exporting locale — European Excel emits semicolons.
  • Whitespace. Meaningless in JSON, structural in YAML (indentation is syntax), and significant inside CSV fields.

YAML's power features, and the price

YAML earns its config-file role with features JSON refuses to have. Anchors deduplicate repeated blocks — one definition, reused by reference:

defaults: &defaults
  retries: 3
  timeout: 30

production:
  <<: *defaults        # merges retries and timeout
  timeout: 60          # then overrides one key

Convert that YAML → JSON and the references vanish into expanded copies — which is also the fastest way to see what your anchors actually produce. The price of YAML's friendliness is implicit typing. This innocent country list:

countries: [DE, FR, NO]     # parses as [DE, FR, false] in YAML 1.1 parsers
version: 1.20               # the number 1.2 — trailing zero gone
zip: 01234                  # 1234 in YAML 1.2 — octal 668 in 1.1 parsers

NO is Norway to you and a boolean to a YAML 1.1 parser — the famous “Norway problem”. YAML 1.2 fixed most of this on paper, but widely deployed parsers (libyaml, PyYAML) still follow 1.1 rules. The defensive habit: quote every scalar that must stay a string.

CSV's dialect problem

RFC 4180 nails down commas, CRLF line endings and double-quote escaping ("" inside a quoted field) — but real-world CSV predates the RFC by decades and Excel is its own standard. Concretely: a German or Dutch Excel exports semicolon-separated files (because the comma is the decimal separator there); Excel eats leading zeros unless a column is typed as text; and it historically needed a UTF-8 BOM at the start of the file to render accents correctly. If an “invalid” CSV crosses your desk, check the delimiter and the encoding before blaming the data — then convert it with CSV → JSON once it is comma-separated.

Choose by job, not by taste

Use JSON when programs talk to programs: API payloads, message queues, storage formats, log lines. Every language parses it natively and fast, and its strictness means a document either parses or fails loudly — check any document with the JSON Formatter & Validator.

Use YAML when humans maintain the file: Kubernetes manifests, CI workflows, docker-compose. You get comments, less punctuation noise, and multi-line strings — at the price of the typing foot-guns above. When a YAML config behaves strangely, converting it YAML → JSON shows you what the parser actually understood.

Use CSV when the data is a flat table and a spreadsheet is on either end of the pipeline: exports for analysts, imports from Excel, bulk data loads. It is the only one of the three that non-programmers open directly. Convert a spreadsheet export into objects with CSV → JSON when it needs to enter code.

Converting between them

JSON ↔ YAML is lossless for data (comments and anchors are lost in the YAML → JSON direction, since JSON cannot express them). JSON ↔ CSV is only faithful when the JSON is an array of flat objects with consistent keys — exactly the shape of a table. Round-tripping through CSV strips types: numbers and booleans come back as strings, by design, because guessing corrupts values like postal code 01234.

Do it now — locally

Convert JSON to YAML and back for configs and manifests. Nothing is uploaded.

Open the JSON ↔ YAML

Frequently asked questions

Is every JSON document valid YAML?

Yes. YAML 1.2's data model is a superset of JSON's, so valid JSON parses as YAML. The reverse is false: anchors, comments and multi-line scalars have no JSON form.

Can CSV represent nested data?

Not directly — CSV is rows and columns. Nested structures must be flattened (dotted column names like user.name) or serialized into a cell, both of which are workarounds rather than features. If your data nests, CSV is the wrong format.

Why did my YAML value change type after converting?

YAML guesses types for unquoted scalars: no becomes false, 007 becomes 7, 3:20 can become a sexagesimal number in YAML 1.1 parsers. Quote anything that must stay a string. Converting to JSON is a quick audit for these surprises.

Which format is fastest to parse?

JSON, by a wide margin — its grammar is tiny and parsers are heavily optimized native code in every runtime. YAML parsers are orders of magnitude slower; CSV sits between, depending on quoting complexity.

Should an API ever speak YAML?

Rarely. JSON parses faster, has no implicit-typing ambiguity, and every HTTP client handles it natively. YAML at API boundaries mostly appears where the payload is itself configuration (Kubernetes' API accepts both). Default to JSON on the wire, YAML in the editor.

Why does Excel show my CSV in one column?

Delimiter mismatch: your file is comma-separated but Excel's locale expects semicolons (or vice versa). Use Excel's import wizard to set the delimiter explicitly, or re-export the file with the delimiter your locale expects.