🔄 Converters

Converting between formats is rarely a pure translation, because each format encodes a different model of the world. Knowing what a conversion discards is what separates a clean migration from a bug you discover weeks later in production.

Lossy, lossless, and the difference

Some conversions here are exact. A number in base 10 becomes the same number in base 16. A length in inches becomes an exactly equivalent length in millimetres, because an inch is defined as 25.4 mm rather than measured. Markdown to HTML has well-defined output.

Others necessarily lose something. YAML to JSON drops comments, anchors, type tags and multi-document files, because JSON cannot express any of them. XML to JSON has to invent conventions for attributes and namespaces, since JSON has neither concept. CSV to JSON has to guess types, because every CSV value is text — which is how the postcode 01234 becomes 1234.

The single-item ambiguity

Watch for this specifically when converting XML or CSV into JSON. A list containing exactly one item can reasonably become either a bare value or a one-element array, and different converters choose differently. Code that assumes an array and receives a string fails only on the one-item case, which is precisely the case that gets missed in testing.

Units, and the ones that are genuinely ambiguous

Most unit factors are fixed by international definition. The dangerous units are the ones that share a name: a US short ton, a UK long ton and a metric tonne differ by up to 12 percent; a troy ounce is about 10 percent heavier than an ordinary ounce; a nautical mile is not a statute mile. And temperature is the one conversion with an offset, so the formula that is correct for a reading is wrong for a difference.