Mendoza - The totally non-human readable diff format for structured JSON documents

Written by Magnus Holm

When we started work on the recently released feature Review Changes, we needed a way to keep a significant part of the edit history of a document in the browser memory to be able to respond quickly to different user interface states. As the user picked various document versions to compare we wanted to be able to quickly reconstruct a specific section of the history of a document.

For text diffs, we use the diff-match-patch format, and we just assumed someone would have implemented a similarly efficient and compact diff format for JSON documents, but no such luck. If we wanted a general JSON diff format that was super compact and fast to apply, we would have to invent it ourselves. And thus, Mendoza, the totally non-human readable diff format for structured JSON documents, was born.

Mendoza is:

• Lightweight JSON format
• A flexible format that can accommodate more advanced encodings in the future
• As a Go library for encoding and decoding
• A JavaScript library for decoding
• Efficient handling of the renaming of fields
• Efficient handling of reordering of arrays
• Not designed to be human-readable

Mendoza differs (hah!) from normal diffs as they are:

• Made for humans to read and understand and based on simple operations (like keep, insert, and delete text)
• Possible to apply even if the source has changed a bit by including some of the contexts around every part that has changed
• Designed for text, and not structured documents

Now, this is great when you are collaborating with humans on code development and use something like git to track your changes. What it isn’t great for, however, is expressing differences between structured documents (such as JSON) in a compact manner that can be efficiently transferred over the network and parsed in JavaScript inside of browsers.

Most diffs aren't meant for machines

Most diff formats are made to be human-readable. Take these two documents, where a key and the array have some changes between them: