RON
Readable Object Notation

RON (Readable Object Notation) is a human-readable JSON notation developed under the StarFederation nonprofit. It is unrelated to Rusty Object Notation.

RON represents null, true, false, numbers, strings, lists, maps, and tagged elements. Null, booleans, numbers, strings, lists, and maps correspond directly to JSON values. Tagged elements are encoded as maps.

Strings can often be written without quotes, map keys and values are separated by whitespace rather than colons, and a document can be laid out one member per line. Tags group a map's boolean members between < and >.

Tagged elements give applications a way to represent additional kinds of values without leaving the JSON data model.

RON can be losslessly roundtripped with JSON.

A RON parser reads text and produces values. It does not execute the document or look up the names written in it.

RON source is UTF-8 text. A document contains one value, which can be a scalar, a list, or a map. The outer braces of a map may be omitted, allowing the document to read as a series of keys and values.

name Ada Lovelace
active true
scores [3 5 8]
address {
  city London
  country UK
}
; TODO: add phone number

<active>
address {city London
         country UK}
name Ada Lovelace
scores [3 5 8]
; TODO: add phone number

{
  "$comment": ":: TODO: add phone number",
  "name": "Ada Lovelace",
  "active": true,
  "scores": [
    3,
    5,
    8
  ],
  "address": {
    "city": "London",
    "country": "UK"
  }
}

In this document, name is a key and Ada Lovelace is its string value. The words after the key belong to the value on that line. To write a string containing spaces as the entire document, enclose the string in quotes. An empty document represents an empty map.

