MODL Specification

"

Introduction

MODL is a data serialisation language with the goal of describing objects in as few characters as possible. MODL has particular application in DNS TXT records because:

  • it is character-efficient
  • it is easily minified
  • keys and values do not need to be "quoted" – avoiding DNS storage issues

Until now, developers have rolled their own methods of storing data in DNS TXT records, presenting significant limitations and a barrier to entry for those looking to store data in DNS. MODL aims to standardise data storage in DNS TXT.

Status

MODL was first published on 25th March 2018, we do not anticipate any further changes to the grammar or interpreter rules.

Rules

  1. MODL is case-sensitive
  2. Whitespace means space (0x20) or tab (0x09).
  3. Newline means LF (<0x0A) or CRLF (0x0D0A).
  4. MODL ignores all leading and trailing whitespace.
  5. MODL files must be valid UTF-8 encoded Unicode documents.

Authors

MODL was created by Elliott Brown Content on another site., Alex Dalitz Content on another site. and Tony Walmsley Content on another site..

Machine Diagrams

MODL can be explained using machine diagrams (in the same style as JSON Content on another site.):

Values

The values listed in the machine diagrams above are described precisely below:

Map

A map is known in other languages as a hash table, object, record, struct, dictionary, keyed list, or associative array. A map begins with left parenthesis ( and ends with right parenthesis ), it contains zero or more pairs separated by a semi-colon (;).

run code
copy to clipboard
( a=1; b=2; c=3 )
  • MODL
  • JSON

Array

Arrays in MODL will be familiar to most – beginning with a left square bracket [ and ending with a right square bracket ] containing zero or more values separated by a semi-colon ;. Array items can be of any data type and data types can be mixed.

run code
copy to clipboard
[ 1; 2; 3 ]
  • MODL
  • JSON

Pair

Pairs are the primary building block of MODL and consist of a value assigned to a key. They can be used in a number of ways to aid character efficiency. Orphan pairs (not within a map) are allowed for character efficiency and are converted into a map when parsed.

Standard Pair

A standard pair is a key and a value separated by equals (=):

run code
copy to clipboard
( a=1 )
  • MODL
  • JSON

Map Pair

When assigning a map to a key, we can omit = since the left parenthesis separates the key from the map contents:

run code
copy to clipboard
( a( b=1 ) )
  • MODL
  • JSON

Array Pair

When assigning an array to a key, we can omit = since the left square bracket separates the key from the array contents:

run code
copy to clipboard
( a[ 1; 2 ] )
  • MODL
  • JSON

Orphan Pairs

An orphan pair is one that is expressed outside of a map.

At the top level

Pairs can be expressed outside of a map at the top level and they are automatically considered pairs in the same map:

run code
copy to clipboard
a=1; b=2; c=3
  • MODL
  • JSON
As array values

Pairs can be expressed as values in an array, where they are automatically considered individual maps each with one pair:

run code
copy to clipboard
[ a=1; b=2; c=3 ]
  • MODL
  • JSON

Number

Numbers in MODL are the same as numbers in JSON view RFC Content on another site.

String

Strings in MODL are the same as strings in JSON view RFC Content on another site., with the exception that they can also be unquoted and `graved`.

Boolean

True is represented using true and false is represented using false – in both cases, the same as JSON.

Null

Null is represented using null, the same as JSON.

Type Inference

MODL infers the type of a value, to set a number to a string it can be quoted. For example:

run code
copy to clipboard
( force_number_as_string="1" )
  • MODL
  • JSON

Quoting Values

Values can be quoted using double quotes (") or DNS-friendly graves (`), for example:

run code
copy to clipboard
( force_number_as_string="1"; force_another_number_as_string=`2` )
  • MODL
  • JSON

Escaping

Like JSON, the backslash (\) can be used to escape characters. In addition, the DNS-friendly tilde (~) can also be used as an escape character. For character efficiency, it's usually better to quote values that include more than one reserved character. For example:

run code
copy to clipboard
( include_one_reserved_char = we won :\); include_many_reserved_chars = "this (that [the other]" )
  • MODL
  • JSON

In MODL tilde (~) is equivalent to backslash (\). Backslash can be used to escape tilde and tilde can be used to escape backslash. Tilde can be used to escape tilde. Backslash can be used to escape backslash.

Encoding For DNS

MODL is not limited to ASCII characters Content on another site. but some storage media are (e.g. DNS TXT records). Non-ASCII characters can be expressed in ASCII MODL in two ways:

Hex Values

Any unicode character represented by four hex digits can be used in MODL in the same way as JSON:

run code
copy to clipboard
( symbol=\u03C0 )
  • MODL
  • JSON

A DNS-friendly version is also available using the tilde (~) in place of the back slash (\):

run code
copy to clipboard
( symbol=~u03C0 )
  • MODL
  • JSON

Punycode

For more complex strings, it's more efficient to Punycode Content on another site. the string before storing it in an ASCII system (e.g. DNS), then decode the string before parsing. Any Unicode character can be punycode encoded, providing ASCII support for almost every language on Earth and symbols like emojis.

In the Russian language object below, the name field uses the punycode conversion of пример (English translation: 'Example') and the department uses the punycode conversion of обслуживание клиентов (English: 'Customer Service'):

copy to clipboard
xn--name=;department= -7wotvc6cpbv3bpcc5dyaik8chwph4bd0d1c4a
An example DNS TXT record string using punycode to represent non-ASCII characters.

If decoded before parsing, the resulting MODL object looks like this:

run code
copy to clipboard
name=пример; department=обслуживание клиентов
  • MODL
  • JSON

Reserved Characters

For character efficiency, you should use a quoted or graved string Content further up this document. if a value includes two or more reserved characters, otherwise use an escape character (\ or ~) for a single reserved character. The following characters have special meaning in MODL:

  • Brackets: The left bracket ( indicates the start of a map Content further up this document., the right bracket ) indicates the end.
  • Square Brackets: The left square bracket [ indicates the start of an array Content further up this document., the right square bracket ] indicates the end.
  • Semi-colon ; is used in a map Content further up this document. to separate pairs Content further up this document. and used in an array Content further up this document. to separate items.
  • Grave accents and double quotes (` and " respectively) are used for quoting values Content further up this document..
  • Backslash and tilde (\ and ~ respectively) are escape characters and can be used before any reserved character to escape its reserved use. To use a backlash or tilde in a MODL object, simply use two: \\, ~~, \~ or ~\.
Playground
Reduce | 
Enlarge | 
Full |