Merge pull request #340 from duglin/versionEventType

Add clarity text and an example of versioning eventTypes

Author: Doug Davis

primer.md

@@ -18,6 +18,7 @@ This document is a working draft.
 - [History](#history)
 - [CloudEvents Concepts](#cloudevents-concepts)
 - [Design Goals](#design-goals)
+- [Versioning of Attributes](#versioning-of-attributes)
 - [CloudEvent Attributes Extensions](#cloudevent-attribute-extensions)
 - [Qualifying Protocols and Encodings](#qualifying-protocols-and-encodings)
 - [Prior Art](#prior-art)
@@ -122,6 +123,25 @@ The following will not be part of the specification:
 * Language-specific runtime APIs
 * Selecting a single identity/access control system
 
+## Versioning of Attributes
+
+For certain CloudEvents attributes, the entity or data model referenced by its
+value might change over time. For example, `schemaurl` might be a reference
+one particular version of a schema document. Often these attribute values
+will then distinguish each variant by including some version-specific
+string as part of its value. For example, a version number (`v1`, `v2`), or a
+date (`2018-01-01`) might be used.
+
+The CloudEvents specification does not mandate any particular pattern to
+be used, or even the use of version strings at all. This decision is up to
+each event producer. However, when a version-specific string is included,
+care should be taken whenever its value changes as event consumers might
+be reliant on the existing value and thus a change could be interpretted
+as a "breaking change". Some form of communication between producers and
+consumers should be established to ensure the event consumers know what
+possible values might be used. In general, this is true for all CloudEvents
+attributes as well.
+
 ## CloudEvent Attribute Extensions
 
 In order to achieve the stated goals, the specification authors will attempt to

spec.md

@@ -176,13 +176,18 @@ help intermediate gateways determine how to route the events.
 * Type: `String`
 * Description: Type of occurrence which has happened. Often this
   attribute is used for routing, observability, policy enforcement, etc.
+  The format of this is producer defined and might include information such
+  as the version of the `eventtype` - see
+  [Versioning of Attributes in the Primer](primer.md#versioning-of-attributes)
+  for more information.
 * Constraints:
    * REQUIRED
    * MUST be a non-empty string
    * SHOULD be prefixed with a reverse-DNS name. The prefixed domain dictates
             the organization which defines the semantics of this event type.
 * Examples
    * com.github.pull.create
+   * com.example.object.delete.v2
 
 ### specversion
 * Type: `String`
@@ -229,7 +234,10 @@ help intermediate gateways determine how to route the events.
 ### schemaurl
 * Type: `URI`
 * Description: A link to the schema that the `data` attribute adheres to.
-Incompatible changes to the schema SHOULD be reflected by a different URL.
+  Incompatible changes to the schema SHOULD be reflected by a different URL.
+  See
+  [Versioning of Attributes in the Primer](primer.md#versioning-of-attributes)
+  for more information.
 * Constraints:
   * OPTIONAL
   * If present, MUST adhere to the format specified in