diff --git a/SCHEMA-SPEC.md b/SCHEMA-SPEC.md index cc4700b..801fe4b 100644 --- a/SCHEMA-SPEC.md +++ b/SCHEMA-SPEC.md @@ -24,15 +24,129 @@ None. #### Properties -* `description` (optional): An informational description of the purpose of this schema. -* `schema-url` (optional): A URL where someone may go to find more information about this schema. It is not meant for mechanical processing. +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) (optional): zero or more titles +* [`description`](#description-node) (optional): zero or more descriptions +* [`author`](#author-and-contributor-nodes) (optional): zero 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](https://semver.org/) 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 + +* URI/IRI - A URI/IRI that the link points to + +#### Properties + +* `rel`: what the link 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 +274,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..b514b39 100644 --- a/examples/kdl-schema.kdl +++ b/examples/kdl-schema.kdl @@ -1,13 +1,23 @@ -document description="KDL Schema KDL schema in KDL" schema-url="https://github.com/zkat/kdl" { +document { + info { + title "KDL Schema" lang="en" + description "KDL Schema KDL schema in KDL" lang="en" + author "Kat Marchán" { + link "https://github.com/zkat" rel="self" + } + contributor "Lars Willighagen" { + link "https://github.com/larsgw" rel="self" + } + link https://github.com/zkat/kdl rel="documentation" + license "Creative Commons Attribution-ShareAlike 4.0 International License" spdx="CC-BY-SA-4.0" { + link "https://creativecommons.org/licenses/by-sa/4.0/" lang="en" + } + published "2021-08-31" + modified "2021-09-01" + } node "document" { min 1 max 1 - prop "schema-url" description="URL where you can find this schema. Informational only." { - type "url" - } - prop "description" description="General purpose and description for this document schema." { - type "string" - } children id="node-children" { node "node-names" description="Validations to apply specifically to arbitrary node names" { children ref="#validations" @@ -20,7 +30,102 @@ 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" { + 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" { + 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" + format "uri" "iri" + 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 +167,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 +274,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 +304,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 +318,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" + } + } } } }