KDL - The KDL Document Language

KDL is a document language with xml-like semantics that looks like you're invoking a bunch of CLI commands!

It's meant to be used both as a serialization format and a configuration language, and is relatively light on syntax compared to XML.

There's a living specification, as well as implementations. The language is based on SDLang, with a number of modifications and clarifications on its syntax and behavior.

Design and Discussion

KDL is still extremely new, and discussion about the format should happen over on the discussions page. Feel free to jump in and give us your 2 cents!

Design Principles

1. Maintainability
2. Flexibility
3. Cognitive simplicity and Learnability
4. Ease of de/serialization
5. Ease of implementation

Implementations

• Rust: kdl-rs
• JavaScript: kdljs

Editor Support

• VS Code

Overview

Basics

A KDL node is a node name, followed by zero or more "arguments", and children.

title "Hello, World"

You can also have multiple values in a single node!

bookmarks 12 15 188 1234

Nodes can have properties.

author "Alex Monad" email="alex@example.com" active=true

And they can have nested child nodes, too!

contents {
  section "First section" {
    paragraph "This is the first paragraph"
    paragraph "This is the second paragraph"
  }
}

Nodes without children are terminated by a newline, a semicolon, or the end of a file stream:

node1; node2; node3;

Values

KDL supports 4 data types:

• Strings: "hello world"
• Numbers: 123.45
• Booleans: true and false
• Null: null

Strings

It supports two different formats for string input: escaped and raw.

node "this\nhas\tescapes"
other r"C:\Users\zkat\"

Both types of string can be multiline as-is, without a different syntax:

string "my
multiline
value"

And for raw strings, you can add any number of # after the r and the last " to disambiguate literal " characters:

other-raw r#"hello"world"#

Numbers

There's 4 ways to represent numbers in KDL. KDL does not prescribe any representation for these numbers, and it's entirely up to individual implementations whether to represent all numbers with a single type, or to have different representations for different forms.

KDL has regular decimal-radix numbers, with optional decimal part, as well as an optional exponent.

num 1.234e-42

And using the appropriate prefix, you can also enter hexadecimal, octal, and binary literals:

my-hex 0xdeadbeef
my-octal 0o755
my-binary 0b10101101

Finally, all numbers can have underscores to help readability:

bignum 1_000_000

Comments

KDL supports C-style comments, both line-based and multiline. Multiline comments can be nested.

// C style

/*
C style multiline
*/

tag /*foo=true*/ bar=false

/*/*
hello
*/*/

On top of that, KDL supports /- "slashdash" comments, which can be used to comment out individual nodes, arguments, or children:

// This entire node and its children are all commented out.
/-mynode "foo" key=1 {
  a
  b
  c
}

mynode /-"commented" "not commented" /-key="value" /-{
  a
  b
}

More Details

// Nodes can be separated into multiple lines
title \
  "Some title"


// Files must be utf8 encoded!
smile "😁"

// Instead of anonymous nodes, nodes and properties can be wrapped
// in "" for arbitrary node names.
"!@#$@$%Q#$%~@!40" "1.2.3" "!!!!!"=true

// The following is a legal bare identifier:
foo123~!@#$%^&*.:'|/?+ "weeee"

// And you can also use unicode!
ノード　お名前＝"☜(ﾟヮﾟ☜)"

// kdl specifically allows properties and values to be
// interspersed with each other, much like CLI commands.
foo bar=true "baz" quux=false 1 2 3

License

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.