berkus
/
kdl
mirror of https://github.com/kdl-org/kdl.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

more validation work, cleanup, and docs

This commit is contained in:
Kat Marchán 2021-08-31 11:23:22 -07:00
parent 8cf9ce0693
commit 1508ee4f13
No known key found for this signature in database
GPG Key ID: AEB529C08A3C7E9E
2 changed files with 53 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
SCHEMA-SPEC.md
View File

@ -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.

43
examples/kdl-schema.kdl
View File

@ -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