2.0.0

It's finally here! KDL 2.0.0 is a major overhaul of the language. It keeps to the spirit of 1.0.0 but addresses a lot of tiny sharp corners, and adds a few exciting new features to make the language overall more ergonomic, easier to manage, and more pleasant on the eyes. It is the culmination of over 3 years of work by scores of contributors, implementers, and community members. It draws from years of experience with KDL 1.0.0 in the wild.

KDL 2.0.0 documents are unambiguous with KDL 1.0.0 documents: if a document happens to parse with either parser, the data is guaranteed to be the exact same.

For up-to-date information on what parsers support which versions of the language, please refer to the implementations table in the README.

Grammar

• Solidus/Forward slash (/) is no longer an escaped character.
• Space (U+0020) can now be written into quoted strings with the \s
  escape.
• Single line comments (//) can now be immediately followed by a newline.
• All literal whitespace following a \ in a string is now discarded.
• Vertical tabs (U+000B) are now considered to be newlines.
• The grammar syntax itself has been described, and some confusing definitions
  in the grammar have been fixed accordingly (mostly related to escaped
  characters).
• ,, <, and > are now legal identifier characters. They were previously
  reserved for KQL but this is no longer necessary.
• Code points under 0x20 (except newline and whitespace code points), code
  points above 0x10FFFF, Delete control character (0x7F), and the unicode
  "direction control"
  characters
  are now completely banned from appearing literally in KDL documents. They
  can now only be represented in regular strings, and there's no facilities to
  represent them in raw strings. This should be considered a security
  improvement.
• Raw strings no longer require an r prefix: they are now specified by using
  #""#.
• Raw string productions are now explicitly non-greedy (and "fallible").
• Line continuations can be followed by an EOF now, instead of requiring a
  newline (or comment). node \<EOF> is now a legal KDL document.
• # is no longer a legal identifier character.
• null, true, and false are now #null, #true, and #false. Using
  the unprefixed versions of these values is a syntax error.
• The spec prose has more explicitly stated that whitespace and newlines are
  not valid identifier characters, even though the grammar already expressed
  this.
• Bare identifiers can now be used as values in Arguments and Properties, and are interpreted as string values.
• The spec prose now more explicitly states that strings and raw strings can
  be used as type annotations.
• Removed a statement in the spec prose that said "It is reasonable for an
  implementation to ignore null values altogether when deserializing". This is
  no longer encouraged or desired.
• Code points have been constrained to Unicode Scalar
  Values only, including
  values used in string escapes (\u{}). All KDL documents and string values
  should be valid UTF-8 now, as was intended.
• The last node in a child block no longer needs to be terminated with ;,
  even if the closing } is on the same line, so this is now a legal node:
  node{foo;bar;baz}
• More places allow whitespace (node-spaces, specifically) now. With great
  power comes great responsibility:
  • Inside (foo) annotations (so, ( foo ) would be legal (( f oo ) would
    not be, since it has two identifiers))
  • Between annotations and the thing they're annotating ((blah) node (thing) 1 y= (who) 2)
  • Around = for props (x = 1)
• The BOM is now only allowed as the first character in a document. It was
  previously treated as generic whitespace.
