From 7a89c3003a6bead5dcdd7cd8dcf628d2b9b2cf82 Mon Sep 17 00:00:00 2001 From: Lars Willighagen Date: Thu, 9 Sep 2021 11:42:44 +0200 Subject: [PATCH] draft Schema spec for node and value tags --- SCHEMA-SPEC.md | 26 ++++++++++++++++++++++++++ examples/kdl-schema.kdl | 41 +++++++++++++++++++++++++++++++++++++++-- 2 files changed, 65 insertions(+), 2 deletions(-) diff --git a/SCHEMA-SPEC.md b/SCHEMA-SPEC.md index 6a6e20d..05c0965 100644 --- a/SCHEMA-SPEC.md +++ b/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. diff --git a/examples/kdl-schema.kdl b/examples/kdl-schema.kdl index b514b39..d398cd1 100644 --- a/examples/kdl-schema.kdl +++ b/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" } } }