Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 39 ยท Getting Started

Choosing the Right Format

Compare JSON, XML, YAML, TOML, CSV and Markdown by readability, size, types, comments and tooling, and learn a simple checklist for picking the right one.

There is no best data format, only the best one for a job. A web API, a Kubernetes manifest, a spreadsheet export and a README all hold "data", yet each usually uses a different format. This lesson gives you a short list of criteria and then compares the formats against them.

Questions to ask first

  1. Who reads it? People editing by hand favor YAML or TOML. Machines talking to machines favor JSON.
  2. Does it need comments? Plain JSON has none; YAML, TOML and XML do.
  3. How deeply nested is the data? CSV is flat. TOML gets awkward when deep. JSON, XML and YAML handle trees.
  4. Is it a document or a record? Text with inline markup ("this word is bold") is a document: XML or Markdown. A bundle of fields is a record: JSON, YAML.
  5. How large is it, and is it streamed? Huge tables suit CSV or JSON Lines; they can be processed one row at a time.
  6. What does the other side already speak? Browsers speak JSON; legacy enterprise systems often speak XML.

Comparison table

JSON XML YAML TOML CSV Markdown
Comments No Yes Yes Yes No Yes (HTML)
Nesting Yes Yes Yes Limited No Headings only
Native types string, number, boolean, null, array, object Everything is text Many, inferred Many, incl. dates Everything is text Text
Human editing OK Verbose Good, but fragile Good Good in a spreadsheet Excellent
Schema language JSON Schema XSD, DTD, RELAX NG JSON Schema (via JSON) Few Few (CSV Schema) None
Query language JSONPath, jq XPath, XQuery Via JSON tools None SQL import None

The same decision in practice

Pick by job

Web API JSON
App config YAML or TOML
Rich documents XML or Markdown
Tables CSV

Start from who reads it and what it must hold.

1 / 2

Measuring size

Size matters on slow networks and for huge files. The code below writes one array of records in JSON, XML and CSV and counts the bytes. The XML and CSV writers are simple stand-ins.

Node.js Size of the same data in three formats

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

CSV wins because names are written once, in the header. XML pays for every closing tag. Gzip compression shrinks all three a lot, because repeated names compress well, so the gap on a real network is smaller than the raw numbers suggest.

Converting between formats

Because all of them describe trees or tables of simple values, data usually moves between formats easily. Conversions lose information when the target cannot express something: JSON to CSV loses nesting, XML to JSON loses attributes versus elements, YAML to JSON loses comments and anchors.

Node.js Flattening nested JSON for CSV

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Which format is a natural choice for a hand-edited config file that needs comments?

    YAML and TOML allow comments and are comfortable to edit by hand. Plain JSON has no comments.
  2. 2. Why is CSV usually smaller than JSON or XML for a large table?

    JSON and XML repeat the field names on every record; CSV writes them once.
  3. 3. What is lost when converting nested JSON into CSV?

    CSV is a flat table, so nested objects need flattened column names or separate tables.

Summary

  • Choose by audience, comments, nesting, document-versus-record and what the other side speaks.
  • JSON for APIs, YAML/TOML for config, XML/Markdown for documents, CSV for flat tables.
  • Conversions can lose information such as nesting, comments or attributes.
  • Compression narrows size gaps between formats.

Next: Text encoding and syntax basics