From ba8ad6f4fe820332b6002a3cd2a7604fd6a17de8 Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Tue, 13 Nov 2018 15:05:17 -0800 Subject: [PATCH] Add some rationale for our extensions decision The Primer is a good location to document some of our design decisions without cluttering the spec with non-normative text. This is my first pass at some of the reasons why we're serializing extensions as top-level properties in JSON. Note, as you review this please focus on whether the text accurately reflects the reasons why we ended up with our current design. This PR should not be used to question whether it was a good or bad decision. If you want to question the decision itself then a new issue (or PR) is the best place to do that - I'm just trying to document history. Signed-off-by: Doug Davis --- json-format.md | 10 +++++++++- primer.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ spec.md | 3 ++- 3 files changed, 57 insertions(+), 2 deletions(-) diff --git a/json-format.md b/json-format.md index 0a096ce31..09093effd 100644 --- a/json-format.md +++ b/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 @@ -105,7 +113,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. diff --git a/primer.md b/primer.md index ea0e49e04..d2f66cc80 100644 --- a/primer.md +++ b/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, diff --git a/spec.md b/spec.md index e41413eb4..8eb26cc1e 100644 --- a/spec.md +++ b/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