From 8c57e08754003101a47a6e74a61abe87ad1caed1 Mon Sep 17 00:00:00 2001 From: Lars Trieloff Date: Wed, 2 May 2018 14:42:30 +0000 Subject: [PATCH 1/5] [trivial] include explanation of abstract and concrete schemas --- docs/abstract.md | 17 +++++++++++++++++ package.json | 2 +- 2 files changed, 18 insertions(+), 1 deletion(-) create mode 100644 docs/abstract.md diff --git a/docs/abstract.md b/docs/abstract.md new file mode 100644 index 000000000..7fe4f8a8f --- /dev/null +++ b/docs/abstract.md @@ -0,0 +1,17 @@ +## Abstract and Concrete Schemas + +XDM is defined using a modular schema framework that encourages the re-use of schemas or parts of schemas. +As a result, XDM consists of abstract and concrete schemas. + +### Abstract Schemas + +Abstract schemas or schema fragments are partial schemas that can be re-used in other schemas, but that do not allow the creation of any instances. +As an example, the [Language Alternative](reference/assets/language-alternative.schema.md) schema which is used to define metadata that varies by language can be used as part of an [Asset](reference/assets/asset.schema.md), but it cannot stand on its own. + +Abstract schemas are often used to define properties that are used in multiple schemas at once. + +### Concrete Schemas + +Concrete schemas or proper schemas are schemas that can be instantiated, i.e. they describe instances of entities that are exposed by APIs that are implementing XDM. + +Concrete schemas often include or reference Abstract schemas. diff --git a/package.json b/package.json index 9661226c5..58294fb75 100644 --- a/package.json +++ b/package.json @@ -12,7 +12,7 @@ "scripts": { "clean": "rm -rf docs/reference", "markdown": - "shx mkdir -p docs/reference && jsonschema2md -o docs/reference -d schemas", + "shx mkdir -p docs/reference && jsonschema2md -o docs/reference -d schemas --link-abstract abstract.md", "test": "mocha", "lint": "prettier --write *.json *.md docs/*.md schemas/*/**/*.md schemas/*/**/*.json extensions/*/**/*.json && git diff --exit-code", From 29dbddee975e001f7e92617270b875179e1986dd Mon Sep 17 00:00:00 2001 From: Lars Trieloff Date: Wed, 2 May 2018 14:53:54 +0000 Subject: [PATCH 2/5] Explain the status attributes --- docs/status.md | 11 +++++++++++ package.json | 2 +- 2 files changed, 12 insertions(+), 1 deletion(-) create mode 100644 docs/status.md diff --git a/docs/status.md b/docs/status.md new file mode 100644 index 000000000..69a6f71c7 --- /dev/null +++ b/docs/status.md @@ -0,0 +1,11 @@ +## Schema Status + +The status of each schema in XDM describes the likelihood of change of a schema. +In particular for XDM Versions prior to XDM 1.0.0, this can inform users and providers of XDM-compatible APIs of the stability of a given schema. + +XDM defines following status values: + +* Stable: the schema is considered stable and can be used in production without any risk. Additions to the schema are possible, but will not impact existing implementations. +* Stabilizing: No further major changes to the schema are expected, but may occur after review. Implementors should check the status of the schema regularly. +* Experimental: Major changes can be expected because the schema is still in active development. Implementors should proceed with caution. +* Deprecated: Schema is no longer maintained, supported or is superceded by another schema/set of schemas. Implementors should update their implementations. diff --git a/package.json b/package.json index 58294fb75..c499d9aa5 100644 --- a/package.json +++ b/package.json @@ -12,7 +12,7 @@ "scripts": { "clean": "rm -rf docs/reference", "markdown": - "shx mkdir -p docs/reference && jsonschema2md -o docs/reference -d schemas --link-abstract abstract.md", + "shx mkdir -p docs/reference && jsonschema2md -o docs/reference -d schemas --link-abstract abstract.md --link-extensible extensions.md --link-status status.md", "test": "mocha", "lint": "prettier --write *.json *.md docs/*.md schemas/*/**/*.md schemas/*/**/*.json extensions/*/**/*.json && git diff --exit-code", From 8c41743174288939bdf623eaf64d56d13e4d631b Mon Sep 17 00:00:00 2001 From: Lars Trieloff Date: Wed, 2 May 2018 14:58:17 +0000 Subject: [PATCH 3/5] [trivial] lint --- docs/introduction.md | 16 ++++++++++++---- docs/status.md | 2 +- 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/docs/introduction.md b/docs/introduction.md index 60b34fef7..4241a6110 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -55,6 +55,10 @@ As laid out in [Semantic Versioning 2.0.0](https://semver.org), article 4: XDM is at major version zero at this time, and should not be considered stable. +### Schema Status + +Every Schema in XDM has a dedicated status that describes the likelihood of and ability to change. Details are explained in [Schema Status](status.md) + ### Extensibility The fields in each XDM model are extensible. Consuming applications should not fail when they encounter unknown schemas, field names, or property values. @@ -67,13 +71,17 @@ All extensions will be performed using URIs as property names, which means that This best practice holds for customer- and vendor-specific extensions to XDM, but also to version updates to XDM. New schemas, field names, or property values introduced by either a newer version of XDM or an extension of XDM must not cause a consumer to fail, and should, when possible, passed through without modification. -### Versioning Schema - -… - ## Formal Expression XDM is formally specified through a combination of JSON Schema and some aspects of JSON for Linking Data (JSON-LD). JSON Schema specifies unambiguously which properties and property values are allowed for a specific instance of a model, JSON-LD provides us with best practices of defining namespace prefixes, and identifying the semantics of property names. For consumers, it is not neccessary to understand JSON-LD, and expected to treat all XDM documents as JSON documents. This means, if the JSON representation of two XDM models is identical, then the two models are considered identical. + +## Specification Details + +1. [Related Standards](standards.md) +2. [Terminology used in XDM](terminology.md) +3. [Extending XDM](extensions.md) +4. [Abstract and Concrete Schema](abstract.md) +5. [Schema Status](status.md) diff --git a/docs/status.md b/docs/status.md index 69a6f71c7..2d0f976b5 100644 --- a/docs/status.md +++ b/docs/status.md @@ -1,6 +1,6 @@ ## Schema Status -The status of each schema in XDM describes the likelihood of change of a schema. +The status of each schema in XDM describes the likelihood of change of a schema. In particular for XDM Versions prior to XDM 1.0.0, this can inform users and providers of XDM-compatible APIs of the stability of a given schema. XDM defines following status values: From 5262aab68de1412db337186006391841e6eb9ec0 Mon Sep 17 00:00:00 2001 From: Lars Trieloff Date: Wed, 2 May 2018 15:06:58 +0000 Subject: [PATCH 4/5] Explain the `@id` attribute --- docs/id.md | 6 ++++++ docs/introduction.md | 1 + package.json | 2 +- 3 files changed, 8 insertions(+), 1 deletion(-) create mode 100644 docs/id.md diff --git a/docs/id.md b/docs/id.md new file mode 100644 index 000000000..05c2f37ac --- /dev/null +++ b/docs/id.md @@ -0,0 +1,6 @@ +## Identifying Entities + +Instances of most schemas in XDM are uniquely identifiable based on the value of the `@id` attribute. +This attribute is always a URI, but may not be present or required in all schemas. + +Schemas that have an `@id` attribute are considered identifiable, schemas that do not have this attribute are typically only used as child-objects in identifiable schemas. diff --git a/docs/introduction.md b/docs/introduction.md index 4241a6110..a3c3692ab 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -85,3 +85,4 @@ This means, if the JSON representation of two XDM models is identical, then the 3. [Extending XDM](extensions.md) 4. [Abstract and Concrete Schema](abstract.md) 5. [Schema Status](status.md) +6. [Identifiable Entities](id.md) diff --git a/package.json b/package.json index c499d9aa5..1279c4b05 100644 --- a/package.json +++ b/package.json @@ -12,7 +12,7 @@ "scripts": { "clean": "rm -rf docs/reference", "markdown": - "shx mkdir -p docs/reference && jsonschema2md -o docs/reference -d schemas --link-abstract abstract.md --link-extensible extensions.md --link-status status.md", + "shx mkdir -p docs/reference && jsonschema2md -o docs/reference -d schemas --link-abstract abstract.md --link-extensible extensions.md --link-status status.md --link-id id.md", "test": "mocha", "lint": "prettier --write *.json *.md docs/*.md schemas/*/**/*.md schemas/*/**/*.json extensions/*/**/*.json && git diff --exit-code", From 84cdbfca7e5bbad2bd96095ba5df661ecbf0684c Mon Sep 17 00:00:00 2001 From: Lars Trieloff Date: Wed, 2 May 2018 15:09:01 +0000 Subject: [PATCH 5/5] Use extensions to describe custom and additional properties --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 1279c4b05..3007d82bc 100644 --- a/package.json +++ b/package.json @@ -12,7 +12,7 @@ "scripts": { "clean": "rm -rf docs/reference", "markdown": - "shx mkdir -p docs/reference && jsonschema2md -o docs/reference -d schemas --link-abstract abstract.md --link-extensible extensions.md --link-status status.md --link-id id.md", + "shx mkdir -p docs/reference && jsonschema2md -o docs/reference -d schemas --link-abstract abstract.md --link-extensible extensions.md --link-status status.md --link-id --link-custom extensions.md --link-additional extensions.md", "test": "mocha", "lint": "prettier --write *.json *.md docs/*.md schemas/*/**/*.md schemas/*/**/*.json extensions/*/**/*.json && git diff --exit-code",