Property Annotation

[dezren39]

Allow annotating properties in the same way that values and identifiers can be annotated.

[dezren39]

at least one implementation seems to have already implemented this

• https://pkg.go.dev/github.com/lunjon/gokdl#Prop

type Prop struct {
	Name  [string](https://pkg.go.dev/builtin#string)
	Value [any](https://pkg.go.dev/builtin#any)
	// ValueTypeAnnot is the type annotation for the value of the property.
	// Example: age=(u8)25
	// In this case it would be "u8".
	ValueTypeAnnot [TypeAnnotation](https://pkg.go.dev/github.com/lunjon/gokdl#TypeAnnotation)
	// TypeAnnot is the type annotation for the property itself.
	// Example: (author)name="Jonathan"
	TypeAnnot [TypeAnnotation](https://pkg.go.dev/github.com/lunjon/gokdl#TypeAnnotation)
}

[IceDragon200]

Kuddle supports property annotations (even in v1, which was a side effect of using the same Value struct for keys and values)

defmodule Kuddle.Node do
  alias Kuddle.Value

  defstruct [
    name: nil,
    annotations: [],
    attributes: [],
    children: nil,
  ]

  @typedoc """
  An attribute is either a property `{key, value}`, or just a plain value.
  """
  @type attribute :: {key::Value.t(), value::Value.t()} | Value.t()

  @type t :: %__MODULE__{
    name: String.t(),
    annotations: [String.t()],
    attributes: [attribute()],
    children: [t()] | nil
  }
end

defmodule Kuddle.Value do
  defstruct [
    value: nil,
    annotations: [],
    type: :id,
    format: :plain,
  ]
end

// This is legal in kuddle, but not to spec
(ntype)node (ktype)key=(vtype)"Something" 

I'd agree, allowing annotations on property keys should be fine, I can't think of a reason why it shouldn't be allowed.

[tabatkins]

I've got no particular problem with annotations on keys (they're trivial to parse, tho they do present some data-model complexities), but I do question their value. Key annotations would be similar to node annotations, rather than value annotations - they'll provide some additional context to the node/key, rather than telling you what kind of data is in the value. This is useful for nodes, because you can have multiple nodes with the same node name in a single child list, which are meant to provide different things (say, an (author)person ... vs a (reviewer)person ...).

But key names have to be unique on a node already, so all necessary context is already baked in to their name. And the property's value can carry its own annotation when necessary.

So what is an actual use-case for a property key annotation?

[tabatkins]

Hm, can you elaborate on why you think (review)type=in-person is reasonable to write, but review-type=in-person isn't? Is the expectation that sometimes people will just write type=in-person, but they'll provide the tag if they wanna, I guess, comment it for themselves to make it more readable?

[dezren39]

basically, yeah. i would argue there's no reason to restrict it, and it can be useful for specific kinds of documents.

[tabatkins]

I generally disagree with that - we shouldn't be giving tools that don't actually do anything meaningful. While value annotations are well-justified, node annotations are already on much shakier ground, and that's with a few use-cases. If key annotations don't actually do anything meaningful, then we shouldn't add them, as they just become an attractive nuisance to users of the language. People will figure that, since they exist, there must be some use for them, and end up doing weird things just because they're available.

[IceDragon200]

@tabatkins After rewriting my reply around seven times, I decided to take a break and re-read the spec to understand your stance, and I hope by explaining that here, dezren39 can also understand why.

Annotations

Or rather Type Annotations, while the spec makes lax assumptions about how these values should be interpreted, it is clear they are meant to represent some kind of data type, not so much as "tagging" as I had initially treated it, nothing is stopping anyone from using it for tagging however.

But its primary use is to denote the "type" of the item it is annotating (node or value), by that, I now understand why you said this:

While value annotations are well-justified, node annotations are already on much shakier ground, and that's with a few use-cases.

And to that, I present:

node a b c
(list)node2 d

That's a node annotation used to inform the configuration that the attributes of the node should be treated as a list of items, for context kuddle_config by default treats single arguments as immediate key value pairs:

[
  node: ["a", "b", "c"],
  node2: ["d"]
]

Without the node annotation telling it to treat the second node as a list, it would be this:

[
  node: ["a", "b", "c"],
  node2: "d"
]

You could argue: the value should have that annotation instead, except, in elixir a string > list is an actual operation that implies a charlist:

node a b c
node2 (list)d

[
  node: ["a", "b", "c"],
  node2: 'd' # or [100]
]

That justifies node annotations at least.

Properties

The one thing I had completely overlooked is how restrictive property keys are, since they only allow strings (bare IDs or quoted effectively), which makes this invalid:

node 1=2 3=4

However, there is a valid case for property annotations now:

// This is a data_coding table for SMPP, the intention is to recode the left (key) to the right (value)
// In other words:
// GSM7 / Default, ASCII, and Latin 1 to UCS2 (UTF16)
recode (u32)"0"=8 (u32)"1"=8 (u32)"3"=8

This would have been better if properties allowed ANY value for its keys:

recode 0=8 1=8 3=8

[tabatkins]

they are meant to represent some kind of data type,

Right. Value annotations denote the value's type, with more precision than what you can get from just the syntax. Node annotations, well, can denote a type, but usually the node name will denote the type already, and so the node annotation instead serves as a key distinguishing it from other siblings of the same name. Thus examples like (author)person ... vs (reviewer)person .... There are indeed example of using node annotations to denote types, of course; you gave one, and the official JiK syntax uses it as well to annotate ambiguous arrays or objects.

(Generally, values won't need this sort of "role" annotation, because you'd just make them properties in that case. The only remaining hole in the functionality is you can't tag multiple values with the same role, like you can nodes, unless you forgo using "type" annotations for them; but at that point the suggestion is to move to child nodes anyway.)

However, there is a valid case for property annotations now:

That example requires your data model to be very specific, re-casting properties as simple pairs where the first value is required to be a string. It's arguable a minor abuse of KDL syntax, tho of course KDL is a tool that you can use however you find useful. I wouldn't want to change the language to support that kind of usage, however.