The KDL Document Language

3.1. Document

The toplevel concept of KDL is a Document. A Document is composed of zero or more Nodes (Section 3.2), separated by newlines and whitespace, and eventually terminated by an EOF.¶

All KDL documents should be UTF-8 encoded and conform to the specifications in this document.¶

foo {
    bar
}
baz

3.2. Node

Being a node-oriented language means that the real core component of any KDL document is the "node". Every node must have a name, which must be a String (Section 3.9).¶

The name may be preceded by a Type Annotation (Section 3.8) to further clarify its type, particularly in relation to its parent node. (For example, clarifying that a particular date child node is for the publication date, rather than the last-modified date, with (published)date.)¶

Following the name are zero or more Arguments (Section 3.5) or Properties (Section 3.4), separated by either whitespace (Section 3.17) or a slash-escaped line continuation (Section 3.3). Arguments and Properties may be interspersed in any order, much like is common with positional arguments vs options in command line tools. Collectively, Arguments and Properties may be referred to as "Entries".¶

Children (Section 3.6) can be placed after the name and the optional Entries, possibly separated by either whitespace or a slash-escaped line continuation.¶

Arguments are ordered relative to each other and that order must be preserved in order to maintain the semantics. Properties between Arguments do not affect Argument ordering.¶

By contrast, Properties SHOULD NOT be assumed to be presented in a given order. Children (Section 3.6) should be used if an order-sensitive key/value data structure must be represented in KDL. Cf. JSON objects preserving key order.¶

Nodes MAY be prefixed with Slashdash (Section 3.17.3) to "comment out" the entire node, including its properties, arguments, and children, and make it act as plain whitespace, even if it spreads across multiple lines.¶

Finally, a node is terminated by either a Newline (Section 3.18), a semicolon (;), the end of a child block (}) or the end of the file/stream (an EOF).¶

// `foo` will have an Argument value list like `[1, 3]`.
foo 1 key=val 3 {
    bar
    (role)baz 1 2
}

3.3. Line Continuation

Line continuations allow Nodes (Section 3.2) to be spread across multiple lines.¶

A line continuation is a \ character followed by zero or more whitespace items (including multiline comments) and an optional single-line comment. It must be terminated by a Newline (Section 3.18) (including the Newline that is part of single-line comments).¶

Following a line continuation, processing of a Node can continue as usual.¶

my-node 1 2 \  // comments are ok after \
        3 4    // This is the actual end of the Node.

3.4. Property

A Property is a key/value pair attached to a Node (Section 3.2). A Property is composed of a String (Section 3.9), followed immediately by an equals sign (=, U+003D), and then a Value (Section 3.7).¶

Properties should be interpreted left-to-right, with rightmost properties with identical names overriding earlier properties. That is:¶

node a=1 a=2

In this example, the node's a value must be 2, not 1.¶

No other guarantees about order should be expected by implementers. Deserialized representations may iterate over properties in any order and still be spec-compliant.¶

Properties MAY be prefixed with /- to "comment out" the entire token and make it act as plain whitespace, even if it spreads across multiple lines.¶

3.5. Argument

An Argument is a bare Value (Section 3.7) attached to a Node (Section 3.2), with no associated key. It shares the same space as Properties (Section 3.4), and may be interleaved with them.¶

A Node may have any number of Arguments, which should be evaluated left to right. KDL implementations MUST preserve the order of Arguments relative to each other (not counting Properties).¶

Arguments MAY be prefixed with /- to "comment out" the entire token and make it act as plain whitespace, even if it spreads across multiple lines.¶

my-node 1 2 3 a b c

3.6. Children Block

A children block is a block of Nodes (Section 3.2), surrounded by { and }. They are an optional part of nodes, and create a hierarchy of KDL nodes.¶

Regular node termination rules apply, which means multiple nodes can be included in a single-line children block, as long as they're all terminated by ;.¶

parent {
    child1
    child2
}

parent { child1; child2; }

3.7. Value