• Multi-line strings must now use """ as delimeters. The opening delimiter must be immediately followed by a newline, and the closing delimiter must be on its own line, prefixed by optional whitespace.
• Multi-line strings are now automatically dedented, according to the common
  whitespace matching the whitespace prefix of the closing line.
• .1, +.1 etc are no longer valid identifiers, to prevent confusion and
  conflicts with numbers.
• Multi-line strings' literal Newline sequences are now normalized to single
  LFs.
• #inf, #-inf, and #nan have been added in order to properly support
  IEEE floats for implementations that choose to represent their decimals that
  way.
• Correspondingly, the identifiers inf, -inf, and nan are now syntax
  errors.
• u128 and i128 have been added as well-known number type annotations.
• Slashdash (/-) -compatible locations adjusted to be more clear and
  intuitive. They can now be used in exactly three different places: before nodes,
  before entire entries, or before entire child blocks.
• Furthermore, The ordering of slashdashed elements has been restricted such
  that a slashdashed child block cannot go before an entry (including slashdashed
  entries).
• Optional version marker /- kdl-version 2 (or 1) as the first line in a document, optionally preceded by the BOM.

KQL

[!INFO] Note: these are provided for convenience, but as of the 2.0.0 KDL spec release,
KQL itself is not finalized and should be considered a separate specification,
alongside the Schema spec and others.

• There's now a required descendant selector (>>), instead of using plain
  spaces for that purpose.
• The "any sibling" selector is now ++ instead of ~, for consistency with
  the new descendant selector.
• Some parsing logic around the grammar has changed.
• Multi- and single-line comments are now supported, as well as line
  continuations with \.
• Map operators have been removed entirely.

New Contributors

• @thammin made their first contribution in #151
• @chris-morgan made their first contribution in #152
• @IceDragon200 made their first contribution in #156
• @jihchi made their first contribution in #161
• @benjreinhart made their first contribution in #162
• @swift2plunder made their first contribution in #167
• @danderson made their first contribution in #168
• @Devasta made their first contribution in #201
• @CAD97 made their first contribution in #206
• @djmattyg007 made their first contribution in #239
• @fuzzypixelz made their first contribution in #243
• @tailhook made their first contribution in #256
• @boringcactus made their first contribution in #259
• @spaarmann made their first contribution in #263
• @pingiun made their first contribution in #271
• @oledfish made their first contribution in #276
• @fabiancook made their first contribution in #278
• @basile-henry made their first contribution in #234
• @Lucretiel made their first contribution in #290
• @bkane-msft made their first contribution in #301
• @imsnif made their first contribution in #305
• @Patitotective made their first contribution in #311
• @Exidex made their first contribution in #312
• @chee made their first contribution in #319
• @lunjon made their first contribution in #334
• @sblinch made their first contribution in #336
• @mikavilpas made their first contribution in #369
• @wackbyte made their first contribution in #375
• @alightgoesout made their first contribution in #388
• @segiddins made their first contribution in #405
• @Alch-Emi made their first contribution in #410
• @wommy made their first contribution in #383

Full Changelog: 1.0.0...2.0.0

2.0.0-draft.8

What's Changed

• Some details have been clarified around the treatment of whitespace in
  multiline strings.
• raw-string productions have been updated to be explicitly non-greedy and
  "fallible".
• Some tests have been added, others adjusted, some removed, after a cleanup pass.

New Contributors

• @wommy made their first contribution in #383

Full Changelog: 2.0.0-draft.7...2.0.0-draft.8

2.0.0-draft.7

• node-space is now allowed as whitespace after a slashdash, meaning line
  continuations will work now.
• One or two consecutive double-quotes are now allowed in the bodies of
  multi-line quoted strings, without needing to be escaped.
• Grammar has been fixed to disallow raw strings like #"""#, which are now
  properly treated as invalid multi-line raw strings (instead of the equivalent of
  "\"").
• Test suite has been updated to include a _fail suffix in all test cases
  which are expected to fail.
• A slew of additional slashdash and multi-line string compliance tests have
  been added. Have fun. :)
• The organization of string types in the spec prose has been updated to a
  hopefully more helpful structure.

2.0.0-draft.6

What's Changed

• Multiline strings, both Raw and Quoted, must now use """ instead of a single ". Using """ for a single-line string is a syntax error.
• Fixed an issue with the unicode_silly test case.
• Some rewordings and clarification in the spec prose.
• Slight grammar tweak where the pre-terminator node-space* for node and final-node have been moved into base-node.

New Contributors

• @mikavilpas made their first contribution in #369
• @segiddins made their first contribution in #405
• @Alch-Emi made their first contribution in #410

Full Changelog: 2.0.0-draft.5...2.0.0-draft.6

2.0.0-draft.5

What's changed

• Equals signs other than = are no longer supported in properties.
• 128-bit integer type annotations have been added to the list of "well-known"
  type annotations.
• Multiline string escape rules have been tweaked significantly.
• \s is now a valid escape within a string, representing a space character.
• Slashdash (/-)-compatible locations and related grammar adjusted to be more
  clear and intuitive. This includes some changes relating to whitespace,
  including comments and newlines, which are breaking changes.
• Various updates to test suite to reflect changes.

Full Changelog: 2.0.0-draft.4...2.0.0-draft.5

2.0.0-draft.4

What's Changed

• v2: Fix broken formatting in grammar language example by @wackbyte in #375
• v2: Remove extra indent in CI example by @wackbyte in #376

New Contributors

• @wackbyte made their first contribution in #375

Full Changelog: 2.0.0-draft.3...2.0.0-draft.4

2.0.0-draft.3

Full Changelog: 2.0.0-draft.2...2.0.0-draft.3

2.0.0-draft.2

What's Changed

• KDL V2 Test Fixes by @IceDragon200 in #368

Full Changelog: 2.0.0-draft.1...2.0.0-draft.2

2.0.0-draft.1

What's Changed

