From 578e18e31574eb9e95466e71cf1f8037a2e17e10 Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Thu, 31 May 2018 07:00:23 -0700 Subject: [PATCH] Make extension attributes siblings to our attributes Signed-off-by: Doug Davis --- json-format.md | 19 ++++++------------- spec.md | 36 +++++++++++++++--------------------- 2 files changed, 21 insertions(+), 34 deletions(-) diff --git a/json-format.md b/json-format.md index cc66fc7cf..62dfe9b63 100644 --- a/json-format.md +++ b/json-format.md @@ -86,7 +86,6 @@ The following table shows exemplary mappings: | eventID | String | "1234-1234-1234" | eventTime | Timestamp| "2018-04-05T17:31:00Z" | contentType | String | "application/json" -| extensions | Map | { "extA" : "vA", "extB", "vB" } | data | String | "" | data | Binary | "Q2xvdWRFdmVudHM=" | data | Map | { "objA" : "vA", "objB", "vB" } @@ -140,11 +139,9 @@ Example event with `String`-valued `data`: "source" : "/mycontext", "eventID" : "A234-1234-1234", "eventTime" : "2018-04-05T17:31:00Z", - "extensions" : { - "comExampleExtension" : "value" - }, "contentType" : "text/xml", - "data" : "" + "data" : "", + "comExampleExtension" : "value" } ``` @@ -157,11 +154,9 @@ Example event with `Binary`-valued data "source" : "/mycontext", "eventID" : "B234-1234-1234", "eventTime" : "2018-04-05T17:31:00Z", - "extensions" : { - "comExampleExtension" : "value" - }, "contentType" : "application/vnd.apache.thrift.binary", - "data" : "... base64 encoded string ..." + "data" : "... base64 encoded string ...", + "comExampleExtension" : "value" } ``` @@ -175,15 +170,13 @@ a `Map` or [JSON data](#31-special-handling-of-the-data-attribute) data: "source" : "/mycontext", "eventID" : "C234-1234-1234", "eventTime" : "2018-04-05T17:31:00Z", - "extensions" : { - "comExampleExtension" : "value" - }, "contentType" : "application/json", "data" : { "appinfoA" : "abc", "appinfoB" : 123, "appinfoC" : true - } + }, + "comExampleExtension" : "value" } ``` diff --git a/spec.md b/spec.md index a7346981a..c12544beb 100644 --- a/spec.md +++ b/spec.md @@ -137,6 +137,14 @@ attributes and the event data will be materialized. For example, in the case of a JSON serialization, the context attributes and the event data might both appear within the same JSON object. +CloudEvent producers MAY include additional extension attributes within the +event. Each specification that defines how to serialize a CloudEvent will +define how extension attributes will appear. When defining a new extension +care SHOULD be taken to use a name that is descriptive enough to reduce the +chances of it overlapping with other extensions. +See the [Extensions](extensions.md) document for a list of documented extension +attributes. + ### eventType * Type: `String` * Description: Type of occurrence which has happened. Often this @@ -206,38 +214,24 @@ Incompatible changes to the schema SHOULD be reflected by a different URL. `contentType` values are defined in the event format specifications; for example, the JSON event format defines the relationship in [section 3.1](./json-format.md#31-special-handling-of-the-data-attribute). - - When this attribute is omitted, the "data" attribute simply follows the - event format's encoding rules. For the JSON event format, the "data" - attribute value can therefore be a JSON object, array, or value. - + + When this attribute is omitted, the "data" attribute follows the + event format's encoding rules. For the JSON event format, the "data" + attribute value can therefore be a JSON object, array, or value. + For the binary mode of some of the CloudEvents transport bindings, where the "data" content is immediately mapped into the payload of the transport frame, this field is directly mapped to the respective transport or application protocol's content-type metadata property. Normative rules - for the binary mode and the content-type metadata mapping can be found + for the binary mode and the content-type metadata mapping can be found in the respective transport mapping specifications. - + * Constraints: * OPTIONAL * If present, MUST adhere to the format specified in [RFC 2046](https://tools.ietf.org/html/rfc2046) * For Media Type examples see [IANA Media Types](http://www.iana.org/assignments/media-types/media-types.xhtml) -### extensions -* Type: `Map` -* Description: This is for additional metadata and this does not have a - mandated structure. This enables a place for custom fields a producer or - middleware might want to include and provides a place to test metadata before - adding them to the CloudEvents specification. - See the [Extensions](extensions.md) document for a list of possible - attributes. -* Constraints: - * OPTIONAL - * If present, MUST contain at least one entry -* Examples: - * authorization data - ## Data Attribute As defined by the term [Data](#data), CloudEvents MAY include domain-specific