A value is either: a String (Section 3.9), a Number (Section 3.14), a Boolean (Section 3.15), or Null (Section 3.16).¶

Values MUST be either Arguments (Section 3.5) or values of Properties (Section 3.4). Only String (Section 3.9) values may be used as Node (Section 3.2) names or Property (Section 3.4) keys.¶

Values (both as arguments and in properties) MAY be prefixed by a single Type Annotation (Section 3.8).¶

3.8. Type Annotation

A type annotation is a prefix to any Node Name (Section 3.2) or Value (Section 3.7) that includes a suggestion of what type the value is intended to be treated as, or as a context-specific elaboration of the more generic type the node name indicates.¶

Type annotations are written as a set of ( and ) with a single String (Section 3.9) in it. It may contain Whitespace after the ( and before the ), and may be separated from its target by Whitespace.¶

KDL does not specify any restrictions on what implementations might do with these annotations. They are free to ignore them, or use them to make decisions about how to interpret a value.¶

Additionally, the following type annotations MAY be recognized by KDL parsers and, if used, SHOULD interpret these types as follows:¶

node (u8)123
node prop=(regex).*
(published)date "1970-01-01"
(contributor)person name="Foo McBar"

3.9. String

Strings in KDL represent textual UTF-8 Values (Section 3.7). A String is either an Identifier String (Section 3.10) (like foo), a Quoted String (Section 3.11) (like "foo") or a Multi-Line String (Section 3.12). Both Quoted and Multiline strings come in normal and Raw String (Section 3.13) variants (like #"foo"#):¶

• Identifier Strings let you write short, "single-word" strings with a minimum of syntax¶

• Quoted Strings let you write strings "like normal", with whitespace and escapes.¶

• Multi-Line Strings let you write strings across multiple lines and with indentation that's not part of the string value.¶

• Raw Strings don't allow any escapes, allowing you to not worry about the string's content containing anything that might look like an escape.¶

Strings MUST be represented as UTF-8 values.¶

Strings MUST NOT include the code points for disallowed literal code points (Section 3.19) directly. Quoted and Multi-Line Strings may include these code points as values by representing them with their corresponding \u{...} escape.¶

3.10. Identifier String

An Identifier String (sometimes referred to as just an "identifier") is composed of any Unicode Scalar Value other than non-initial characters (Section 3.10.1), followed by any number of Unicode Scalar Values other than non-identifier characters (Section 3.10.2).¶

A handful of patterns are disallowed, to avoid confusion with other values:¶

• idents that appear to start with a Number (Section 3.14) (like 1.0v2 or -1em) or the "almost a number" pattern of a decimal point without a leading digit (like .1).¶

• idents that are the language keywords (inf, -inf, nan, true, false, and null) without their leading #.¶

Identifiers that match these patterns MUST be treated as a syntax error; such values can only be written as quoted or raw strings. The precise details of the identifier syntax is specified in the Full Grammar in Section 4.¶

3.11. Quoted String

A Quoted String is delimited by " on either side of any number of literal string characters except unescaped " and \.¶

Literal Newline (Section 3.18) characters can only be included if they are Escaped Whitespace (Section 3.11.1.1), which discards them from the string value. Actually including a newline in the value requires using a newline escape sequence, like \n, or using a Multi-Line String (Section 3.12) which is actually designed for strings stretching across multiple lines.¶

Like Identifier Strings, Quoted Strings MUST NOT include any of the disallowed literal code-points (Section 3.19) as code points in their body.¶

Quoted Strings have a Raw String (Section 3.13) variant, which disallows escapes.¶

"Hello World"

"Hello \    World"

"Hello\       \nWorld"

    "Hello\n\
    World"

"Hello\nWorld"

"""
  Hello
  World
  """

3.12. Multi-line String

Multi-Line Strings support multiple lines with literal, non-escaped Newlines. They must use a special multi-line syntax, and they automatically "dedent" the string, allowing its value to be indented to a visually matching level as desired.¶

A Multi-Line String is opened and closed by three double-quote characters, like """. Its first line MUST immediately start with a Newline (Section 3.18) after its opening """. Its final line MUST contain only whitespace before the closing """. All in-between lines that contain non-newline, non-whitespace characters MUST start with at least the exact same whitespace as the final line (precisely matching codepoints, not merely counting characters or "size"); they may contain additional whitespace following this prefix. The lines in between may contain unescaped " (but no unescaped """ as this would close the string).¶

