Skip to main content

Data Formats 10

Convert and format JSON, YAML, CSV, XML and more

JSON, YAML, TOML, CSV, XML: the formats that configuration and data arrive in. Converting between them is routine, and each conversion loses something you should know about before you rely on it.

Tools in this category

Every conversion is lossy in one direction

The formats do not describe the same things, so moving between them discards whatever the destination cannot express. YAML and TOML have comments; JSON does not, so converting drops them. CSV is flat; nested JSON has to be flattened or stringified to fit. XML distinguishes attributes from child elements; JSON needs a convention to keep them apart. None of this is a defect in a converter, but it does mean that a converted file is usually a view of your data rather than a replacement for the original.

Types are where the surprises live

JSON has exactly one numeric type and no dates. YAML infers types from unquoted text, which is how a country code becomes a boolean and a version number loses a digit. CSV has no types at all, so a postcode with a leading zero survives only if nothing helpfully converts it to a number. TOML is the strict one, requiring quotes and writing dates as literals. When a value changes shape during a conversion, the format's typing rules are almost always the reason.

Converting to JSON is a good way to read a file

Indentation-based nesting in YAML and implicit nesting from TOML table headers are both easy to get subtly wrong: a key indented one level too far becomes a child rather than a sibling, and the file still parses. Braces and brackets make the structure explicit, so converting a manifest to JSON is often the quickest way to confirm it describes what you intended, even when you have no intention of using the JSON.

What to reach for

The JSON Formatter indents or minifies and validates as it goes. The YAML, TOML, CSV, TSV and XML converters each go both ways, with the options that format needs. The JSON Schema Generator and JSON to TypeScript turn a sample response into a contract or into types. The JSONPath Finder lists every path in a document so you can find the one you need without counting brackets.

Data Formats: frequently asked questions

Which format should I use for configuration?
TOML for flat-to-moderately-nested configuration, because its types are explicit and whitespace carries no meaning. YAML for deeply nested documents such as Kubernetes manifests, where the punctuation of the alternatives becomes unreadable. JSON for anything machines write and read, where comments are unnecessary and unambiguous parsing matters more than editing comfort.
Why did my value change type during conversion?
Almost certainly YAML type inference or a numeric string being read as a number. Unquoted values in YAML are typed by shape, so a version like 1.10 becomes 1.1 and the word no can become false. Quote anything that must stay a string, and check identifiers with leading zeros after any conversion through a format that has no types.

Other categories