Clarification on type annotation usage

[tryoxiss]

In KDL, type annotations like (u8)122 make sense, but the specification uses some examples that seem backwards, like (published)date. Seems odd, as the field should be published! Even weirder when you consider that date is a defined type in KDL, so why not (date)published? It makes more sense to do that, since its a "published" field, that should be interprited as a date. Because of that it also seems inconsistant in examples when its used as more of a key with the node name indicating type, or when the node name indicates key and the annotation indicates type.

Can someone explain why it is done this way? Or, if there isn't a good reason, maybe the semantics should be changed for KDL 2?

[tabatkins]

Annotations on values have well-defined meaning; the value holds the "value" and the annotation gives "type" information. We've got a lot of built-in value annotations that enforce this meaning.

But KDL intentionally does not assign meaning to annotations on nodes. Partly this is because nodes are much more free-form than individual values, but it's also partly because the semantics can reasonably be different. Node names usually indicate the "type" of the node (this is the main benefit of a node-based language, after all, over the anonymous-object model of JSON), with the attribute/properties/children forming the "value". The annotation, then, isn't needed to indicate the type, and is free to be used to indicate other information.

In particular, the usage you're noting is giving the child list, which is otherwise purely an indexed list of values akin to a node's attributes, the ability to act like a key/value list, akin to a node's properties. In other words, node published=(date)"2020-01-01" and node { (published)date "2020-01-01"; } are expressing similar data structures, in the same way that node (date)"2020-01-01" and node { date "2020-01-01"; } do.

Such an example could be written in other ways, of course; for example, node { date published "2020-01-01"; } would also be perfectly reasonable, indicating the extra information in an attribute.

[tabatkins]

You are saying that the node indicates the type, but then what pourpose do the annotations have?

Per the spec: "a suggestion of what type the value is intended to be treated as, or as a context-specific elaboration of the more generic type the node name indicates".

KDL values come in four generic types, indicated by syntax - strings, numbers, bools, or null. The annotation indicates a more specific type. KDL nodes come in an infinity of types, depending on the application, indicated by the node name. The annotation similarly indicates an even more specific type.

So is (published)date "2024-01-01" equivalent to (published)date (date)"2024-01-01"?

It could be. It depends on how the application chooses to interpret the config file. It might know that date nodes always have their first attribute as a date string, so it's not required to annotate that fact explicitly. Or it might require the annotation because there's flexibility in how the node works, and having an annotated date string works differently than having something else.

Similarly, one could forgo annotations altogether and just have a more specific node name, like published-date "2024-01-01". What is best depends on what you are trying to do, and what makes your files the most readable and understandable. Having very specific node names is often the right thing, but there are contexts where you might be intentionally using a predefined vocabulary with specific, meaningful node names, and thus would want to use an annotation to convey more specific information.

The website mentions the semantics are clearly defined but I am unable to find any definitions of them, even after reading the entire spec.

What text are you referring to? The only mention of "semantics" on the homepage is in the opening paragraphs, mentioning that KDL has "XML-like semantics". In the spec itself, generic semantics are defined, such as "argument order matters", "child order matters", "property order doesn't matter". This is important for guiding implementations in their data structure choice for representing KDL, and for encourage languages built on KDL to rely on specific aspects.

Annotations are intentionally not given meaning, but a set of value annotations are reserved by the language and given suggested semantics. All other annotations (value or node) are entirely defined by the host language built on top of KDL, tho.

I know in XML/HTML its not really super clear how something should be implemented, and its always felt abitrary that its

Yes, it is arbitrary, and it's just plain bad design. But that's not the fault of the XML/HTML syntax, it's a design flaw in the HTML language built on top of the syntax - it exists just the same if you're writing HTML in KDL (meta rel=stylesheet href="foo"; style src="foo";), or in JSON (["meta", {"rel":"stylesheet", "href":"foo"}] ["style", {"src":"foo"}]) , or whatever. All of them allow bad languages to be defined on top of them, because they're just the carriers of the semantics; they don't have semantics themselves beyond the most trivial sense.

