draft Schema spec for node and value tags

SCHEMA-SPEC.md

@@ -33,6 +33,9 @@ None.
 * [`definitions`](#definitions-node) (optional): Definitions of nodes, values, props, and children block to reference in the toplevel nodes.
 * `node-names` (optional): [Validations](#validation-nodes) to apply to the _names_ of child nodes.
 * `other-nodes-allowed` (optional): Whether to allow nodes other than the ones explicitly listed here. Defaults to `false`.
+* [`tag`](#tag-node) - zero or more toplevel tags for nodes in the KDL document that this schema describes.
+* `tag-names` (optional): [Validations](#validation-nodes) to apply to the _names_ of tags of child nodes.
+* `other-tags-allowed` (optional): Whether to allow node tags other than the ones explicitly listed here. Defaults to `false`.
 
 ### `info` node
 
@@ -169,10 +172,31 @@ another node.
 * `max` (optional): Maximum number of this kind of node (or any node, if the name is missing) allowed in the parent's children block.
 * `prop-names` (optional): [Validations](#validation-nodes) to apply to the _names_ of properties.
 * `other-props-allowed` (optional): Whether to allow props other than the ones explicitly listed here. Defaults to `false`.
+* `tag`: [Validations](#validation-nodes) to apply to the tag of the node. 
 * [`prop`](#prop-node) - zero or more properties for this node.
 * [`value`](#value-node) - zero or more values for this node.
 * [`children`](#children-node) - zero or more children for this node.
 
+### `tag` node
+
+The `tag` describes the tags allowed in a children block or toplevel document.
+
+#### Values
+
+* Tag name (optional) - A tag for the node. If present, the node's rules/validations will apply only to children with this tag. Otherwise, the rules will apply to _all_ child nodes with tags.
+
+#### Properties
+
+* `description` (optional): An informational description of the purpose of this node.
+* `id` (optional): A globally unique identifier for this node.
+* `ref` (optional): A globally unique reference to another node's ID. If present, all properties, values, and children defined in the target node will be copied to this node, replacing any conflicts.
+
+#### Children
+
+* [`node`](#node-node) - zero or more toplevel nodes that this tag is allowed to be on.
+* `node-names` (optional): [Validations](#validation-nodes) to apply to the _names_ of nodes with this tag.
+* `other-nodes-allowed` (optional): Whether to allow nodes other than the ones explicitly listed here. Defaults to `false`.
+
 ### `prop` node
 
 Represents a property of a node, which is a key/value pair in KDL.
@@ -240,6 +264,7 @@ and property names when the `node-names` or `prop-names` options are activated.
 
 #### Generic validations
 
+* `tag`: [Validations](#validation-nodes) to apply to the tag of the value.
 * `type`: A string denoting the type of the property value.
 * `enum`: A specific list of allowed values for this property. May be heterogenous as long as it agrees with the `type`, if specified.
 
@@ -290,6 +315,7 @@ None.
 #### Children
 
 * [`node`](#node-node) - zero or more node definitions.
+* [`tag`](#tag-node) - zero or more toplevel tags for nodes in the KDL document that this schema describes.
 * [`prop`](#prop-node) - zero or more property definitions.
 * [`value`](#value-node) - zero or more value definitions.
 * [`children`](#children-node) - zero or more definitions of children blocks.

examples/kdl-schema.kdl

@@ -19,10 +19,21 @@ document {
         min 1
         max 1
         children id="node-children" {
-            node "node-names" description="Validations to apply specifically to arbitrary node names" {
+            node "node-names" id="node-names-node" description="Validations to apply specifically to arbitrary node names" {
                 children ref="#validations"
             }
-            node "other-nodes-allowed" description="Whether to allow child nodes other than the ones explicitly listed. Defaults to 'false'." {
+            node "other-nodes-allowed" id="other-nodes-allowed-node" description="Whether to allow child nodes other than the ones explicitly listed. Defaults to 'false'." {
+                max 1
+                value {
+                    min 1
+                    max 1
+                    type "boolean"
+                }
+            }
+            node "tag-names" description="Validations to apply specifically to arbitrary type tag names" {
+                children ref="#validations"
+            }
+            node "other-tags-allowed" description="Whether to allow child node tags other than the ones explicitly listed. Defaults to 'false'." {
                 max 1
                 value {
                     min 1
@@ -125,6 +136,26 @@ document {
                     }
                 }
             }
+            node "tag" id="tag-node" description="A tag belonging to a child node of `document` or another node." {
+                value description="The name of the tag. If a tag name is not supplied, the node rules apply to _all_ nodes belonging to the parent." {
+                    type "string"
+                    max 1
+                }
+                prop "description" description="A description of this node's purpose." {
+                    type "string"
+                }
+                prop "id" description="A globally-unique ID for this node." {
+                    type "string"
+                }
+                prop "ref" description="A globally unique reference to another node." {
+                    type "string"
+                }
+                children {
+                    node ref="#node-names-node"
+                    node ref="#other-nodes-allowed-node"
+                    node ref="#node-node"
+                }
+            }
             node "node" id="node-node" description="A child node belonging either to `document` or to another `node`. Nodes may be anonymous." {
                 value description="The name of the node. If a node name is not supplied, the node rules apply to _all_ nodes belonging to the parent." {
                     type "string"
@@ -167,6 +198,7 @@ document {
                             type "number"
                         }
                     }
+                    node ref="#value-tag-node"
                     node "prop" id="prop-node" description="A node property key/value pair." {
                         value description="The property key." {
                             type "string"
@@ -191,6 +223,10 @@ document {
                             }
                         }
                         children id="validations" description="General value validations." {
+                            node "tag" id="value-tag-node" description="The tags associated with this value" {
+                                max 1
+                                children ref="#validations"
+                            }
                             node "type" description="The type for this prop's value." {
                                 max 1
                                 value {
@@ -324,6 +360,7 @@ document {
                     node ref="#value-node"
                     node ref="#prop-node"
                     node ref="#children-node"
+                    node ref="#tag-node"
                 }
             }
         }