# Litl V1


"**Li**ttle **t**erm **l**anguage"

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.