diff --git a/SCHEMA-SPEC.md b/SCHEMA-SPEC.md index cc4700b..9264f7e 100644 --- a/SCHEMA-SPEC.md +++ b/SCHEMA-SPEC.md @@ -29,10 +29,125 @@ None. #### Children +* [`info`](#info-node) - one info node for that describes the schema itself. * [`node`](#node-node) - zero or more toplevel nodes for the KDL document this schema describes. +* [`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`. +### `info` node + +The `info` node describes the schema itself. + +#### Values + +None. + +#### Properties + +None. + +#### Children + +* [`title`](#title-node): one or more titles +* [`description`](#description-node) (optional): zero or more descriptions +* [`author`](#author-and-contributor-nodes): one or more authors +* [`contributor`](#author-and-contributor-nodes) (optional): zero or more contributors +* [`link`](#link-node) (optional): zero or more URLs +* [`license`](#license-node) (optional): zero or more licenses +* [`published`](#published-and-modified-nodes) (optional): a publication date +* [`modified`](#published-and-modified-nodes) (optional): a modification date +* [`version`](#version-node) (optional): a (semver) version number + +### `title` node + +The title of the schema or the format it describes. + +#### Values + +* Title + +#### Properties + +* `lang` (optional): An IETF BCP 47 language tag + +### `description` node + +A description of the schema or the format it describes. + +#### Values + +* Description + +#### Properties + +* `lang` (optional): An IETF BCP 47 language tag + +### `author` and `contributor` nodes + +Author(s) of the schema. + +#### Values + +* Author name + +#### Properties + +* `orcid` (optional): The [ORCID](https://orcid.org/) of the author. + +#### Children + +* [`link`](#link-node) (optional): zero or more URLs + +### `link` node + +Links to the schema itself, and to sources about the schema. + +#### Values + +* URL - A URL that the link points to + +#### Properties + +* `rel`: what the URL is for (`"self"` or `"documentation"`) +* `lang` (optional): An IETF BCP 47 language tag + +### `license` node + +The license(s) that the schema is licensed under. + +#### Values + +* License name - Name of the used license + +#### Properties + +* `spdx` (optional): an [SPDX license identifier](https://spdx.dev/ids/) + +#### Children + +* [`link`](#link-node): one or more URLs + +### `published` and `modified` nodes + +When the schema was published or last modified respectively. + +#### Values + +* Publication or modification date - As a ISO8601 date + +#### Properties + +* `time` (optional): an ISO8601 Time to accompany the date + +### `version` nodes + +The version number of this version of the schema. + +#### Values + +* Version - Semver version specification + ### `node` node The `node` node describes node instances in a document. These may either be at @@ -160,3 +275,22 @@ and property names when the `node-names` or `prop-names` options are activated. * `>=`: Greater than or equal to. * `<`: Less than. * `<=`: Less than or equal to. + +### `definitions` node + +Definitions to reference in parts of the top-level `node`s. + +#### Values + +None. + +#### Properties + +None. + +#### Children + +* [`node`](#node-node) - zero or more node definitions. +* [`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 e6c8b59..76d699f 100644 --- a/examples/kdl-schema.kdl +++ b/examples/kdl-schema.kdl @@ -20,7 +20,103 @@ document description="KDL Schema KDL schema in KDL" schema-url="https://github.c type "boolean" } } - node "node" description="A child node belonging either to `document` or to another `node`. Nodes may be anonymous." { + node "info" description="A child node that describes the schema itself." { + children { + node "title" description="The title of the schema or the format it describes" { + min 1 + value description="The title text" { + type "string" + min 1 + max 1 + } + prop "lang" id="info-lang" description="The language of the text" { + type "string" + } + } + node "description" description="A description of the schema or the format it describes" { + value description="The description text" { + type "string" + min 1 + max 1 + } + prop ref="#info-lang" + } + node "author" description="Author of the schema" { + min 1 + value id="info-person-name" description="Person name" { + type "string" + min 1 + max 1 + } + prop "orcid" id="info-orcid" description="The ORCID of the person" { + type "string" + pattern r"\d{4}-\d{4}-\d{4}-\d{4}" + } + children { + node ref="#info-link" + } + } + node "contributor" description="Contributor to the schema" { + value ref="#info-person-name" + prop ref="#info-orcid" + } + node "link" id="info-link" description="Links to itself, and to sources describing it" { + value description="A URL that the link points to" { + type "string" + min 1 + max 1 + } + prop "rel" description="The relation between the current entity and the URL" { + type "string" + enum "self" "documentation" + } + prop ref="#info-lang" + } + node "license" description="The license(s) that the schema is licensed under" { + value description="Name of the used license" { + type "string" + min 1 + max 1 + } + prop "spdx" description="An SPDX license identifier" { + type "string" + } + children { + node ref="#info-link" + } + } + node "published" description="When the schema was published" { + value description="Publication date" { + type "string" + format "date" + min 1 + max 1 + } + prop "time" id="info-time" description="A time to accompany the date" { + type "string" + format "time" + } + } + node "modified" description="When the schema was last modified" { + value description="Modification date" { + type "string" + format "date" + min 1 + max 1 + } + prop ref="#info-time" + } + node "version" description="The version number of this version of the schema" { + value description="Semver version number" { + type "string" + pattern r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$" + min 1 + max 1 + } + } + } + } + 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" max 1 @@ -62,7 +158,7 @@ document description="KDL Schema KDL schema in KDL" schema-url="https://github.c type "number" } } - node "prop" description="A node property key/value pair." { + node "prop" id="prop-node" description="A node property key/value pair." { value description="The property key." { type "string" } @@ -169,7 +265,7 @@ document description="KDL Schema KDL schema in KDL" schema-url="https://github.c } } } - node "value" description="one or more direct node values" { + node "value" id="value-node" description="one or more direct node values" { prop "id" description="A globally-unique ID of this value." { type "string" } @@ -199,7 +295,7 @@ document description="KDL Schema KDL schema in KDL" schema-url="https://github.c } } } - node "children" { + node "children" id="children-node" { prop "id" description="A globally-unique ID of this children node." { type "string" } @@ -213,6 +309,14 @@ document description="KDL Schema KDL schema in KDL" schema-url="https://github.c } } } + node "definitions" description="Definitions to reference in parts of the top-level nodes" { + children { + node ref="#node-node" + node ref="#value-node" + node ref="#prop-node" + node ref="#children-node" + } + } } } }