mirror of https://github.com/kdl-org/kdl.git
Add schema specs for info and definitions (#120)
Fixes: https://github.com/kdl-org/kdl/issues/113
This commit is contained in:
Lars Willighagen
GitHub
parent
7c54aae64f
commit
80dec07c37
137
SCHEMA-SPEC.md
137
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.
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue