Other Formats

JSON is rarely the only choice. Configuration files are often YAML or TOML, data feeds are sometimes XML or CSV, services between companies use Protocol Buffers, and editors accept "JSON with comments". Each format fixes something JSON lacks and gives something up for it. This chapter does not argue from reputation: it feeds the same awkward inputs to real parsers and reports what came out, converts one document through each format and counts what was lost, and measures size and speed on 100,000 records. The most useful result is a list of places where a format quietly changes your data.

At a Glance

YAML: The Friendly Format with Sharp Edges

YAML uses indentation instead of braces, allows comments and is easy to read. The catch is that a YAML value with no quotes is guessed: the loader decides whether NO is a string, a boolean or something else. The guess depends on which version of the YAML specification the library follows (1.1 or 1.2) and on the library. I wrote one small YAML file full of unquoted values and loaded it with four loaders. A selection:

The first row is the famous Norway problem: a list of country codes containing NO turns Norway into false in a YAML 1.1 loader (PyYAML, and Node's yaml when told to use 1.1). The other rows are the same disease: 1.10 becomes 1.1 in every loader I ran, so a version number must be quoted; 01234 is a zip code in one loader and the number 668 in another; 22:22 is a time of day or the integer 1342. I did not find a case where quoting a value ("NO", "1.10") was read as anything but a string. When PyYAML writes a document it does the quoting for you: yaml.safe_dump wrote the string "1.10" as '1.10' and the string "2026-10-12" as '2026-10-12', and both came back as strings.

"YAML is a superset of JSON": Only Sometimes

The YAML 1.2 specification is designed so that a JSON document is also a YAML document. I fed JSON texts to the same loaders to see how true that is in practice:

A YAML 1.2 loader reads ordinary JSON, but PyYAML (a 1.1 implementation) changed the meaning of 1e3 and broke a valid JSON number into a string, and mangled an emoji. So "just load my JSON with a YAML parser" is only safe with a loader that targets 1.2, and even then the duplicate-key behaviour differs from a JSON parser. (The Node JSON.parse line for 1E400 printed null because I displayed it through JSON.stringify, which prints infinity as null.) One more difference from JSON: a plain value containing a colon and a space, colon_str: a: b, is an error in the loaders I tried (PyYAML: "mapping values are not allowed here"; Node yaml: "Nested mappings are not allowed in compact mappings"), so it must be quoted.

TOML: Configuration Without Guessing

TOML is aimed at configuration files. Values have explicit types (a quoted string is a string, 2026-10-12 is a date) so there is much less guessing. I parsed a small TOML file in Python and Node:

• Types: when came back as a Python datetime with a UTC offset, day as a date, hex as 255 and big as 1000. In Node, smol-toml returned TomlDate objects (a subclass of Date) for both.
• Dates are not JSON: json.dumps on the parsed data raised "Object of type datetime is not JSON serializable". The usual fix, default=str, wrote "2026-10-12 08:30:00+00:00" with a space instead of a T, which is not the ISO form most JSON consumers expect. Convert dates with .isoformat() deliberately.
• No null: n = null is an error in both libraries, and tomli_w refused to write a Python None ("Object of type 'NoneType' is not TOML serializable"). A JSON document with null values cannot go to TOML without deciding what an absent value means.
• Mistakes are caught: a duplicate key (a = 1 then a = 2) and redefining a as a table both raised TOMLDecodeError.
• nan is allowed: x = nan parsed to a NaN float in Python, so a TOML file can contain a value JSON cannot represent.

JSON5 and JSONC: JSON You Can Comment

JSON5 is a superset of JSON that allows comments, trailing commas, single-quoted and unquoted keys, hex numbers, +1, .5, Infinity and NaN. JSONC ("JSON with Comments") is just JSON plus comments and, depending on the tool, trailing commas. I ran thirteen inputs through JSON.parse, JSON5 2.2.3 and Microsoft's jsonc-parser 3.3.1:

The Python json5 package agreed on the cases I tried (comments, trailing comma, unquoted key, Infinity). Two cautions. Comments do not survive: parsing a commented file and writing it back with JSON5.stringify produced a file with the comment gone, and with unquoted keys and single quotes ({ port: 8080, tags: [ 'a', ], }), which is not valid JSON. And a JSON5 or JSONC file is not JSON: JSON.parse, jq and most servers reject it, so strip or convert it before handing it to anything that expects JSON. (I did not test which tools or editors accept comments in which file names; check the documentation of the tool that reads your file.)

XML: Everything Is Text

XML has attributes, mixed content, namespaces and schemas, and it is still the format of many long-lived interfaces. For data, its limit is that there are no number, boolean or list types: everything is text, and a list is only "an element that repeats". Converting a document to XML and back with xmltodict lost types and one list:

That is 6 differences in a 9-field document. The Node library fast-xml-parser showed the same list ambiguity (two <s> elements gave an array, one gave a plain string) and, by default, turned the text 1.10 into the number 1.1 and 01234 into 1234, the YAML problem again. A node with both an attribute and text came out as {"@id": "7", "#text": "hi"} in xmltodict; the names @id and #text are that library's convention, not a standard. Any JSON-to-XML mapping is a set of choices, so two tools will give two different answers.

CSV: Flat and Untyped

CSV is a table of text. It is the right answer for flat data that goes to a spreadsheet. I wrote one record with awkward values using Python's csv module and read it back:

The module handled commas, quotes and embedded newlines correctly by quoting, and kept the leading zero, because it never converts anything. The damage is in types, nulls and nesting: you must write the schema yourself. In my size test below the nested tags list went into one cell as compact JSON, and a reader had to convert each column back. (What a spreadsheet does to 01234, long numbers or dates is a separate problem and I did not test it.)

Protocol Buffers: A Schema and Bytes

Protocol Buffers ("protobuf") describes messages in a .proto schema file and encodes them as compact binary; the schema is needed to read the bytes. (Protobuf in a real service is the subject of the course gRPC.) I used this schema:

For the first record, the JSON line is 100 bytes and the protobuf message is 52 bytes. Three things I observed that do not show in a size table:

• Default values vanish. The first record has id 0. In proto3 a zero is the default and is not stored: it is absent from the bytes, and the library's own JSON conversion (MessageToJson) left "id" out entirely. A reader cannot tell "zero" from "not provided".
• int64 is a string in protobuf's JSON mapping. MessageToJson wrote the id 2⁵³+1 as "9007199254740993" (a string), so JavaScript does not lose the digits (Chapter 1) but your JSON schema must expect a string.
• The bytes are unreadable without the schema, and you must keep schema versions in step between sender and receiver. I did not test schema evolution.

Round Trip: One Document Through Each Format

I took one 9-field configuration document (including a string "1.10", a boolean, a number, a one-item list, a nested object, a list of objects and a null), wrote it with each format's own library, read it back and compared it with the original:

The lesson is the same in each row: a format round-trips what it can represent. If your data has null, TOML cannot hold it; if it has numbers and lists, XML cannot tell you which is which unless something else (a schema) does.

Size and Speed on 100,000 Records

The first 100,000 records of the Chapter 9 data set (about 10.7 MB as JSON) were written and read back in each format, with each result checked against the original (the same records came back for every row except plain XML, where all values are strings). Single run, one machine:

What the numbers say. YAML was about 230 times slower to read than JSON in the pure-Python loader and about 115 times slower with libyaml, for almost the same number of bytes: fine for a config file, wrong for a data feed. After gzip, every format landed between 1.68 MB (CSV) and 2.00 MB (XML), within about 11% of JSON's 1.88 MB, so size is rarely a reason to leave JSON if the transfer is compressed. CSV and Protobuf are smaller raw because they do not repeat the field names on every record. The speed ranking is partly a statement about these libraries (the Python JSON parser is written in C; TOML's is pure Python), not only the formats, and the CSV and Protobuf rows include my own conversion code. The XML "Read" column mixes two different jobs, as labelled.

Choosing and When JSON Is the Wrong Choice

JSON is the wrong choice when you need comments or a human-edited file with no ceremony, when data is naturally a flat table, when you need typed binary data at high volume, or when the other end only speaks something else. It is not the wrong choice just because it is plain: after gzip it was within about 11% of the others on size, and it was the fastest to read in these tests.

Exercises