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.
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.
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).
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.