Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 39 ยท Parsing, Security and Tooling

Choosing a Format and Converting Between Them

Compare JSON, XML, YAML, TOML, CSV and Markdown by purpose, then learn to convert between them safely - flattening nested data, mapping types, and spotting what each conversion loses.

There is no best data format, only a best fit for a job. This lesson gives you a decision method, a comparison you can reuse, and the mechanics of converting between formats, including the things that get lost on the way. Conversion is where most data-format bugs live: dates turn into strings, nested data gets flattened, comments vanish, and numbers change shape.

Match the format to the job

Format Strengths Weaknesses Typical use
JSON universal, simple, typed basics, fast parsers no comments, no dates, no schema in itself web APIs, config written by tools, data exchange
XML namespaces, attributes, mixed content, schemas, XSLT verbose, complex security surface documents, SOAP, SVG, feeds, office formats
YAML human-friendly, comments, anchors many surprises, large spec CI, Kubernetes, hand-edited config
TOML explicit types, comments, unambiguous awkward for deep nesting application and project config
CSV/TSV spreadsheets, compact tables, streamable flat, untyped, dialect chaos exports, analytics, imports
JSON Lines append-only, streamable not one document logs, event streams, ML datasets
Binary (protobuf, MessagePack) compact, fast not human-readable, tooling needed RPC, storage, high volume
Markdown readable prose, converts to HTML not for structured data documentation, content

Ask these questions in order:

flowchart TD
  A["What is the data?"] --> B{"Prose with structure?"}
  B -- "yes" --> M["Markdown (+ front matter) or XML/HTML for rich documents"]
  B -- "no" --> C{"Flat table?"}
  C -- "yes" --> D["CSV/TSV, or JSON Lines for streams"]
  C -- "no" --> E{"Who edits it?"}
  E -- "humans" --> F{"Deeply nested?"}
  F -- "no" --> G["TOML or YAML"]
  F -- "yes" --> H["YAML (with a linter and schema)"]
  E -- "programs" --> I{"Size or speed critical?"}
  I -- "yes" --> J["binary format"]
  I -- "no" --> K["JSON"]

A starting point, not a law. Ecosystem conventions often decide: use what your tools expect.

Other factors: schema support (JSON Schema, XSD, protobuf), tooling in your team's languages, diffability in version control, security requirements and whether you must read old files forever.

Data models differ

Formats do not describe exactly the same thing. Each conversion maps between data models:

  • JSON, YAML, TOML share the idea of maps, lists and scalars. YAML and TOML add comments (not data) and dates; TOML has no null; YAML has anchors and tags.
  • XML has elements, attributes, text and mixed content, plus namespaces and ordering. There is no native array: repeated elements are the list, and a single element is ambiguous (is it a list of one?).
  • CSV is a list of rows of strings, with no hierarchy and no types.

Converting from a richer model to a poorer one loses information; going the other way must invent structure or types.

Direction What gets lost or invented
YAML to JSON comments, anchors (expanded), non-string keys, dates (become strings or objects)
JSON to TOML null (not allowed), mixed-type root arrays, top-level arrays
JSON to CSV nesting (must be flattened), arrays, types
CSV to JSON types (invented by guessing), empty-versus-missing
JSON to XML array-versus-element ambiguity, attribute-versus-child choice, root element name
XML to JSON attributes versus children, text versus mixed content, ordering

Flatten and unflatten

The most common conversion problem is nested data to a flat table. The usual answer is path keys with dots: {"user": {"name": "Ada"}} becomes the column user.name.

Node.js JSON to CSV with flattened columns and back

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.

The round trip shows the cost: id is now the string "1", admin is "true", note is an empty string rather than null, and the array only came back because unflatten treats numeric path parts such as tags.0 as array indexes, a convention you must document (and an object with real keys 0 and 1 would be misread). A conversion that must round-trip needs a schema describing types (for example a header row of column types, or a JSON Schema).

JSON to XML and the ambiguities

XML needs decisions JSON never asks for. What is the root element's name? Does "id": 1 become an attribute or a child element? How is an array written: repeated elements with the same name, or a wrapper element? Every converter picks a convention, and the choices must be documented.

Node.js A simple JSON-to-XML writer with escaping

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.

Two protections are built in: all text is escaped (Ada & Co becomes Ada & Co) and keys that cannot be element names are rejected rather than producing broken XML. JSON keys may contain spaces or start with digits; XML names may not.

Practical conversion advice

  1. Pick one canonical format internally and convert at the edges.
  2. Parse to plain data, then serialise; do not convert by text substitution.
  3. Define the mapping for types: dates as ISO 8601 strings, big numbers as strings, binary as base64, null as an explicit marker where the target lacks it.
  4. Round-trip test with representative data, including empty values, unicode, newlines, quotes and very large numbers.
  5. Validate after converting against a schema in the target format.
  6. Keep comments out of the data; if they matter, convert once and keep editing the original.
  7. Use maintained tools (jq, yq, xmllint, miller, csvkit, libraries) instead of ad hoc scripts, and see Command-Line Data Tools.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which format is the best fit for a hand-edited application settings file with simple sections, where explicit types matter?

    TOML is designed for human-edited configuration with unambiguous types.
  2. 2. What is lost when converting YAML to JSON?

    JSON has no comments or references, and its keys are strings.
  3. 3. How is nested JSON usually represented in a CSV row?

    Dotted path columns are the common convention; arrays need an index or a join convention.
  4. 4. Why is a JSON array hard to represent in XML?

    Repeated elements represent lists, and a single element is ambiguous. Converters must define the convention.

Summary

  • Choose by the shape of the data, who edits it, size/speed needs and ecosystem conventions.
  • Formats have different data models: converting to a poorer model loses information; converting to a richer one invents it.
  • Flatten nested data with path keys for CSV; expect all values to become strings.
  • XML conversion needs explicit rules for arrays, attributes, nulls and names, plus escaping.
  • Convert at the edges, parse then serialise, and round-trip test.

Next: Command-Line Data Tools