Litl V1

"Little term language"

Self-describing, human readable encoding format for structured data.

Litl is a dialect of JSON, more precisely it is

• with conventions for
  • encoding binary data (Base58)
  • tagging binary data
• with an optional canonical encoding
• with an optional streaming compression algorithm (lil)

Semantics & Encoding

Litl shares the following types of values with JSON:

• true, false and null
• numbers (floats): 42, 2.8299e-10
• strings: "Hello", "👾"
• arrays: ["a","b","c",5]
• objects: {"a":1,"b":2,"c":"d"}

These ubsequently will be referred to as "JSON values"

To that, it adds only two concepts:

• raw binary data: "h3znn4pjays7u46h"
• tagged binary data: "hash_hbk5tfu4p3jncen"

Raw binary data

Raw binary data MUST be encoded as z-base32 in a JSON string, with the prefix "h".

All strings of this format (prefix + valid Base58) MUST be considered binary data.

Since raw binary data is encoded as a JSON string, it can be used as a key in dictionaries and MUST be encoded in the same way strings are encoded according to the JCS.

Tagged binary data

Binary data in Litl can be tagged to annotate it with additional type information. This can be used to represent more precise types, newtype-style wrapping or to discriminate between variants of enums.

Tags are strings consisting of arbitrary UTF-8 characters, but MUST NOT contain underscores "_".

Multi-word tags SHOULD be written in camelCase.

Raw binary data MUST be tagged by prefixing the tag to the raw binary string representation:

tag_hgrodomjqb5bcse

Tagged binary data can be tagged with additional tags. Additional tags MUST be specified by prefixing each tag, separating tags by underscores:

outerTag_innerTag_z9jr402fnnsldkn

All strings of these formats (underscore-separated tags + _h prefix + valid z-bae32) MUST be considered tagged binary data.

Since tagged binary data is encoded as a JSON string, it can be used as a key in dictionaries.

Canonical value encoding

To conform to canonical Litl encoding, values MUST be encoded according to the JSON Canonicalization Scheme ("JCS", RFC 8785), which defines a canonical encoding for numbers, strings and deterministic ordering of key-value pairs in objects.

Canoncial encoding for raw & tagged binary data

To conform to canonical Litl encoding, raw and tagged binary Data MUST be encoded in the same way strings are encoded according to the JCS.