Merge pull request #1 from adobe/master

make up to date with main repo

.circleci/config.yml

@@ -106,12 +106,13 @@ jobs:
 
       # generate markdowm
       - run: npm run markdown
+      - run: node bin/show-stablization-candidates.js > STABILIZING.md
       - run: git config --global user.email "trieloff@adobe.com" && git config --global user.name "CircleCI"
 
       # send up-to-date markdown back to GitHub
       - run:
           name: Publish Markdown to GitHub
-          command: git add --force docs/reference/* && git commit -m "[ci skip] updating documentation" && git push
+          command: git add --force STABILIZING.md && git add --force docs/reference/* && git commit -m "[ci skip] updating documentation" && git push
 
 workflows:
   version: 2

CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## Release 0.9.0
+
+[Released on April 13, 2018](https://github.com/adobe/xdm/releases/tag/v0.9)
+
+* Release 0.9 is preview release which updates the `ExperienceEvent` schema to 'stabilizing' status, along with many of the schemas it depends on. This release is intended to get early feedback from implementers and the community before a 1.0 release.
+
+## Release 0.9.1
+
+[Unreleased](https://github.com/adobe/xdm/releases/tag/v0.9.1)
+
+* Renames all `Metric` schemas to `Metric Definition` #254

CONTRIBUTING.md

@@ -61,7 +61,7 @@ You can include the Creative Commons Attribution 4.0 International (CC BY 4.0) l
 Every pull request should specify:
 
 * What the change intends to do
-* If there are breaking changes
+* If there are breaking changes (in case there are, list them in [CHANGELOG.md](CHANGELOG.md), too)
 * Link to the Github issue in the format `#42`
 
 For every update to the schema, make sure
@@ -103,7 +103,7 @@ XDM is not an isolated standard, but incorporates and builds on standards. Whene
 
 ### Design for Compatibility
 
-Interoperability with [Microsoft's Common Data Model (CDM)](https://github.com/Microsoft/CDM)is a top priority. This means that definitions that are present in CDM should be used or extended, where appropriate, by XDM. XDM should not attempt to duplicate definitions that are present in CDM.
+Interoperability with [Microsoft's Common Data Model (CDM)](https://github.com/Microsoft/CDM) is a top priority. This means that definitions that are present in CDM should be used or extended, where appropriate, by XDM. XDM should not attempt to duplicate definitions that are present in CDM.
 
 Where appropriate, we can 'lead' CDM, extend it to meet other requirements.
 Another good source of data model elements is [schema.org](http://schema.org).
@@ -117,6 +117,7 @@ Additional aspects of standard design that aid with consumability are:
 * principle of least astonishment: don't surprise the consumer
 * avoid unnecessary complexity: don't introduce indirections that are not needed
 * the principle of minimal verbosity: make keep things as short as possible, but not shorter
+* avoid unnecessary polymorphism that is hard to consume, e.g. offering both singular and array notations, or introducing type variants that don't provide a common discriminator property.
 
 ### Design for the Cloud
 
@@ -351,6 +352,25 @@ The third schema is `third.schema.json`, it extends both `second`, and transitiv
 }
 ```
 
+### Schema Descriptors
+
+Schema descriptors are an extensible mechanism for providing additional metadata about an XDM schema. For example, schema descriptors can be used to define relationships between schemas or to annotate schema properties with additional metadata. Schema descriptors may be used when certain properties of a schema are not static (which could usually be described in the schema directly) but may vary from usage to usage.
+
+Details on using and defining schema descriptors may be found in the section [Schema Descriptors](./docs/descriptors.md) of the specification.
+
+Schema descriptors are extensible, and new descriptors may be creating by defining a new URI value and using it in
+the `@type` property of the descriptor object. Readers should ignore descriptors they do not understand.
+
+Schema descriptors are defined in XDM using the `SchemaDescriptor` schema.
+
+### Structuring Schemas - Nesting versus Namespaces
+
+The use of JSON-LD namespaces in XDM means that schema definitions are organized around two axes. The first is the structure of the JSON, which may be nested to an arbitrary depth. The second is the orthogonal layer created by each independent namespace. While both organizing axes are available, it is important to use each for its intended purpose.
+
+Namespaces should be used to allow organizations to develop XDM-based grammars independently of each other, without fear of conflict and without a need to coordinate. In general, it is desirable to have the smallest set of namespaces possible while meeting the above goals.
+
+Namespaces _should not_ be used to organize or group concepts within a grammar. When organizing concepts, schema authors should either define sub-objects for each concept, or consider breaking out the concept into an independent schema, as described in "Re-use and Modularity".
+
 ### Schema Stability Status
 
 Each schema should contains the enum property `meta:status` that designates it's stability. The value should be one of the following enumerations:
@@ -366,6 +386,7 @@ XDM is using a couple of custom keywords that are not part of the JSON Schema st
 
 * `meta:extensible`: see above, to describe schemas that allow custom properties
 * `meta:auditable`: for schemas that have created and last modified dates
+* `meta:descriptors`: to annotate schemas with additional metadata (see Schema Descriptors above)
 * `meta:enum`: for known values in enums, strings, and as property keys
 
 ## Writing Styleguides