[tabatkins]

Oh, and:

(invalid according to kdl play) node { date published "2020-01-01"; }

That's valid KDL2 - it uses an ident string in a value position, which is only allowed in KDL1 for node names, property names, and annotations. KDL2 consistently allows that type of string everywhere.

[tryoxiss]

Per the spec: "a suggestion of what type the value is intended to be treated as, or as a context-specific elaboration of the more generic type the node name indicates".

KDL values come in four generic types, indicated by syntax - strings, numbers, bools, or null. The annotation indicates a more specific type. KDL nodes come in an infinity of types, depending on the application, indicated by the node name. The annotation similarly indicates an even more specific type.

Ahh, that makes sense. Thank you!

So is (published)date "2024-01-01" equivalent to (published)date (date)"2024-01-01"?

It could be. It depends on how the application chooses to interpret the config file. It might know that date nodes always have their first attribute as a date string, so it's not required to annotate that fact explicitly. Or it might require the annotation because there's flexibility in how the node works, and having an annotated date string works differently than having something else.

Similarly, one could forgo annotations altogether and just have a more specific node name, like published-date "2024-01-01". What is best depends on what you are trying to do, and what makes your files the most readable and understandable. Having very specific node names is often the right thing, but there are contexts where you might be intentionally using a predefined vocabulary with specific, meaningful node names, and thus would want to use an annotation to convey more specific information.

That makes sense, thank you. I've always leaned towards specific node names but that is a good reason to want to use less specific and elaborate with an annotation, I just didnt see the point before.

The website mentions the semantics are clearly defined but I am unable to find any definitions of them, even after reading the entire spec.

What text are you referring to? The only mention of "semantics" on the homepage is in the opening paragraphs, mentioning that KDL has "XML-like semantics".

https://kdl.dev/ -> "Ok, then why not SDLang?" -> Bullet 1 reads "The grammar and expected semantics are well-defined and specified.", which links to the spec but it does not touch on semantics that much.

In the spec itself, generic semantics are defined, such as "argument order matters", "child order matters", "property order doesn't matter". This is important for guiding implementations in their data structure choice for representing KDL, and for encourage languages built on KDL to rely on specific aspects.

Ahh, I would consider that more syntax than semantics but I could see that being the case.

Annotations are intentionally not given meaning, but a set of value annotations are reserved by the language and given suggested semantics. All other annotations (value or node) are entirely defined by the host language built on top of KDL, tho.

Good to know :3

I know in XML/HTML its not really super clear how something should be implemented, and its always felt abitrary that its

Yes, it is arbitrary, and it's just plain bad design. But that's not the fault of the XML/HTML syntax, it's a design flaw in the HTML language built on top of the syntax - it exists just the same if you're writing HTML in KDL (meta rel=stylesheet href="foo"; style src="foo";), or in JSON (["meta", {"rel":"stylesheet", "href":"foo"}] ["style", {"src":"foo"}]) , or whatever. All of them allow bad languages to be defined on top of them, because they're just the carriers of the semantics; they don't have semantics themselves beyond the most trivial sense.

That makes sense, though I still feel it could have been prevented by having a more baseline set of expected useages for languages built on top of them, but I can see why that would be out of scope. Though even that wouldn't have saved HTML, as HTML is not an xml schemea its an independent language weirdly.

---

Thank you for your time <3 , I think I understand now? To summarize:

• In the case of values, annotations just indicate how something is meant to be read like a time, date, datetime, etc.
• In the case of nodes, annotations are useful when using a predefined grammer that you want to elaborate on. When creating a schemea it is better to use specific node names.
• KDL is both a config, but is also indended to be used as just a syntax that domain-specific languages can be built on.

[tryoxiss]

Ahh that makes sense. I saw a thread for that but I thought it was just a proposal and not part of the spec yet though, I havent really been following it so your probably right.

[tabatkins]

KDL is both a config, but is also indended to be used as just a syntax that domain-specific languages can be built on.

All config files are (usually ad-hoc) domain-specific languages, but yes. ^_^ Your understanding is correct.