• add missing quotation marks by @thammin in #151
• Fix a broken internal link by @chris-morgan in #152
• Correct bom from U+FFEF to U+FEFF by @chris-morgan in #153
• Added Elixir implementation to list by @IceDragon200 in #156
• Fix typo by @jihchi in #161
• Prevent markdown from parsing as link by @benjreinhart in #162
• Re: Issue #165 - "Test case request: Node with same name" by @swift2plunder in #167
• tests: adjust bare identifier inputs to match spec. by @danderson in #168
• tests: ensure output of illegal bare ident is quoted by @benjreinhart in #178
• Add type annotation tests from kdl4j by @hkolbeck in #181
• Update line continuation wording by @benjreinhart in #184
• tests: add more coverage for keywords by @benjreinhart in #189
• Added xml2kdl to the list of implementations. by @Devasta in #201
• argument/property ordering clarification by @CAD97 in #206
• Do not escape solidus (forwardslash) in test by @danini-the-panini in #198
• fix: non-decimal test output according to docs by @danini-the-panini in #196
• Add missing expected file by @tabatkins in #217
• Empty children aren't reflected in the data model. by @tabatkins in #219
• Verify that a slash-dashed prop doesn't shadow a previous prop of the same name by @tabatkins in #227
• Per #223 discussion, this should be a parse error. by @tabatkins in #226
• Add link to additional python implementation by @djmattyg007 in #239
• [editorial] tweak node-props-and-args grammar by @tabatkins in #240
• Add link to Haskell implementation by @fuzzypixelz in #243
• Add knuffel to the list of implementations by @tailhook in #256
• Fix #212 by clarifying left/right by @tabatkins in #249
• Define digit in formal grammar by @CAD97 in #236
• Clarify the parsing of hostname and idl-hostname by @tabatkins in #248
• fix kdl-schema.kdl well-formedness by @boringcactus in #259
• allow contributor links in kdl-schema.kdl by @boringcactus in #260
• Mention multi-line comments in spec prose by @spaarmann in #263
• Add more info about the hyphen character in identifiers by @pingiun in #271
• Remove children from node terminals by @bgotink in #275
• Fix RFC typo by @oledfish in #276
• Add .NET library to the implementation list by @oledfish in #277
• Add @virtualstate/kdl to implementations by @fabiancook in #278
• Correct @virtualstate/kdl description by @fabiancook in #279
• Do not escape / (Solidus, Forwardslash) by @danini-the-panini in #197
• KQL: require operator and change operator grammar a bit by @zkat in #221
• KQL: remove map operator and accessors by @zkat in #222
• Allow "empty" single line comments in the spec by @basile-henry in #234
• Use forward slash in solidus-escape test by @bgotink in #288
• Update expected output of test with changed input by @bgotink in #289
• Add escaped whitespace to KDL strings by @Lucretiel in #290
• Add escaped whitespace note to v2 changelog by @hkolbeck in #291
• Add test for empty single-line comment by @bgotink in #292
• Make JSON-in-KDL more minimalistic by @bgotink in #293
• Mention ckdl in the README by @tjol in #296
• Improvements to string naming consistency by @Lucretiel in #299
• Add links to XML2KDL repo/online editor by @bkane-msft in #301
• Remove credit from test suite README by @hkolbeck in #304
• docs(readme): link to vim syntax plugin by @imsnif in #305
• Add OCaml implementation to the README by @eilvelia in #307
• Add draft grammar for KQL 1.0.0 by @larsgw in #303
• Replace use of non-defined 'tag' term by @larsgw in #310
• kdl-nim implementation by @Patitotective in #311
• Add Intellij IDEA plugin to README.md by @Exidex in #312
• Add link to common lisp implementation by @chee in #319
• Fix a typo in SPEC.md by @eugenesvk in #323
• add playground link to README.md by @danini-the-panini in #332
• add Sublime Text support by @eugenesvk in #326
• Add link to Go implementation by @lunjon in #334
• Add kdl-go to README.md by @sblinch in #336
• Update formal grammar for KDL 2.0 by @CAD97 in #285
• fix some confusion in grammar syntax, and actually specify the syntax… by @zkat in #351
• allow ,<> as identifier characters since they no longer need to be re… by @zkat in #352
• treat bare identifiers and strings in value locations by @zkat in #358

New Contributors

• @thammin made their first contribution in #151
• @chris-morgan made their first contribution in #152
• @jihchi made their first contribution in #161
• @benjreinhart made their first contribution in #162
• @swift2plunder made their first contribution in #167
• @danderson made their first contribution in #168
• @Devasta made their first contribution in #201
• @CAD97 made their first contribution in #206
• @djmattyg007 made their first contribution in #239
• @fuzzypixelz made their first contribution in #243
• @tailhook made their first contribution in #256
• @boringcactus made their first contribution in #259
• @spaarmann made their first contribution in #263
• @pingiun made their first contribution in #271
• @oledfish made their first contribution in #276
• @fabiancook made their first contribution in #278
• @basile-henry made their first contribution in #234
• @Lucretiel made their first contribution in #290
• @bkane-msft made their first contribution in #301
• @imsnif made their first contribution in #305
• @eilvelia made their first contribution in #307
• @Patitotective made their first contribution in #311
• @Exidex made their first contribution in #312
• @chee made their first contribution in #319
• @eugenesvk made their first contribution in #323
• @lunjon made their first contribution in #334
• @sblinch made their first contribution in #336

Full Changelog: 1.0.0...2.0.0-draft.1

1.0.0

We did it! 1.0.0 happened!