The KDL Schema specification describes a schema language for use with KDL, written in KDL itself. A schema language allows users to describe and constrain the allowed semantics of a KDL document. This can be used for many purposes: documentation for users, automated verification, or even automated generation of bindings!
This document describes KDL Schema version 1.0.0
. It was released on September 11, 2021.
For the full KDL Schema schema itself, see examples/kdl-schema.kdl.
This is the toplevel node in a KDL Schema. It is required, and there must be exactly one, at the very toplevel of a document.
None.
None.
info
- one info node for that describes the schema itself.node
- zero or more toplevel nodes for the KDL document this schema describes.definitions
(optional): Definitions of nodes, values, props, and children block to reference in the toplevel nodes.node-names
(optional): Validations 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
- zero or more toplevel tags for nodes in the KDL document that this schema describes.tag-names
(optional): Validations 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
.
The info
node describes the schema itself.
None.
None.
title
(optional): zero or more titlesdescription
(optional): zero or more descriptionsauthor
(optional): zero or more authorscontributor
(optional): zero or more contributorslink
(optional): zero or more URLslicense
(optional): zero or more licensespublished
(optional): a publication datemodified
(optional): a modification dateversion
(optional): a SemVer version number
The title of the schema or the format it describes.
- Title
lang
(optional): An IETF BCP 47 language tag
A description of the schema or the format it describes.
- Description
lang
(optional): An IETF BCP 47 language tag
Author(s) of the schema.
- Author name
orcid
(optional): The ORCID of the author.
link
(optional): zero or more URLs
Links to the schema itself, and to sources about the schema.
- URI/IRI - A URI/IRI that the link points to
rel
: what the link is for (self
ordocumentation
)lang
(optional): An IETF BCP 47 language tag
The license(s) that the schema is licensed under.
- License name - Name of the used license
spdx
(optional): an SPDX license identifier
link
: one or more URLs
When the schema was published or last modified respectively.
- Publication or modification date - As a ISO8601 date
time
(optional): an ISO8601 Time to accompany the date
The version number of this version of the schema.
- Version - Semver version specification
The node
node describes node instances in a document. These may either be at
the toplevel of the document, or they may be nested inside a children block in
another node.
- Node name (optional) - A string name for the node. If present, the node's rules/validations will apply only to children with this node name. Otherwise, the rules will apply to all child nodes, regardless of whether they're named or not.
description
(optional): An informational description of the purpose of this node.id
(optional): A globally unique identifier for this node.ref
(optional): A KDL Query string relative to the root of the document. If present, all properties, values, and children defined in the target node will be copied to this node, replacing any conflicts.
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 to apply to the names of properties.other-props-allowed
(optional): Whether to allow props other than the ones explicitly listed here. Defaults tofalse
.tag
: Validations to apply to the tag of the node.prop
- zero or more properties for this node.value
- zero or more values for this node.children
- zero or more children for this node.
The tag
describes the tags allowed in a children block or toplevel document.
- 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.
description
(optional): An informational description of the purpose of this node.id
(optional): A globally unique identifier for this node.ref
(optional): A KDL Query string relative to the root of the document. If present, all properties, values, and children defined in the target node will be copied to this node, replacing any conflicts.
node
- zero or more toplevel nodes that this tag is allowed to be on.node-names
(optional): Validations 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 tofalse
.
Represents a property of a node, which is a key/value pair in KDL.
key
(optional) - String key for the property. If this value is missing, theprop
node's attributes will apply to all properties of its parent.
description
(optional): An informational description of the purpose of this property.id
(optional): A globally unique identifier for this property.ref
(optional): A KDL Query string relative to the root of the document. If present, all properties defined in the target property will be copied to this property, replacing any conflicts.
required
(optional): A boolean value indicating whether this property is required.- Any validation node.
Used to describe one or more values for a KDL node.
None.
description
(optional): An informational description of the purpose of this value.id
(optional): A globally unique identifier for this value.ref
(optional): A KDL Query string relative to the root of the document. If present, all values defined in the target value will be copied to this value, replacing any conflicts.
min
(optional): Minimum number of values allowed.max
(optional): Maximum number of values allowed.- Any validation node.
Denotes KDL node children.
None.
description
(optional): An informational description of the purpose of this children block.id
(optional): A globally unique identifier for this children block.ref
(optional): A KDL Query string relative to the root of the document. If present, all children defined in the target children block will be copied to this children block, replacing any conflicts.
node
- zero or more child nodes.node-names
(optional): Validations to apply to the names of child nodes.other-nodes-allowed
(optional): Whether to allow nodes other than the ones explicitly listed here. Defaults tofalse
.
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.
tag
: Validations 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 thetype
, if specified.
pattern
: Regex pattern or patterns to test prop values against. Specific regex syntax may be implementation-dependent.min-length
: Minimum length, if a string.max-length
: Maximum length, if a string.format
: Intended data format, if the value is a string. Reserved values are:date-time
: ISO8601 date/time format.time
: "Time" section of ISO8601.date
: "Date" section of ISO8601.duration
: ISO8601 duration format.decimal
: IEEE 754-2008 decimal string format.currency
: ISO 4217 currency code.country-2
: ISO 3166-1 alpha-2 country code.country-3
: ISO 3166-1 alpha-3 country code.country-subdivision
: ISO 3166-2 country subdivision code.email
: RFC5302 email address.idn-email
: RFC6531 internationalized email address.hostname
: RFC1132 internet hostname.idn-hostname
: RFC5890 internationalized internet hostname.ipv4
: RFC2673 dotted-quad IPv4 address.ipv6
: RFC2373 IPv6 address.url
: RFC3986 URI.url-reference
: RFC3986 URI Reference.irl
: RFC3987 Internationalized Resource Identifier.irl-reference
: RFC3987 Internationalized Resource Identifier Reference.url-template
: RFC6570 URI Template.uuid
: RFC4122 UUID.regex
: Regular expression. Specific patterns may be implementation-dependent.base64
: A Base64-encoded string, denoting arbitrary binary data.kdl-query
: A KDL Query string.
%
: 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.format
: Intended data format for numeric values. Reserved values are:i8
: 8-bit signed integeri16
: 16-bit signed integeri32
: 32-bit signed integeri64
: 64-bit signed integeru8
: 8-bit unsigned integeru16
: 16-bit unsigned integeru32
: 32-bit unsigned integeru64
: 64-bit unsigned integerisize
: Platform-dependent signed integerusize
: Platform-dependent unsigned integerf32
: IEEE 754 single (32-bit) precision floating point numberf64
: IEEE 754 double (64-bit) precision floating point numberdecimal64
: IEEE 754-2008 64-bit decimal floating point numberdecimal128
: IEEE 754-2008 128-bit decimal floating point number
Definitions to reference in parts of the top-level node
s.
None.
None.