Merge pull request #353 from duglin/primerExtensions

Add some rationale for our extensions decision

Author: Doug Davis

json-format.md

@@ -43,6 +43,14 @@ specification does not explicitly map each attribute, but
 provides a generic mapping model that applies to all current and future
 CloudEvents attributes, including extensions.
 
+For clarity, extension attributes are serialized using the same rules as
+specification defined attributes. This includes their syntax and placement
+within the JSON object. In particular, extensions are placed as top-level
+JSON properties. Extensions themselves are free to have nested properties,
+however the root of the extension MUST be serialized as a top-level JSON
+property. There were many reason for this design decision and they are covered
+in more detail in the [Primer](primer.md#json-extensions).
+
 ### 2.1. Base Type System
 
 The core [CloudEvents specification][CE] defines a minimal abstract type
@@ -110,7 +118,7 @@ The following table shows exemplary mappings:
 | data               | Binary        | "Q2xvdWRFdmVudHM="
 | data               | Map           | { "objA" : "vA", "objB", "vB" }
 
-## 2.5. JSONSchema Validation
+### 2.5. JSONSchema Validation
 
 The CloudEvents [JSONSchema](http://json-schema.org) for the spec is located
 [here](spec.json) and contains the definitions for validating events in JSON.

primer.md

@@ -177,6 +177,52 @@ consider moving it into the specification as a core attribute. This means
 that the extension mechanism/process can be used as a way to vet new
 attributes prior to formally adding them to the specification.
 
+### JSON Extensions
+
+As mentioned in the [Attributes](json-format.md#2-attributes) section of the
+[JSON Event Format for CloudEvents](json-format.md) specificatinon,
+CloudEvent extension attributes are serialized as siblings to the specification
+defined attributes - meaning, at the top-level of the JSON object. The
+authors of the specification spent a long time considering all options
+and decided that this was the best choice. Some of the rationale follows.
+
+Since the specifications follow [semver](https://semver.org/), this
+means that new properties can be defined by future versions of the
+core specification without requiring a major version number change - as
+long as these properties are optional. In those cases, consider what an
+existing consumer would do with a new (unknown) top-level property. While
+it would be free to ignore it, since it is optional, in most cases it is
+believed that these properties would still want to be exposed to the
+application receiving those events. This would allow those applications to
+support these properties even if the infrastructure doesn't. This means
+that unknown top-level properties (regardless of who defined them - future
+versions of the spec or the event producer) are probably not going to be
+ignored.  So, while some other specifications define a specific property
+underwhich extensions are placed (e.g. a top-level `extensions` property), the
+authors decided that having two different locations within an
+incoming event for unknown properties could lead to interoperability issues
+and confusion for developers.
+
+Often extensions are used to test new potential properties of
+specifications prior to them being formally adopted. If there were an
+`extensions` type of property, in which this new property was serialized,
+then if that property were to ever be adopted by the core specification it
+would be promoted (from a serialization perspective) from the `extensions`
+property to be a top-level property. If we assume that this new property
+will be optional, then as it is adopted by the core specification it will
+be just a minor version increment, and all existing consumers should still
+continue to work. However, consumers will not know where this property
+will appear - in the `extensions` property or as a top-level property.
+This means they might need to look in both places. What if the property
+appears in both place but with different values? Will producers need to place
+it in both places since they could have old and new consumers? While
+it might be possible to define clear rules for how to solve each of the
+potential problems that arise, the authors decided that it would be better
+to simply avoid all of them in the first place by only having one location
+in the serialization for unkown, or even new, properties. It was also
+noted that the HTTP specification is now following a similar pattern by
+no longer suggesting that extension HTTP headers be prefixed with `X-`.
+
 ## Qualifying Protocols and Encodings
 
 The explicit goal of the CloudEvents effort, as expressed in the specification,

spec.md

@@ -142,7 +142,8 @@ both appear within the same JSON object.
 ### Extension Attributes
 CloudEvents producers MAY include additional context attributes in the event
 that might be used in ancillary actions related to the processing of the event.
-See [CloudEvent Attributes Extensions](primer.md#cloudevent-attribute-extensions)
+See
+[CloudEvent Attributes Extensions](primer.md#cloudevent-attribute-extensions)
 for additional information concerning the use and definition of extensions.
 
 This specification places no restriction on the type or semantics of the