Lists and braced maps have two layout modes. If the opening [ is alone on its line, each item line holds one value. If the first item follows [ on the same line, whitespace separates items throughout the list, including on following lines.

Indentation makes nested values easier to read, but does not introduce or close a container. Brackets and braces must still match. A closing bracket may follow the last value on its line, and several closing brackets may appear together.

Lines end with a newline or a carriage return followed by a newline. In these syntax rules, whitespace means spaces, tabs, and line endings. Blank lines are allowed between members and items. A trailing comma may appear at the end of a member or item line, but commas do not separate items in compact notation.

null represents an explicit empty value. A map member whose value is null is still present in the map. true and false are the two boolean values. These spellings are case-sensitive. Quoting one of them produces a string instead.

[null true false "null" "true" "false"]

[null true false "null" "true" "false"]

[
  null,
  true,
  false,
  "null",
  "true",
  "false"
]

Numbers use decimal notation, with the ASCII digits 0 through 9. An integer consists of an optional minus sign followed by digits. Its first digit is nonzero unless the integer is zero itself. A decimal point followed by one or more digits adds a fractional part. An exponent begins with e or E, followed by an optional sign and one or more digits. A decimal point or exponent makes the literal a floating-point number, even when its value is a whole number.

[0 42 -17 1.0 0.125 -2.5 1e3 6.02e23 1E-3]

[0 42 -17 1.0 0.125 -2.5 1000.0 6.02e+23 0.001]

[
  0,
  42,
  -17,
  1.0,
  0.125,
  -2.5,
  1e3,
  6.02e23,
  1E-3
]

Strings contain Unicode text encoded as UTF-8. They can contain spaces, line breaks, and embedded null characters, but are not containers for arbitrary invalid UTF-8 bytes. RON has several string spellings, all of which produce the same kind of value.

A list is an ordered sequence of values enclosed in square brackets. Its elements may have different types, and lists and maps may be nested within it. The empty list is written [].

[1 true null text {name Ada} [2 3]]

[1
 true
 null
 text
 {name Ada}
 [2 3]]

[
  1,
  true,
  null,
  "text",
  {
    "name": "Ada"
  },
  [
    2,
    3
  ]
]

When [ is alone on its line, each item line is one value, so the spaces in these names are part of each string:

[
  Ada lovelace
  Grace Hopper
]

[
  Ada lovelace
  Grace Hopper]

[
  "Ada lovelace",
  "Grace Hopper"
]

An item line on which a word begins with [, {, or < holds containers, and its words are separate items, as in compact notation. A string with a word that begins with < is therefore quoted, while < within a word stays bare:

[
  "a <b"
  "x <>"
  "y < z"
  a<b
  a >b
  "<c"
]

[
  "a <b"
  "x <>"
  "y < z"
  a<b
  a >b
  "<c"]

[
  "a <b",
  "x <>",
  "y < z",
  "a<b",
  "a >b",
  "<c"
]

When an item follows [ on the opening line, every line uses whitespace to separate items. This allows a packed list to wrap across lines:

[item00 item01 item02
 item03 item04]

[item00 item01 item02 item03 item04]

[
  "item00",
  "item01",
  "item02",
  "item03",
  "item04"
]

Each nested list is one item of the outer list; its brackets keep its own values together. The formatter leaves a compact nested list on one line when it fits, and places several such items on each outer line. If the outer list exceeds 100 columns, it balances the number of items across lines, wrapping earlier if needed to respect the width target.

Here the outer list has 24 two-number lists. Its canonical form uses five lines: five nested lists on each of the first four lines, then four on the last. The line breaks do not change the 24 items or their order:

matrix [
  [0 1]
  [1 2]
  [2 3]
  [3 4]
  [4 5]
  [5 6]
  [6 7]
  [7 8]
  [8 9]
  [9 10]
  [10 11]
  [11 12]
  [12 13]
  [13 14]
  [14 15]
  [15 16]
  [16 17]
  [17 18]
  [18 19]
  [19 20]
  [20 21]
  [21 22]
  [22 23]
  [23 24]
]

matrix [[0 1] [1 2] [2 3] [3 4] [4 5]
        [5 6] [6 7] [7 8] [8 9] [9 10]
        [10 11] [11 12] [12 13] [13 14] [14 15]
        [15 16] [16 17] [17 18] [18 19] [19 20]
        [20 21] [21 22] [22 23] [23 24]]

{
  "matrix": [
    [
      0,
      1
    ],
    [
      1,
      2
    ],
    [
      2,
      3
    ],
    [
      3,
      4
    ],
    [
      4,
      5
    ],
    [
      5,
      6
    ],
    [
      6,
      7
    ],
    [
      7,
      8
    ],
    [
      8,
      9
    ],
    [
      9,
      10
    ],
    [
      10,
      11
    ],
    [
      11,
      12
    ],
    [
      12,
      13
    ],
    [
      13,
      14
    ],
    [
      14,
      15
    ],
    [
      15,
      16
    ],
    [
      16,
      17
    ],
    [
      17,
      18
    ],
    [
      18,
      19
    ],
    [
      19,
      20
    ],
    [
      20,
      21
    ],
    [
      21,
      22
    ],
    [
      22,
      23
    ],
    [
      23,
      24
    ]
  ]
}

A root list of maps can place its first map immediately after [. Each subsequent map aligns beneath it, and each map keeps one key/value pair per line:

[
  {args [0 0]
   output 0}
  {args [1 2]
   output 3}
  {args [-4 10]
   output 6}
]

[{args [0 0]
  output 0}
 {args [1 2]
  output 3}
 {args [-4 10]
  output 6}]

[
  {
    "args": [
      0,
      0
    ],
    "output": 0
  },
  {
    "args": [
      1,
      2
    ],
    "output": 3
  },
  {
    "args": [
      -4,
      10
    ],
    "output": 6
  }
]

For eleven similarly sized items, this produces rows of four, four, and three:

[item00_long item01_long item02_long item03_long item04_long item05_long item06_long item07_long item08_long item09_long item10_long]

[item00_long item01_long item02_long item03_long
 item04_long item05_long item06_long item07_long
 item08_long item09_long item10_long]

[
  "item00_long",
  "item01_long",
  "item02_long",
  "item03_long",
  "item04_long",
  "item05_long",
  "item06_long",
  "item07_long",
  "item08_long",
  "item09_long",
  "item10_long"
]

A map, called an object in JSON, contains string keys paired with values. Any value may appear after a key, including null, another map, or a list. An empty map is written {}.

Compact maps alternate keys and values, separated by whitespace. Each ordinary member has both a key and a value. A tag group supplies boolean members using the shorthand described below. There is no colon between a key and its value.

Canonical nonempty nested maps put the first key/value pair immediately after { and align each following pair beneath it. Each pair occupies its own line, including in maps with one member. A comment that must precede the first item puts the opening brace on its own line. The empty map remains {}:

single {x 1}
multiple {x 1 y 2}
empty {}

empty {}
multiple {x 1
          y 2}
single {x 1}

{
  "single": {
    "x": 1
  },
  "multiple": {
    "x": 1,
    "y": 2
  },
  "empty": {}
}

{name Ada age 36 active true}

<active>
age 36
name Ada

{
  "name": "Ada",
  "age": 36,
  "active": true
}

A map with { alone on its opening line has one ordinary member per line and may also contain tag groups. Each ordinary member begins with its key, followed by its value. The first member may follow the opening brace on the same line, and the last value may be followed immediately by the closing brace.

{
  name Ada Lovelace
 age 36
 active true}

<active>
age 36
name Ada Lovelace

{
  "name": "Ada Lovelace",
  "age": 36,
  "active": true
}

When the first member follows { on the opening line, the map is packed: each line contains whitespace-separated key/value pairs and optional tag groups. A packed map can wrap between complete pairs. Values containing spaces need quotes.

settings {
  <active !admin>
  field00 value00
  field01 value01
  field02 value02
  field03 value03
  field04 value04
  field05 value05
  field06 value06
  field07 value07
  field08 value08
  field09 value09
  field10 value10
  field11 value11
  field12 value12
  field13 value13
  field14 value14
  field15 value15
  field16 value16
  field17 value17
  field18 value18
  field19 value19
}

settings {<active !admin>
          field00 value00
          field01 value01
          field02 value02
          field03 value03
          field04 value04
          field05 value05
          field06 value06
          field07 value07
          field08 value08
          field09 value09
          field10 value10
          field11 value11
          field12 value12
          field13 value13
          field14 value14
          field15 value15
          field16 value16
          field17 value17
          field18 value18
          field19 value19}

{
  "settings": {
    "active": true,
    "admin": false,
    "field00": "value00",
    "field01": "value01",
    "field02": "value02",
    "field03": "value03",
    "field04": "value04",
    "field05": "value05",
    "field06": "value06",
    "field07": "value07",
    "field08": "value08",
    "field09": "value09",
    "field10": "value10",
    "field11": "value11",
    "field12": "value12",
    "field13": "value13",
    "field14": "value14",
    "field15": "value15",
    "field16": "value16",
    "field17": "value17",
    "field18": "value18",
    "field19": "value19"
  }
}

A tag group also counts as content on the opening line. Its position selects how the ordinary member lines are read. With { alone on the opening line, the whole bare value Ada Lovelace PhD belongs to name:

settings {
  <active>
  name Ada Lovelace PhD
}

settings {<active>
          name "Ada Lovelace PhD"}

{
  "settings": {
    "active": true,
    "name": "Ada Lovelace PhD"
  }
}

Moving the tag group after { selects packed mode. The same following line now contains two pairs: name is Ada, and Lovelace is PhD:

settings {<active>
  name Ada Lovelace PhD
}

settings {<active>
          Lovelace PhD
          name Ada}

{
  "settings": {
    "active": true,
    "name": "Ada",
    "Lovelace": "PhD"
  }
}

To keep Ada Lovelace PhD as one value in packed mode, write it as "Ada Lovelace PhD". Canonical formatting chooses a layout from the decoded map rather than the input layout, while preserving the decoded values.

A map can also pack a compact nested value alongside its other members:

data {
  count 3
  values [1 2 3]
  name Ada
}

data {count 3
      name Ada
      values [1 2 3]}

{
  "data": {
    "count": 3,
    "values": [
      1,
      2,
      3
    ],
    "name": "Ada"
  }
}

In canonical output, every ordinary key/value pair has its own line, in sorted key order. The first item follows the opening brace, and subsequent items align beneath it. A tag group has its own line before ordinary members:

record {
  field00 value00
  field01 value01
  field02 value02
  field03 value03
  field04 value04
  field05 value05
  field06 value06
  field07 value07
  field08 value08
  field09 value09
  field10 value10
}

record {field00 value00
        field01 value01
        field02 value02
        field03 value03
        field04 value04
        field05 value05
        field06 value06
        field07 value07
        field08 value08
        field09 value09
        field10 value10}

{
  "record": {
    "field00": "value00",
    "field01": "value01",
    "field02": "value02",
    "field03": "value03",
    "field04": "value04",
    "field05": "value05",
    "field06": "value06",
    "field07": "value07",
    "field08": "value08",
    "field09": "value09",
    "field10": "value10"
  }
}

This also applies when all the ordinary members would fit beside the tags:

user {<active> age 36 name Ada}

user {<active>
      age 36
      name Ada}

{
  "user": {
    "active": true,
    "age": 36,
    "name": "Ada"
  }
}

This is the same map as the following compact form:

{name "Ada Lovelace" age 36 active true}

<active>
age 36
name Ada Lovelace

{
  "name": "Ada Lovelace",
  "age": 36,
  "active": true
}

Keys are strings, so punctuation and spaces may be part of a key when it is quoted. The empty string is also a valid key.

{"full name" Ada "a:b" 1 "a,b" 2 "" empty}

"" empty
"a,b" 2
a:b 1
"full name" Ada

{
  "full name": "Ada",
  "a:b": 1,
  "a,b": 2,
  "": "empty"
}

Keys are always read as strings. Number, boolean, and null spellings have no special meaning in key position.

{null 456 true omg 1 one ^name text}

1 one
^name text
null 456
true omg

{
  "null": 456,
  "true": "omg",
  "1": "one",
  "^name": "text"
}

Bare keys follow different token rules from bare values. A bare key runs to the whitespace before its value. It cannot contain commas or double quotes, or begin with [, ], {, }, or <. Brackets after the first character are part of the key. Parentheses do not introduce a RON container and may begin a bare key. Colons are ordinary characters in bare keys.

Each of these keys starts with a comma, double quote, bracket, brace, or tag-group opener and must be quoted. The quote is part of the second key's name; JSON-style escaping is accepted in the input, and canonical formatting chooses a fence:

",name" 1
"\"name" 2
"[name" 3
"]name" 4
"{name" 5
"}name" 6
"<name" 7

""\"name"" 2
",name" 1
"<name" 7
"[name" 3
"]name" 4
"{name" 5
"}name" 6

{
  ",name": 1,
  "\"name": 2,
  "[name": 3,
  "]name": 4,
  "{name": 5,
  "}name": 6,
  "<name": 7
}

items[0] 1
/people/{id} {get x}
a:b colon

/people/{id} {get x}
a:b colon
items[0] 1

{
  "items[0]": 1,
  "/people/{id}": {
    "get": "x"
  },
  "a:b": "colon"
}

Keys must be unique within a map. Repeated keys are errors, even when their values agree or one occurrence is written as a tag. Canonical formatting sorts members by key name, with boolean members collected into a tag group before the remaining members. These rules apply recursively to nested maps.

{name Ada age 36 active true}

<active>
age 36
name Ada

{
  "name": "Ada",
  "age": 36,
  "active": true
}

Tags are shorthand for boolean-valued members of a map. Tags form a set of string names, each associated with a boolean value. They are not general-purpose sets of arbitrary values: names are represented as JSON object keys, which can only be strings. A tag group encloses key names between < and >. A name without a prefix gives that key the value true. An immediately preceding ! gives it the value false. Tags introduce no new value type and are distinct from the #-prefixed objects called tagged elements below.

<foo bar !baz>
name Ada

<bar !baz foo>
name Ada

{
  "foo": true,
  "bar": true,
  "baz": false,
  "name": "Ada"
}

The formatter collects all boolean members into one group before the other members. It sorts tags by their key names, without including the negation marker in the sort. The remaining members follow in key-name order.

Ordinary boolean members remain valid input. Input may contain multiple tag groups anywhere an object member can begin, including before, between, or after ordinary members. For example:

<foo>
name Ada
age 36
baz false
<bar>

<bar !baz foo>
age 36
name Ada

{
  "foo": true,
  "name": "Ada",
  "age": 36,
  "baz": false,
  "bar": true
}

Tag groups also balance names across rows when they exceed the width target. A group with attached comments uses separate lines so each comment stays with its name:

<configuration development documentation experimental instrumentation observability performance production validation>

<configuration development documentation
 experimental instrumentation observability
 performance production validation>

{
  "configuration": true,
  "development": true,
  "documentation": true,
  "experimental": true,
  "instrumentation": true,
  "observability": true,
  "performance": true,
  "production": true,
  "validation": true
}

<tag00_longname tag01_longname tag02_longname tag03_longname tag04_longname tag05_longname tag06_longname tag07_longname tag08_longname tag09_longname tag10_longname>

<tag00_longname tag01_longname tag02_longname tag03_longname
 tag04_longname tag05_longname tag06_longname tag07_longname
 tag08_longname tag09_longname tag10_longname>

{
  "tag00_longname": true,
  "tag01_longname": true,
  "tag02_longname": true,
  "tag03_longname": true,
  "tag04_longname": true,
  "tag05_longname": true,
  "tag06_longname": true,
  "tag07_longname": true,
  "tag08_longname": true,
  "tag09_longname": true,
  "tag10_longname": true
}

Duplicate names are errors both within a group and across groups or ordinary members. For example, <foo !foo> and {<foo> foo false} are invalid.

The name “tagged element” comes from the EDN format specification.

A tagged element represents an object with exactly one #-prefixed key. Its canonical spelling is #prefix value, without object braces. The prefix consumes exactly one value and is valid at the document root, in a list, or as a map member's value:

color #color blue
point #point [1 2]

color #color blue
point #point [1 2]

{
  "color": {
    "#color": "blue"
  },
  "point": {
    "#point": [
      1,
      2
    ]
  }
}

[#color blue #point [1 2] #flag true #nothing null]

[#color blue #point [1 2] #flag true #nothing null]

[
  {
    "#color": "blue"
  },
  {
    "#point": [
      1,
      2
    ]
  },
  {
    "#flag": true
  },
  {
    "#nothing": null
  }
]

The payload may be any value, including another tagged element:

#outer #inner [1 2]

#outer #inner [1 2]

{
  "#outer": {
    "#inner": [
      1,
      2
    ]
  }
}

Tagged-element payloads participate in the same width calculation:

#values [item00 item01 item02 item03 item04 item05 item06 item07 item08 item09 item10 item11 item12 item13 item14 item15 item16 item17 item18 item19 item20 item21]

#values [item00 item01 item02 item03 item04
         item05 item06 item07 item08 item09
         item10 item11 item12 item13
         item14 item15 item16 item17
         item18 item19 item20 item21]

{
  "#values": [
    "item00",
    "item01",
    "item02",
    "item03",
    "item04",
    "item05",
    "item06",
    "item07",
    "item08",
    "item09",
    "item10",
    "item11",
    "item12",
    "item13",
    "item14",
    "item15",
    "item16",
    "item17",
    "item18",
    "item19",
    "item20",
    "item21"
  ]
}

The ordinary object spelling remains valid input. The formatter converts an eligible single-key object to tagged-element notation:

{#color blue}

#color blue

{
  "#color": "blue"
}

This rule also applies when the payload is boolean; tagged-element notation takes precedence over boolean tag-group notation for these single-key objects:

{#flag false}

#flag false

{
  "#flag": false
}

A prefix contains # followed by a nonempty name, then at least one space or tab before the payload. Its name cannot contain whitespace, commas, double quotes, or any of [], {}, (), or <>. Names outside those rules remain ordinary quoted object keys. Objects with additional keys, including $comment, retain ordinary map notation.

The payload follows compact value rules even on a member line: quote a string containing spaces or commas. Container payloads may span lines, and multiline string fences remain available.

#text "hello world"

#text "hello world"

{
  "#text": "hello world"
}

value #person {
  name Ada
  age 36}

value #person {age 36
               name Ada}

{
  "value": {
    "#person": {
      "name": "Ada",
      "age": 36
    }
  }
}

A leading # in a string must be quoted. A # inside a string is ordinary text:

["#color" "#" "a#b"]

["#color" "#" a#b]

[
  "#color",
  "#",
  "a#b"
]

At the document root, #prefix value is one complete tagged element. To write several ordinary members whose keys begin with #, use explicit object braces or quote the keys. The formatter quotes such keys in an implicit root map.

{#a 1 #b 2}

"#a" 1
"#b" 2

{
  "#a": 1,
  "#b": 2
}

RON assigns no built-in meaning to any prefix. It does not evaluate a tagged element or look up its prefix as a function. An application defines what each kind of tagged element means and which payloads it accepts.

; starts a line comment at the beginning of a line or after whitespace. The comment continues to the end of the line. A document must not mix ; comments with an explicit $comment member. Within a quoted string, or within a bare word rather than after whitespace, the same characters are text. A semicolon within an unbroken token remains text.

Comments are preserved in a map's $comment string instead of being discarded during parsing. Comment lines are joined with newlines. Prefixes record where each comment appeared:

For a list stored in a map, the prefix includes the member name and a zero-based item index, such as fields[0]. Comments inside a nested map are stored in that map's $comment member.

; A person
name Ada ; Display name

; A person
name Ada ; Display name

{
  "$comment": "A person\nname: Display name",
  "name": "Ada"
}

Comments can also follow list items or appear on separate lines between them.

fields [
  id ; identifier
]

fields [
  id ; identifier
]

{
  "$comment": "fields[0]: identifier",
  "fields": [
    "id"
  ]
}

With epsilon convert --comment-roundtrip, comments use structured JSON Pointer groups in the $comment string. The start and end groups distinguish value occurrences from collection opening and closing boundaries. Root lists use reserved comment-only objects in the JSON array; root scalars use a marker and the value. Ordinary JSON conversion keeps $comment strings as fields.

Canonical formatting depends on the decoded value, not on the input's spacing or choice of equivalent syntax. Reformatting canonical output leaves it unchanged. Canonical RON does not append a terminal newline. Internal line breaks use LF and remain part of the canonical output. For example, the integer 42 formats as exactly the two bytes 42; a map with members a 1 and b 2 formats as a 1\nb 2, where \n denotes its one internal LF.

The canonical width target is 100 text columns. The width includes indentation, prefixes, delimiters, and inline comments. It is a layout target rather than a validity limit: long strings, names, comments, and deeply indented values may exceed it. The formatter does not split a string merely to make a line fit. Columns count Unicode code points rather than display-cell widths, so an emoji may occupy more screen space than its column count.

Ordinary root maps omit their outer braces; empty maps use {}. Members sort by key name. Boolean members form one leading tag group, except that an eligible single-key #-prefixed object uses tagged-element notation. Each ordinary key/value pair has its own line, including in nested maps. The first item follows the opening brace and subsequent items align beneath it; a tag group occupies its own line before the ordinary members. Comments that must precede the first item leave the opening brace on a line of its own. Nested lists can pack eligible items up to the width target. Line-oriented layout also preserves strings and comments.