Proposed extensions to the schema specification

[larsgw]

1. A top-level metadata (or info) node. Authors, title/description, URLs (documentation, persistent self-URL for linked data), publication dates and version information.
2. A top-level definitions node. In the example schema, the props description, ref and id are shared among various nodes throughout the documentation. To remove the duplication one could give the first definition an id and ref it in other places but the first definition is not necessarily the most natural place to put it. A definitions node could house node, prop, value and children nodes.

(Edit: I see there are description props already on document, but I think more metadata is still helpful. The same goes for schema-url if it's a reference to the current schema; if it's a reference to the schema schema, like an XML namespace, then a top-level schema node to contain metadata, definitions and document might be good too.)

[zkat]

I like both of these ideas and will gladly take PRs for them!!

[larsgw]

It might depend on experience but I think I would personally be more drawn to the metadata section to see the description than the first line (especially coming from XML and HTML).

[zkat]

I'm more inclined to put everything inside document:

document {
    metadata {
        ...
    }
    definitions {
        ...
    }
    other-nodes-allowed true
    node "document" { ... }
}

[larsgw]

I like having a node for the KDL document root, especially since it can contain multiple node nodes (and those shouldn't have a other-nodes-allowed or metadata in between). The other things also all say something about the schema: what it is (metadata), how it should be applied (other-nodes-allowed etc.). In my opinion that is distinct from document, which directly says something about the files that the schema should be applied to (that is how I interpreted it at least). I am not entirely sure where definitions fits in this though.

[zkat]

what you're using as schema is literally what document is meant to be, though. The document node can be renamed to schema and we'd basically have the same behavior.

[larsgw]

Ah, okay. My bad.

[zkat]

I'm converting this to an issue because I want to make sure it's resolved for #112