Readable Object Description

Readable Object Description (ROD) is a human-readable format for describing general data.

Goals

ROD is designed principally to provide a representation suitable for testing file formats. Consider it a specified format for "snapshots" or "golden files".

• Human-readable. The format is expected to be read by humans. Elements should be unambiguous, and should have exactly one representation.
• Diffable. It should be possible to format a ROD file so that produced diffs are human-readable, with as little noise as possible.
• Comparable. It should be easy to compare two files of the format semantically.
• Machine-friendly. The expected use-case of ROD is to convert data between ROD and another format, for the purpose of testing that format. Despite being human-readable, implementing a decoder and encoder in the target language should be straightforward. The reference implementation should be easily translatable to other languages.

Non-goals

• Human-writable. Files in the format are mainly expected to be generated by a machine. Humans aren't expected to be writing ROD files by hand.
• Data exchange. The format is not JSON 2.0, and should not be used for transmitting data.

Implementations

The go subdirectory provides a reference implementation. Additionally, the luau subdirectory provides an implementation in Luau.

Overview

ROD is similar to JSON, consisting of a number of primitive and composite types.

Type	Example	Description
null	null	The absence of a value.
boolean	true	One of two possible states.
integer	+42	A signed integer.
float	-3.14	A floating-point number.
string	"hello"	A sequence of characters.
blob	| 68 65 6C 6C 6F |	A sequence of bytes.
array	[1, 2, 3]	A sequence of values.
map	("A": 1, 2: 3, true: null)	Maps a primitive value to another value.
struct	{A: 1, B: 2, C: 3}	Maps an identifier to a value.