The value of the Multi-Line String omits the first and last Newline, the Whitespace of the last line, and the matching Whitespace prefix on all intermediate lines. The first and last Newline can be the same character (that is, empty multi-line strings are legal).¶

In other words, the final line specifies the whitespace prefix that will be removed from all other lines.¶

Multi-line Strings that do not immediately start with a Newline and whose final """ is not preceeded by optional whitespace and a Newline are illegal. This also means that """ may not be used for a single-line String (e.g. """foo""").¶

multi-line """
    \r\n[CRLF]
    foo[CRLF]
    """

single-line "\r\n\nfoo"

multi-line """
        foo
    This is the base indentation
            bar
    """

    foo
This is the base indentation
        bar

"    foo\nThis is the base indentation\n        bar"

multi-line """
        foo
    This is no longer on the left edge
            bar
  """

      foo
  This is no longer on the left edge
          bar

"      foo\n  This is no longer on the left edge\n          bar"

multi-line """
    Indented a bit

    A second indented paragraph.
    """

Indented a bit.

A second indented paragraph.

"Indented a bit.\n\nA second indented paragraph."

multi-line """can't be single line"""

multi-line """
  closing quote with non-whitespace prefix"""

multi-line """stuff
  """

// Every line must share the exact same prefix as the closing line.
multi-line """[\n]
[tab]a[\n]
[space][space]b[\n]
[space][tab][\n]
[tab]"""

  """
  foo
  bar\
  """

  // equivalent to
  """
  foo
  bar"""

  """
  foo \
bar
  baz
  \   """

  // equivalent to
  """
  foo bar
  baz
  """

3.13. Raw String

Both Quoted (Section 3.11) and Multi-Line Strings (Section 3.12) have Raw String variants, which are identical in syntax except they do not support \-escapes. This includes line-continuation escapes (\ + ws collapsing to nothing). They otherwise share the same properties as far as literal Newline (Section 3.18) characters go, multi-line rules, and the requirement of UTF-8 representation.¶

The Raw String variants are indicated by preceding the strings's opening quotes with one or more # characters. The string is then closed by its normal closing quotes, followed by a matching number of # characters. This means that the string may contain any combination of " and # characters other than its closing delimiter (e.g., if a raw string starts with ##", it can contain " or "#, but not "## or "###).¶

Like other Strings, Raw Strings MUST NOT include any of the disallowed literal code-points (Section 3.19) as code points in their body. Unlike with Quoted Strings, these cannot simply be escaped, and are thus unrepresentable when using Raw Strings.¶

just-escapes #"\n will be literal"#

quotes-and-escapes ##"hello\n\r\asd"#world"##

raw-multi-line #"""
    Here's a """
        multiline string
        """
    without escapes.
    """#

