add schema specs for info and definitions

Fix https://github.com/kdl-org/kdl/issues/113
2021-09-01 12:30:26 +02:00 · 2021-09-01 12:30:26 +02:00 · 522a647a26
parent 7c54aae64f
commit 522a647a26
2 changed files with 242 additions and 4 deletions
--- 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.
--- 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"
+                }
+            }
        }
    }
 }