diff --git a/SCHEMA-SPEC.md b/SCHEMA-SPEC.md index bee260c..51d3719 100644 --- a/SCHEMA-SPEC.md +++ b/SCHEMA-SPEC.md @@ -30,6 +30,8 @@ None. #### Children * [`node`](#node-node) - zero or more toplevel nodes for the KDL document this schema describes. +* `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`. ### `node` node @@ -51,6 +53,8 @@ another node. * `min` (optional): Minimum number of this kind of node (or any node, if the name is missing) allowed in the parent's children block. * `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`. * [`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. @@ -71,9 +75,8 @@ Represents a property of a node, which is a key/value pair in KDL. #### Children -* `type` (optional): A string denoting the type of the property value. -* `enum` (optional): A specific list of allowed values for this property. May be heterogenous as long as it agrees with the `type`, if specified. * `required` (optional): A boolean value indicating whether this property is required. +* Any [validation node](#validation-nodes). ### `value` node @@ -91,10 +94,9 @@ None. #### Children -* `type` (optional): A string denoting the type of the value. -* `enum` (optional): A specific list of allowed values for this value. May be heterogenous as long as it agrees with the `type`, if specified. * `min` (optional): Minimum number of values allowed. * `max` (optional): Maximum number of values allowed. +* Any [validation node](#validation-nodes). ### `children` node @@ -113,3 +115,31 @@ None. #### Children * [`node`](#node-node) - zero or more child 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`. + +### Validation Nodes + +The following nodes are shared validations between props and values, and can +be used as children to either definition. They are also used to verify node +and property names when the `node-names` or `prop-names` options are activated. + +#### Generic validations + +* `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. + +#### String validations + +* `pattern`: PCRE (Regex) pattern or patterns to test prop values against. +* `min-length`: Minimum length, if a string. +* `max-length`: Maximum length, if a string. +* `format`: Intended data format, if the value is a string. + +#### Number validations + +* `%`: Only used for numeric values. Constrains them to be multiples of the given number(s). +* `>`: Greater than. +* `>=`: Greater than or equal to. +* `<`: Less than. +* `<=`: Less than or equal to. diff --git a/examples/kdl-schema.kdl b/examples/kdl-schema.kdl index dede887..3e5c919 100644 --- a/examples/kdl-schema.kdl +++ b/examples/kdl-schema.kdl @@ -9,6 +9,17 @@ document description="KDL Schema KDL schema in KDL" schema-url="https://github.c type "string" } children id="node-children" { + node "node-names" 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'." { + max 1 + value { + min 1 + max 1 + type "boolean" + } + } 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" @@ -24,15 +35,10 @@ document description="KDL Schema KDL schema in KDL" schema-url="https://github.c type "string" } children { - node "other-properties-allowed" description="Whether to allow properties other than the ones explicitly listed. Defaults to 'false'." { - max 1 - value { - min 1 - max 1 - type "boolean" - } + node "prop-names" description="Validations to apply specifically to arbitrary property names" { + children ref="#validations" } - node "other-children-allowed" description="Whether to allow child nodes other than the ones explicitly listed. Defaults to 'false'." { + node "other-props-allowed" description="Whether to allow properties other than the ones explicitly listed. Defaults to 'false'." { max 1 value { min 1 @@ -78,9 +84,6 @@ document description="KDL Schema KDL schema in KDL" schema-url="https://github.c type "boolean" } } - node "property-names" description="Validations to apply specifically to arbitrary node names" { - children ref="#validations" - } } children id="validations" description="General value validations." { node "type" description="The type for this prop's value." { @@ -96,14 +99,6 @@ document description="KDL Schema KDL schema in KDL" schema-url="https://github.c min 1 } } - node "required" description="Whether this property is required if its parent is present." { - max 1 - value { - min 1 - max 1 - type "boolean" - } - } node "pattern" description="PCRE (Regex) pattern or patterns to test prop values against." { value { min 1 @@ -133,14 +128,14 @@ document description="KDL Schema KDL schema in KDL" schema-url="https://github.c enum "date-time" "date" "time" "email" "idn-email" "hostname" "ipv4" "ipv6" "uri" "uri-reference" "iri", "iri-reference" "uri-template" "kdl-pointer" "relative-kdl-pointer" "regex" "uuid" } } - node "multiple-of" description="Only used for numeric values. Constrains them to be multiples of the given number(s)" { + node "%" description="Only used for numeric values. Constrains them to be multiples of the given number(s)" { max 1 value { min 1 type "number" } } - node "gt" description="Only used for numeric values. Constrains them to be greater than the given number(s)" { + node ">" description="Only used for numeric values. Constrains them to be greater than the given number(s)" { max 1 value { min 1 @@ -148,7 +143,7 @@ document description="KDL Schema KDL schema in KDL" schema-url="https://github.c type "number" } } - node "gte" description="Only used for numeric values. Constrains them to be greater than or equal to the given number(s)" { + node ">=" description="Only used for numeric values. Constrains them to be greater than or equal to the given number(s)" { max 1 value { min 1 @@ -156,7 +151,7 @@ document description="KDL Schema KDL schema in KDL" schema-url="https://github.c type "number" } } - node "lt" description="Only used for numeric values. Constrains them to be less than the given number(s)" { + node "<" description="Only used for numeric values. Constrains them to be less than the given number(s)" { max 1 value { min 1 @@ -164,7 +159,7 @@ document description="KDL Schema KDL schema in KDL" schema-url="https://github.c type "number" } } - node "lte" description="Only used for numeric values. Constrains them to be less than or equal to the given number(s)" { + node "<=" description="Only used for numeric values. Constrains them to be less than or equal to the given number(s)" { max 1 value { min 1