The KDL Document Language | Hacker News Reader

The KDL Document Language

kdl.dev

162 pointsingve62 comments

Hi!

I'm the author of the Java KDL library, https://github.com/hkolbeck/kdl4j. I'm currently overwhelmed by other things and unable to do the work to get it up to the 1.0.0 spec. I'm looking for folks willing to help me. DM me on Twitter at the same name if you're interested.

thank you for this very cool effort; what if the folks able to help are those who shun twitter?

(of the strong programmers i know, each refuses to have anything to do with twitter.)

They can email hskolbeck at gmail :)

Looks interesting enough to put it on my "to evaluate/play-around" pile.

I'd be interested to know what the author thinks about RON[0], it's not quite the same but also has some nice properties and wants to be a replacement for JSON (yes this is more one for XML or JSON, but still).

Sometimes I wonder if all those formats would never have got invented if JSON had just allowed comments and trailing commas in the first place. While there's JSON5[1] now, it just has not the same level of native (ecosystem) support as JSON has.

[0]: https://github.com/ron-rs/ron

[1]: https://json5.org/

I like it :) As "precise" and "analytical" we like to think we are (well I least). I can fully agree with the FAQ section;

Why yet another document language?: "Because nothing out there felt quite right."

Sometimes looking at code (my code) or platforms, frameworks etc, this "does it feels right" plays big part in my decision to use/like it.

I really like the /- ("slashdash") comments. Seems like they did a lot of things right! I might use this in projects.

Me too! I sometimes do this in lisp, to comment out the following expression:

    * '(1 #+nil 2 3)
    (1 3)

