Data Converters

Every data format encodes a slightly different model of the world, so converting between them is rarely lossless. Knowing what gets dropped is the difference between a clean migration and a bug you find weeks later.

What each conversion costs you

JSON and CSV disagree about shape. CSV is flat and untyped; JSON is nested and typed. Converting JSON to CSV forces nested objects to be flattened into dotted column names, and arrays have no natural representation at all. Coming back the other way, every CSV value is text, so a converter has to guess types — which is what turns the postcode 01234 into 1234 and a long order number into scientific notation.

YAML and JSON are closer: YAML 1.2 is a superset of JSON, so any JSON file is already valid YAML. Going from YAML to JSON discards comments, anchors and aliases, type tags and multi-document files, because JSON cannot express any of them.

XML to JSON is the least mechanical. XML distinguishes attributes from child elements and carries namespaces; JSON has neither concept, so converters adopt conventions such as prefixing attributes with @.

Markdown to HTML and the Number Base Converter are the two clean conversions here, with well-defined output.

The single-item array trap

Watch for this when converting XML or CSV to JSON. A list containing exactly one item is ambiguous — it can reasonably become either a bare value or a one-element array. Code that assumes an array and receives a string breaks only on the single-item case, which is exactly the case that slips through testing.