JSON, XML, and YAML to documents: flattening nested data
4 min read · Updated 2026-09-12
JSON, XML, and YAML all describe trees: values inside objects inside arrays, nested as deeply as you like. CSV describes a grid. A PDF describes a page. There is no mechanical translation between a tree and a grid, which means every one of these conversions involves a choice about how to flatten, and it is worth knowing which choice is being made for you.
What the three source formats have in common
JSON, XML, and YAML are different syntaxes for broadly the same data model. JSON is the web's default and the most compact. YAML is the same model with significant whitespace and a friendlier surface, which is why configuration files use it. XML is older, more verbose, and carries extra machinery — attributes, namespaces, schemas — that the other two do not have.
Because the model is shared, converting between them is mostly mechanical, and the interesting conversions are the ones that leave the family: into a spreadsheet, into a document, or into a PDF someone will read.
The flattening problem
An array of flat objects converts to a table perfectly. This is the shape almost everyone actually has, and it is why these conversions work as often as they do:
The trouble starts when values are themselves structures. If a record contains an `address` object, does that become one column holding the whole object, or four columns for street, city, postcode, and country? If a record contains a list of tags, does that become one comma-joined cell, or one column per tag — and if so, how many columns, given different records have different numbers of tags?
There are defensible answers to all of these and no universally correct one. The converter flattens nested keys and arrays into a readable shape and writes that. For an array of flat records, the result is exactly the table you wanted. For a ten-level configuration tree, the result is a readable rendering of the tree, not a meaningful table — because there is no meaningful table to produce.
Choosing a target
| You want | Convert to |
|---|---|
| To analyse the data in a spreadsheet | CSV or XLSX — and prefer XLSX, which keeps cell types |
| To give a non-technical colleague something readable | |
| To include the data in a report you are writing | DOCX, where it lands as an editable table |
| To read it yourself quickly | TXT |
| To move it to another system | Another structured format — JSON to YAML, XML to JSON |
What to expect from each
- To CSV or XLSX: best when the source is an array of records. Check the first rows of the output — a nested field that got joined into a single cell is obvious there and invisible later.
- To PDF: the data is laid out as a readable document. Useful for review, sign-off, and sending to someone who will never open a JSON file. It is not machine-readable output; do not convert to PDF and then expect to get the data back.
- To DOCX: the data arrives as a table you can edit, restyle, and paste into a larger document. This is the right target when the data is going into something a person wrote.
- To TXT: the flattest, most predictable output, and the fastest to scan. No structure survives beyond indentation.
Malformed input fails loudly, on purpose
A JSON file with a trailing comma, an XML file with an unclosed tag, or a YAML file with inconsistent indentation will stop the conversion with a parse error rather than producing a half-converted document.
This is deliberate and it is the right behaviour. A converter that silently skipped the part it could not parse would hand you a document that looks complete and is missing records — which is far worse than an error message, because you would not find out until it mattered.
If a file fails to parse, validate it with a linter for its format first. The error will tell you the line; the fix is almost always mechanical.
When not to convert at all
If the destination is another program, keep the data structured. Converting JSON to PDF so someone can email it, and then having them re-key it, is a common and avoidable loss.
If the data is deeply nested and genuinely hierarchical — a configuration file, an API response with several levels of embedding, a document tree — a table is the wrong shape for it and any flattening will be lossy in the sense that matters: the relationships will be gone. Convert to a readable document if a person needs to read it, and keep the original for anything that needs to use it.