I have pretty much no interest in another markup language (or whatever we're calling these sorts of things today[1]) but I really want the slashdash comment style in every language I use now, that's an incredible idea.

[1] apparently I didn't edit this in fast enough but wow I have even less interest in semantic arguments about what is and isn't a markup language.

The author specifically mentions at the end that they do not mean KDL to be a markup language:

> Finally, KDL is not a markup language. XML or HTML do a much better job of "marking up" a text document with special tags, although KDL can still be useful for templating engines that want to be more strict about text fragments.

Yeah tbh I don't know why syntax commenting isn't more common; when I wrote a language with s-exprs one of the earliest things I did was add a comment form to comment out an expression. And _especially_ in s-exprs it's almost trivial to add! Really don't understand why we don't see it more.

so do(n't) I.

Why is the slashdash comment style an incredible idea?

because commenting out multiple lines of code in most languages is tedious and involves me doing work the compiler already knows how to do in my head.

Sure, editors often have shortcuts, but then undoing them is often a pain and sometimes I'm editing something in a really basic editor and it'd be nice to just let the compiler to it.

I've long made half-hearted stabs at creating what I call "NFML", a.k.a. "No Markup Language". My vision is incredibly similar to this, so I wish you luck! I believe the future resembles KDL.

Nice doc, but I feel like it's confusing documents like XML/HTML and tree-structured data like JSON.

It seems like it would be annoying to write this directly, like how do you make a word bold or italic? How do you make a class of hyperlink that's a different color (e.g. internal links vs. external)? HTML is OK but not fun to write directly -- I'm not sure that KDL is an improvement. You would still want something like Markdown.

On the other hand it could be better for tables, which are awkward in HTML. But I'd like to see how that works.

In summary:

- XML/HTML: better when you have more text than data. Good for docs, awkward for tables.

- JSON: better when you have more data than text. Good for web API request and response, awkward for docs (e.g. do you want to write markdown or HTML inside double quotes?). OK for config files but awkward because it's a strict format.

Right near the end:

> Finally, KDL is not a markup language.

Here's an example of how a HTML page would be presented.

https://github.com/kdl-org/kdl/blob/main/examples/website.kd...

It actually looks pretty similar to GraphQL but without parens around argument lists. I wonder whether the author looked at it as well (might be interesting to compare).

Which reminds me, the doc doesn’t mention typeaheads. The ability to provide suggestions should be one of the considerations when designing a new syntax.

Oh wow. That’s actually surprising readable. I’m genuinely impressed.

reminds me of slim templates, but not just for Ruby

http://slim-lang.com/

This isn't meant to replace HTML. I see it as a better language for configs. JSON lacks comments. YAML also has problems: https://noyaml.com/

The very first example is a document with metadata like title, author, etc. It's called a "document language".

It seems to be straddling documents and configuration, which in my experience makes for a lot of awkwardness.

This part seems to be a symptom of that:

There are two specifications for writing KDL that can be losslessly translated between it and JSON or XML. These specifications define a stricter subset of KDL that, even if NOT entirely idiomatic, is still valid and fits into the data models of the other two languages: (emphasis mine)

  > The very first example is a document with metadata like title, author, etc. It's called a "document language".

Static sites generators often have content in markdown, but I also saw quite some use of YAML or JSON.

  > It seems to be straddling documents and configuration, which in my experience makes for a lot of awkwardness.

It seems to be for structured data, that can be both a document of some sorts or a configuration; just like YAML/JSON/XML is used for both.

  > There are two specifications for writing KDL that can be losslessly translated between it and JSON or XML.
  > These specifications define a stricter subset of KDL that, even if NOT entirely idiomatic, is still valid and fits into the data models of the other two languages: (emphasis mine)

Note that the author means two separate, additional specifications about how to losslessly translate (iow. convert) between KDL and JSON or XML, not that the actual KDL spec has provisions for reading JSON/XML as KDL. I mean, FWICT some JSON file may parse though, but it's not like YAML, which is an actual superset of JSON; now _that_ adds awkwardness.

One can also create a spec to transform JSON into XML, that does not mean it has anything directly to do with the XML spec.

I rather see this as effort to make it easier to switch to KDL, if one finds its characteristics nice(r).

I have no idea what people are complaining about in this thread. I find projects like this genius. I love making programming languages and I hate hate hate writing parsers, yet I enjoy experimenting with different syntax. Stuff like this is very convenient because you can just import your code as document, use path language to extract data, and schema language to apply basic checks. Not only is this thing standardized[1], it's implemented in your favorite language (Rust, Python, Java whatever).

[1] EDIT: to be clear here, I meant to say it has a specification. I'm guessing your handbaked language won't have.

When my projects are posted publicly, I like attaboys, but I need constructive criticism. Asking pointed questions and questioning purported inconsistencies is not complaining.

Criticism given by those that do not align with the core goals/userbase of a project is not constructive. Giving criticism on something you don't intend to/wouldn't use is just complaining.

I disagree, there's always the chance that there is a nugget of useful knowledge in there. I'd rather go through 100s of criticisms than miss it.

For some perspective, this HN thread is much, much better than the Reddit post from yesterday. Sure, there were a couple of good points hidden in the rubble, but lordy it was bad. Cruel, even. The main author has taken a break (and fair enough) so you probably won't see them around today.

Yuck.

I think this post is pure grandstanding. Giving good feedback is hard, and almost no one knows how to do it. Now, combine that with someone that has no skin in the game and is sometimes posting in-bad-faith, you're just creating a sea of garbage to wade through. To then say "yeah but I'd do it because _maybe_ I'd get something useful" is silly. No you wouldn't. You'd create a legitimized channel (Slack, Discord, email list) for people that are _actually interested_ and then talk to them directly. Posts like this are mostly just to put content in front of eyes that _would_ join such a legitimized channel.

Message boards are message boards. You can't take them seriously, including this one.

Who commented that you don't imagine uses configuration files?

To me it looks amazing, and I was literally about to adopt it in one of my open source Rust-based projects, but then I realized that the Rust version (and only the Rust version) is restrictively licensed under the Parity Public License [1].

I want my open source project to be able to be used in commercial applications, and don't want any of my dependencies' licenses to restrict that.

[1]: https://github.com/kdl-org/kdl-rs/blob/87f836134c1d901ff5ce6...

Alternative implementation for serde at https://github.com/Lucretiel/kaydle, MPL-2.0

Love to use this in my projects. Anyone aware of a C implementation?

Hmm... Not really sure I get what problem this schema is the best solution for. It seems like the author was more interested in implementing a model they felt was more conceptually sound than other solutions, but aren't solving any significant problems, and don't seem to have any big functional improvements over more established contenders.

Just going through the section for why they think it beats YAML:

> YAML can be ambiguous about what types the data written into it is.

If you're worried about data types, that sounds like a job for a proper data storage format rather than putting it into a configuration file, no?

> There's also a persistent issue where very large YAML files become unmanageable, especially due to the significant indentation feature.

That sounds like a poorly designed configuration setup. If you've got a nested config that complex, by my reckoning, it should be reorganized into flatter data structures or broken down into more specific configuration files regardless of what the format is.

>YAML is a great, widespread language. Unlike KDL, which is node-based (like XML or HTML), it's based on map and array data structures, which can provide an easier serialization experience in some cases.

Saying that processing node-based formats is more difficult in 'some cases' is a particularly charitable take, especially when they're touting their ability to handle very large, complex configurations.

> KDL is designed to avoid these particular pitfalls by always being explicit about types, and having clearly-delimited scope (and the ability to auto-indent/auto-format). Syntax errors are easier to catch, and large files are (hopefully!) much more manageable.

It seems like it adds significant complexity over YAML to mitigate abuse of YAML... but wouldn't it just be better to do a better job using YAML?

I do tend to be biased towards conforming to the usage practices of existing tools rather than adopting new tools for edge cases or minor conflicts because learning new tools tends to have a slightly higher cognitive toll for me than some others— but as a general rule, I don't see a problem with only switching tools because you have a problem that's significantly more difficult or less efficient to solve with the old tool.

Maybe there's some really clear use cases that aren't obvious to me for whatever reason.

I felt similarly when I first saw it, but I saw that there was no java impl, and I'd been looking for a project, so I wrote one. I've been playing with it for more than 6 months and I think it's better than YAML in a number of ways. The syntax is very clear and mostly simple and the noted ability to autoformat is no small thing. I think it aims for a niche, and hits its target pretty well.

Fair enough— not my niche, I guess.

After dealing with a bunch of really hairy, complex, node-based data processing for a few years, I'd sooner roll around in a dusty sandbox with my eyes taped open than purposefully invite that into my life again... but if I suppose if you're doing something that dumb in your config files then the config format isn't the problem, anyway. Cheers.

> That sounds like a poorly designed configuration setup. If you've got a nested config that complex, by my reckoning, it should be reorganized into flatter data structures or broken down into more specific configuration files regardless of what the format is.

YAML isn’t just for config. It’s also a serialization format. If your internal data structures are deeply-nested, then the YAML serialization of them will also (properly) be deeply-nested.

Sometimes you need to hand-edit some data in a multi-megabyte YAML-serialized file. It’s possible, but it’s kind of awful. Editing a multi-megabyte KDL-serialized file sounds like it might be slightly less awful.

(Maybe I’m weird, but I see this format as being close to a textual analog of https://en.wikipedia.org/wiki/Interchange_File_Format, as used/inherited by file formats like AIFF, PNG, etc. Maybe picturing a PNG file or the like encoded in this format might make it clearer what the author is going for?)

> It seems like it adds significant complexity over YAML to mitigate abuse of YAML

On the complexity axis I think you're talking about, yes, having clear scopes and no ambiguity about whether something is a string means there are more bits of syntax to type, but I don't think that adds complexity. JSON has more curly braces and quotes but it is a much simpler and much more reliable format than YAML. KDL is the same.

KDL does not "add significant complexity over YAML" in really any sense. The KDL specification is 1/10th the size of YAML's. Being extraordinarily complex and impossible to fully implement is is what YAML is famous for.[0] Asking people to do a better job writing YAML is a tough ask when even computers can barely do it correctly.

[0]: https://www.arp242.net/yaml-config.html

They mention xml quite early but bury how you’d do markup inside a text. Basically you can’t do it, but there is a convention to work around it.

> If the element contains mixed text and element children, the text can be encoded as a KDL node with the name - with a single string unnamed argument. For example, the XML

    <span>some <b>bold</b> text</span>

> can be encoded as

    span { - "some "; b "bold"; - " text" }.

I'm pretty sure that's invalid KDL, despite appearing in the XML-in-KDL document. Both the grammar and kdl-rs appear to require a trailing semicolon before the close brace. I think this might be a bug in one of the specs.

I'm quite fond of KDL and intend to use it in a future project.

Quick said-contras:

Q: "Another markup/config language?" A: Yes. We actually do get (slowly) better at solving already-solved problems. Evolution of spec does happen and is important. Steady refinement and reflection on past work just is progress.

Q: "OK, but is it worth the mental clutter and cognitive load of an additional standard/dependency/format?" A: That's for the market and community to decide together. Example: Time was, Markdown was a bizarre hobby format and most work happened in XML or LaTeX or Wiki (or, gasp, Perldoc). But Markdown proved better, more sensible; so Markdown won.

Q: "Why not YAML?" A: Am I the only old here who remembers the era of YAML security bugs? Like, it was like the Sendmail Bug Era, but worse, because it was in everything. YAML, like Perl, is easy to read, but hard to reason about; and that makes it a hazard. These days, we have YAML libs and practices we regard as known-good, but I still trust it about as much as I trust \.doc(x?) or \.pdf, or some weird execv() involving ImageMagick. It's unclean. Sorry, not sorry.

KDL is solid and I'm a fan.

I would like to see a document format based on s-expr catch on. I briefly worked on one[1] just enough for it to support the features needed for another project.

Two things I particularly enjoy:

- Self-closing blocks.

- Easy parsing.

[1] https://github.com/s-i-e-v-e/sxml

Does it support multilevel properties (ie. properties about properties)? What I mean is something like this

    rome name="Rome" founded="753BC"(source=foobar) {
        child ...
    }

What's the use case of this? It's for configs, documents or what?

I think anything you would normally write a schema for, and edit by hand. It does actually come with a schema language too, embedded in KDL, based on JSON-schema. I think it would be a great syntax for something like CSL (Citation Style Language, something I work with); not a document, no actual content, but free-flowing, recursive, needs a schema, and is edited by non-programmers. There's a lot of talk in CSL-land about graphical editors because XML is just too hard, but graphical editors are also too much effort to build. Someone once suggested based on general facts (lighter, etc) about JSON that CSL should switch input language to JSON -- that would have been a disaster, JSON is terrible for this. (And the CSL project wouldn't change its spec dramatically and unnecessarily.) But KDL seems good for that kind of thing.

Unfortunately I don't quite see it as a replacement for Jsonnet (or Dhall, etc) in terms of writing extremely laborious Kubernetes/Terraform/etc config by hand. It doesn't seem very easy to embed a functional KDL-generating language in KDL. I sat down and tried to imagine what this would be like and couldn't make it connect. Maybe someone else can give this a shot, there are devops folks out there that need saving from YAML. Part of the problem for KDL as a replacement for these is that its mapping to JSON/YAML is a bit awkward, whereas XML is actually pretty close. That's presumably why Kat called it their Document Language. So I expect if it catches on it will be in greenfield projects or XML revamps.

This is also close enough to GraphQL that it could replace it.

The only syntactic difference I see with GraphQL is the lack of parenthesis around arguments and the existence of anonymous arguments.

It's pretty close to HashCorp's HCL, actually.

Go for it KDL, I really want a better standard for this. Anyone with some dev experience has done the XML => Json => Yaml => “screw it I’ll do my own” cycle.

It’s painful to go through.

Yeah. What's next to follow? The whole format ecosystem - only KDL, i.e. all the equivalents of XPath, XSLT, XQuery, XML Schema, libraries, and modern re-envision of other tools such as jq and JMESPath...

Honest question: are there document languages for ticket systems and/or process/project plans? like gant diagrams? no tex code, but real DSLs?

this looks interesting

If I've got you right, then https://plantuml.com/en/gantt-diagram

Is this related to https://kaitai.io/?

Why ever allow non-property text in a node? Isn't this an example of needless complexity?

> The language is based on SDLang

Aha, cute pun! :)

and the lang itself looks quite nice tbh

Refenrecing the site “What about HOCON?”

Obligatory xkcd: https://xkcd.com/927/

Also yes, I'm aware the author states:

>Have you seen that one XKCD comic about standards?

>Yes. I have. Please stop linking me to it.

To which I say: You shouldn't have created a new standard if you didn't want to be linked to the xkcd. Any annoyance is self inflicted, and you've weaponized the internet against yourself.

This isn't a unifying standard, which is what the XKCD comic is about. It's not attempting to take other standards and develop the One To Rule Them All—you know, like the first panel of the comic describes—but rather building a different tool that's a better fit for some specific use-cases.

Honestly, if the internet had been around when the screwdriver was invented, the Hacker News commenters of the time would have been linking to XKCD 927 along with snide comments about how hammers and wrenches already exist.

"A wheel? Don't be silly, how are you going to add wheels to a horse?" (Prehistoric HN commenter)

Hammers, wrenches!

Rolls eyes.

Screwdrivers scale!

Screwdrivers are scalable, idempotent and functional.

Can't believe you are serving 100 villagers with hammers. Hammers make everything look like a nail. And it's impossible to make comments with wrenches.

I'd love to understand why all the advertised implementations have permissive licenses except for the Rust implementation, which is released under the Parity Public License 7.0.0 [1]? This seems to be as restrictive as the GPL, no?

In my mind, copyleft licenses applied to infrastructural projects like kdl-rs prematurely limits their adoption and promotes the development of alternatives with more permissive licensing, since the spec is released under a Creative Commons license [2].

[1]: https://github.com/kdl-org/kdl-rs/blob/87f836134c1d901ff5ce6...

[2]: https://github.com/kdl-org/kdl/blob/785abebfc507ff6b7bdeac07...

Reply on news.ycombinator.com