Merge pull request #290 from adobe/extensibility-docs

Improve Documentation of Schema Attributes

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.

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.

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,18 @@ 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)
+6.  [Identifiable Entities](id.md)

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.

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 --link-extensible extensions.md --link-status status.md --link-id --link-custom extensions.md --link-additional extensions.md",
     "test": "mocha",
     "lint":
       "prettier --write *.json CHANGELOG.md CONTRIBUTING.md README.md docs/*.md schemas/*/**/*.md schemas/*/**/*.json extensions/*/**/*.json && git diff --exit-code",