KDL 2.0.0: Document Syntax, Adoption, and Implementation Choices

What KDL 2.0.0 Changes in Document Design

KDL addresses the need for a human-readable format that can represent both configuration and serialized data without adopting the visual conventions of JSON, YAML, or XML. Its defining feature is a node-oriented syntax with XML-like node semantics. A node can have a name, positional values, properties, children, and comments. That combination lets a document keep familiar command-line shapes while still modeling nested configuration.

The intended audience includes developers designing package manifests, application settings, task files, and other structured documents. KDL is also presented as an alternative serialization format. This is a specification repository rather than a parser library, so adoption begins with understanding the language and selecting one of the listed implementations.

The repository identifies KDL 2.0.0 as the current specification and says that it has been finalized with no further changes expected. KDL 1.0.0 remains available through `SPEC_v1.md`, and the README directs users toward migration. It describes migration from KDL 1 to KDL 2 as forward-and-backward-compatible, safe, and suitable for automation. Individual implementations may still support only one version, so compatibility of the document format does not mean every parser can read it.

KDL Nodes, Properties, Strings, and Comments

A normal KDL document is built from named nodes. Child nodes are enclosed in braces, while a node can also stand alone or carry key/value properties. Positional values and properties therefore coexist without requiring every datum to be converted into an object field.

The README example places package identity and dependency data inside a `package` node. Values such as `my-pkg` are unquoted identifiers, while the version is a quoted string. The dependency line combines a positional value with properties, including `optional=#true` and `alias=underscore`. This is a useful illustration of KDL's central design choice: a document can resemble a sequence of commands without losing explicit structured values.

KDL supports raw and dedented multiline strings. It can also continue one logical node over source lines with `\`. Slashdash comments use `/-` and can suppress an entire node subtree, not merely a single line. The example marks a `this-is-commented` node as inactive, including its `is gone` child.

This syntax reduces visual ceremony, but it introduces parsing choices that an implementation must handle consistently. Implementations differ in whether they preserve formatting and comments, whether they expose diagnostics as friendly errors, and whether they can parse both major versions. The specification defines the language contract; it does not make all libraries interchangeable.

Getting Started with KDL Through the Browser

The repository does not document installation of a command-line KDL parser because `kdl-org/kdl` is the language specification, not an executable distribution. The README points users to the browser playground for an immediate way to work with KDL. No package manager command or local setup command is provided, so adding one would invent an installation procedure.

A first document can be created from the package example in the README. The following fenced block is directly based on the documented syntax. Save it as `package.kdl` only if a selected parser or tool will consume that file. The browser playground is the first documented place to try it without choosing a language-specific library.

package {
  name my-pkg
  version "1.2.3"

  dependencies {
    lodash "^3.2.1" optional=#true alias=underscore
  }
}

A reader should see one parent node named `package`, two values for `name` and `version`, and a nested `dependencies` node. Inside it, `lodash` has one positional value and two properties. The README example also demonstrates commands and multiline text. A real application would then pass the document to an implementation that supports KDL 2.0.0; this repository itself does not define a parsing API or return a parsed object.

Why KDL 2.0.0 Is Not Automatically Interoperable

The README states that there is no data ambiguity between KDL 1 and KDL 2 documents. It also says migration is forward-and-backward-compatible. Those statements concern the language design and the availability of migration, not identical behavior across every library.

The implementation table exposes the practical constraint. For example, `Kadlet` is marked for KDL 1 but not KDL 2. The Common Lisp, Crystal, Go, Haskell, Lua, Nim, PHP, Python, Ruby, Swift, and XSLT entries marked only for KDL 1 have the same version boundary. Other listed libraries cover both versions, while some JavaScript implementations are query-only or use different capabilities.

Teams should therefore verify the implementation before designing syntax around it. A library that parses package configuration may not be intended to retain source formatting. A query-only implementation does not replace a full parser. A hybrid implementation may attempt both versions, which can be convenient during migration but should not be mistaken for full feature parity among those versions.

KDL also has separate specifications for a query language based on CSS selectors and a schema language loosely based on JSON Schema. A parser for the core document syntax does not necessarily support either companion specification.

Where KDL Differs from JSON and YAML

A KDL document expresses named nodes that may contain arguments, properties, and child nodes. KDL includes slashdash node-level comments, as well as raw and dedented multiline strings for command text or other content.

KDL borrows the appearance of CLI commands. A line such as a command name followed by values and properties reads differently from a YAML mapping. That difference is useful when the document describes tools, scripts, or package metadata, because the source can resemble the commands a developer might type.

The cost of that design is ecosystem dependence. KDL has a specification and a long implementation list, yet version support is uneven. KDL is the better fit when readable command-like structure and node-level commenting matter. A team with an existing JSON or YAML schema library, strict cross-language parser expectations, or no suitable KDL 2.0.0 implementation may have less reason to change formats.

Maintenance Scope, Release State, and License Review

The repository is not archived, and its last push was on 2026-10-01. The README says KDL 2.0.0 has been finalized and that no further changes are expected. The recent releases list KDL 2.0.0 on 2024-12-22, following draft releases in December 2024. This indicates a stable specification release with an ongoing repository history, but it should not be read as a promise that every implementation will add KDL 2.0.0 support on the same schedule.

The specification still accepts reports for minor editorial fixes or critical errata. The presence of `CHANGELOG.md`, `CONTRIBUTING.md`, query and schema specifications, examples, and a tests directory reflects a broader specification project. The Makefile bootstraps the `i-d-template` repository when the `lib` directory is missing, which appears intended for building or working on the specification documents rather than installing a KDL runtime.

The repository metadata reports a custom license that GitHub cannot classify. The exact permissions and obligations therefore need to be read in `LICENSE.md` before reuse or redistribution. This review does not infer the terms from the license label and does not provide legal advice. Adoption planning should distinguish the cost of updating a KDL document from the separate maintenance burden of maintaining a parser, schema validation, query support, and any version-compatibility layer.

Editorial conclusion

KDL 2.0.0 fits developers who want a readable, node-oriented document format and can select an implementation that supports version 2. It is a poor fit for teams that need an official reference parser from this repository or require broad version support in one library. Verify the chosen parser's KDL 2.0.0 support, preservation behavior, error reporting, license, and migration procedure before adopting it for a production format.

Frequently asked questions

Official sources

1. Issues
2. kdl-org/kdl on GitHub
3. Project website
4. README
5. Releases