Here's a """
    multiline string
    """
without escapes.

"Here's a \"\"\"\n    multiline string\n    \"\"\"\nwithout escapes."

3.14. Number

Numbers in KDL represent numerical Values (Section 3.7). There is no logical distinction in KDL between real numbers, integers, and floating point numbers. It's up to individual implementations to determine how to represent KDL numbers.¶

There are five syntaxes for Numbers: Keywords, Decimal, Hexadecimal, Octal, and Binary.¶

• All non-Keyword (Section 3.14.1) numbers may optionally start with one of - or +, which determine whether they'll be positive or negative.¶

• Binary numbers start with 0b and only allow 0 and 1 as digits, which may be separated by _. They represent numbers in radix 2.¶

• Octal numbers start with 0o and only allow digits between 0 and 7, which may be separated by _. They represent numbers in radix 8.¶

• Hexadecimal numbers start with 0x and allow digits between 0 and 9, as well as letters A through F, in either lower or upper case, which may be separated by _. They represent numbers in radix 16.¶

• Decimal numbers are a bit more special:¶

  • They have no radix prefix.¶

  • They use digits 0 through 9, which may be separated by _.¶

  • They may optionally include a decimal separator ., followed by more digits, which may again be separated by _.¶

  • They may optionally be followed by E or e, an optional - or +, and more digits, to represent an exponent value.¶

Note that, similar to JSON and some other languages, numbers without an integer digit (such as .1) are illegal. They must be written with at least one integer digit, like 0.1. (These patterns are also disallowed from Identifier Strings (Section 3.10), to avoid confusion.)¶

3.15. Boolean

A boolean Value (Section 3.7) is either the symbol #true or #false. These SHOULD be represented by implementation as boolean logical values, or some approximation thereof.¶

my-node #true value=#false

3.16. Null

The symbol #null represents a null Value (Section 3.7). It's up to the implementation to decide how to represent this, but it generally signals the "absence" of a value.¶

my-node #null key=#null

3.17. Whitespace

The following characters should be treated as non-Newline (Section 3.18) white space:¶

3.18. Newline

The following character sequences should be treated as new lines:¶

Note that for the purpose of new lines, the specific sequence CRLF is considered a single newline.¶

3.19. Disallowed Literal Code Points

The following code points may not appear literally anywhere in the document. They may be represented in Strings (but not Raw Strings) using Unicode Escapes (Section 3.11.1) (\u{...}, except for non Unicode Scalar Value, which can't be represented even as escapes).¶

• The codepoints U+0000-0008 or the codepoints U+000E-001F (various control characters).¶

• U+007F (the Delete control character).¶

• Any codepoint that is not a Unicode Scalar Value (U+D800-DFFF).¶

• U+200E-200F, U+202A-202E, and U+2066-2069, the unicode "direction control" characters¶

• U+FEFF, aka Zero-width Non-breaking Space (ZWNBSP)/Byte Order Mark (BOM), except as the first code point in a document.¶

4.1. Grammar language

The grammar language syntax is a combination of ABNF with some regex spice thrown in. Specifically:¶

• Single quotes (') are used to denote literal text. \ within a literal string is used for escaping other single-quotes, for initiating unicode characters using hex values (\u{FEFF}), and for escaping \ itself (\\).¶

• * is used for "zero or more", + is used for "one or more", and ? is used for "zero or one". Per standard regex semantics, * and + are greedy; they match as many instances as possible without failing the match.¶

• *? (used only in raw strings) indicates a non-greedy match; it matches as few instances as possible without failing the match.¶

• ¶ is a cut point. It always matches and consumes no characters, but once matched, the parser is not allowed to backtrack past that point in the source. If a parser would rewind past the cut point, it must instead fail the overall parse, as if it had run out of options. (This is only used with the raw-string production, to ensure the first instance of the appropriate closing quote sequence is guaranteed to be the end of the raw string, rather than allowing it to potentially consume more of the document unexpectedly.)¶

• () can be used to group matches that must be matched together.¶

• a | b means a or b, whichever matches first. If multiple items are before a |, they are a single group. a b c | d is equivalent to (a b c) | d.¶

• [] are used for regex-style character matches, where any character between the brackets will be a single match. \ is used to escape \, [, and ]. They also support character ranges (0-9), and negation (^)¶

• - is used for "except for" or "minus" whatever follows it. For example, a - 'x' means "any a, except something that matches the literal 'x'".¶

• The prefix ^ means "something that does not match" whatever follows it. For example, ^foo means "must not match foo".¶

• A single definition may be split over multiple lines. Newlines are treated as spaces.¶

• // followed by text on its own line is used as comment syntax.¶