kdl-in-json

[shimeoki]

nixpkgs maintainers are adding a writer for kdl from nix code: NixOS/nixpkgs#426828

to achieve that, they defined a specific syntax for arbitrary kdl documents. nix attribute sets are essentially json values, so after that they convert the nix attrset to json and finally this json to kdl.

if i understood correctly, then they use a schema like this:

// node
{
	"type": "type", // or null
	"name": "name",
	"arguments": [
		// just values
	],
	"properties": {
		// object with string names as keys and values as... values
	},
	"children": [
		// nested nodes
	],
}

// value is a string, number, boolean, null, or this object:
{
	"type": "type", // annotation like in a node
	"value": "value", // as described above
}

however, there is a kdl-test repository, that already defines a schema.

they are pretty similar, but in kdl-test:

• arguments are args and properties are props
• type annotations are required even if there are no annotations, but the value in this case is null
• all actual values are stored as strings and to know the real type an additional type context is used

method used in nixpkgs to store values as-is leads to this. long story short, storing actual numbers instead of their string format is able to cause many problems (in specific nix case there are more problems, but it's out of topic).

because kdl-test is a part of kdl-org and almost the same format was introduced in parallel from at least two places (nixpkgs and kdl-test), i think it should be defined as an official standard to avoid two of them. the pr in nixpkgs is not merged yet (and still a draft), so there is time.

analogous to json-in-kdl, it probably should be named kdl-in-json. the short form is kinda bad (KiJ), but whatever. maybe there are other variations, that's just my initial discussion idea.

i think just making kdl-test specification official in the current form is fine, but maybe some changes are desirable:

1. use nodes instead of children. it is shorter, and tells about the data type: a single element in nodes is a node.

2. instead of a separate value type (not annotation) null just is a null as the whole object. e.g. "prop": { "type": null, "value": null } instead of "prop": { "type": null, "value": { "type": "null" } }. otherwise the schema requires that the value field is optional.

3. either rename type like string or number for actual values to kind, or rename type for annotations to anno to avoid confusion between these two fields. i like the latter more, because the specification says that "annotations further clarify its type", so type should actually be used for the value type and anno clarifies it.

4. the decision to convert all numbers to, essentially, floats (decimals) is probably the best solution to numbers. not hex/octal/binary, and keywords are kept as-is. however, maybe it's still worth it to discuss.

if it gets the green light, then i can create a pr with the specification. if there are no objections, then i also want to incorporate the first three aforementioned points. however, i have no experience in writing json schema specifications, and i don't want to give guarantees about the deadline (i hope a few weeks at most).