The JSON Format for CloudEvents defines how events are expressed in JavaScript Object Notation (JSON) Data Interchange Format (RFC8259).
This document is a working draft.
CloudEvents is a standardized and transport-neutral definition of the structure and metadata description of events. This specification defines how the elements defined in the CloudEvents specification are to be represented in the JavaScript Object Notation (JSON) Data Interchange Format (RFC8259).
The Attributes section describes the naming conventions and data type mappings for CloudEvents attributes.
The Envelope section defines a JSON container for CloudEvents attributes and an associated media type.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.
This section defines how CloudEvents attributes are mapped to JSON. This 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.
The core CloudEvents specification defines a minimal abstract type system, which this mapping leans on.
The CloudEvents type system MUST be mapped to JSON types as follows, with exceptions noted below.
| CloudEvents | JSON |
|---|---|
| String | string |
| Integer | number, only the int component is permitted |
| Binary | string, Base64-encoded binary |
| URI-reference | string following RFC 3986 |
| Timestamp | string following RFC 3339 (ISO 8601) |
| Map | JSON object |
| Any | JSON value |
Extension specifications MAY define diverging mapping rules for the values of attributes they define.
For instance, the attribute value might be a data structure defined in a standard outside of CloudEvents, with a formal JSON mapping, and there might be risk of translation errors or information loss when the original format is not preserved.
An extension specification that defines a diverging mapping rule for JSON, and any revision of such a specification, MUST also define explicit mapping rules for all other event formats that are part of the CloudEvents core at the time of the submission or revision.
If required, like when decoding Maps, the CloudEvents type can be determined by
inference using the rules from the mapping table, whereby the only potentially
ambiguous JSON data type is string. The value is compatible with the
respective CloudEvents type when the mapping rules are fulfilled.
The CloudEvents data attribute is Any-typed, meaning that it holds a value
of any valid type. Map entry values are also Any typed.
If an implementation determines that the actual type of an Any is a String,
the value MUST be represented as JSON string expression; for
Binary, the value MUST represented as JSON string expression
containing the Base64 encoded binary value; for Map, the value MUST
be represented as a JSON object expression, whereby the index
fields become member names and the associated values become the respective
member's value.
The following table shows exemplary mappings:
| CloudEvents | Type | Exemplary JSON Value |
|---|---|---|
| type | String | "com.example.someevent" |
| specversion | String | "0.3" |
| source | URI-reference | "/mycontext" |
| id | String | "1234-1234-1234" |
| time | Timestamp | "2018-04-05T17:31:00Z" |
| datacontenttype | String | "application/json" |
| data | String | "<much wow="xml"/>" |
| data | Binary | "Q2xvdWRFdmVudHM=" |
| data | Map | { "objA" : "vA", "objB", "vB" } |
The CloudEvents JSONSchema for the spec is located here and contains the definitions for validating events in JSON.
Each CloudEvents event can be wholly represented as a JSON object.
Such a representation MUST use the media type application/cloudevents+json.
All REQUIRED and all not omitted OPTIONAL attributes in the given event MUST become members of the JSON object, with the respective JSON object member name matching the attribute name, and the member's type and value being mapped using the type system mapping.
The mapping of the Any-typed data attribute follows the rules laid out in
Section 2.3., with two additional rules:
First, if an implementation determines that the type of the data attribute is
Binary or String, it MUST inspect the datacontenttype attribute to
determine whether it is indicated that the data value contains JSON data.
If the datacontenttype value is either "application/json" or any
media type with a structured +json suffix, the implementation MUST
translate the data attribute value into a JSON value, and set
the data attribute of the envelope JSON object to this JSON value.
If the datacontenttype value does not follow the structured +json
suffix but is known to use JSON encoding, the implementation MUST
translate the data attribute value into a JSON value, and set
the data attribute of the envelope JSON object to this JSON value. Its typical
examples are, but not limited to, text/json,
application/json-seq and
application/geo+json-seq.
Unlike all other attributes, for which value types are restricted to strings per
the type-system mapping, the resulting data member
JSON value is unrestricted, and MAY also contain numeric and
logical JSON types.
Second, whether a Base64-encoded string in the data attribute is treated as
Binary or as a String is also determined by the datacontenttype value. If
the datacontenttype media type is known to contain text, the data attribute
value is not further interpreted and treated as a text string. Otherwise, it is
decoded and treated as a binary value.
Example event with String-valued data:
{
"specversion" : "0.3",
"type" : "com.example.someevent",
"source" : "/mycontext",
"id" : "A234-1234-1234",
"time" : "2018-04-05T17:31:00Z",
"comexampleextension1" : "value",
"comexampleextension2" : {
"otherValue": 5
},
"datacontenttype" : "text/xml",
"data" : "<much wow=\"xml\"/>"
}Example event with Binary-valued data
{
"specversion" : "0.3",
"type" : "com.example.someevent",
"source" : "/mycontext",
"id" : "B234-1234-1234",
"time" : "2018-04-05T17:31:00Z",
"comexampleextension1" : "value",
"comexampleextension2" : {
"otherValue": 5
},
"datacontenttype" : "application/vnd.apache.thrift.binary",
"data" : "... base64 encoded string ..."
}Example event with JSON data for the "data" member, either derived from a Map
or JSON data data:
{
"specversion" : "0.3",
"type" : "com.example.someevent",
"source" : "/mycontext",
"id" : "C234-1234-1234",
"time" : "2018-04-05T17:31:00Z",
"comexampleextension1" : "value",
"comexampleextension2" : {
"otherValue": 5
},
"datacontenttype" : "application/json",
"data" : {
"appinfoA" : "abc",
"appinfoB" : 123,
"appinfoC" : true
}
}In the JSON Batch Format several CloudEvents are batched into a single JSON document. The document is a JSON array filled with CloudEvents in the JSON Event format.
Although the JSON Batch Format builds ontop of the JSON Format, it is considered as a separate format: a valid implementation of the JSON Format doesn't need to support it. The JSON Batch Format MUST NOT be used when only support for the JSON Format is indicated.
This section defines how a batch of CloudEvents is mapped to JSON.
The outermost JSON element is a JSON Array, which contains as elements CloudEvents rendered in accordance with the JSON event format specification.
A JSON Batch of CloudEvents MUST use the media type
application/cloudevents-batch+json.
An example containing two CloudEvents: The first with Binary-valued data, the
second with JSON data.
[
{
"specversion" : "0.3",
"type" : "com.example.someevent",
"source" : "/mycontext/4",
"id" : "B234-1234-1234",
"time" : "2018-04-05T17:31:00Z",
"comexampleextension1" : "value",
"comexampleextension2" : {
"otherValue": 5
},
"datacontenttype" : "application/vnd.apache.thrift.binary",
"data" : "... base64 encoded string ..."
},
{
"specversion" : "0.3",
"type" : "com.example.someotherevent",
"source" : "/mycontext/9",
"id" : "C234-1234-1234",
"time" : "2018-04-05T17:31:05Z",
"comexampleextension1" : "value",
"comexampleextension2" : {
"otherValue": 5
},
"datacontenttype" : "application/json",
"data" : {
"appinfoA" : "abc",
"appinfoB" : 123,
"appinfoC" : true
}
}
]An example of an empty batch of CloudEvents (typically used in a response):
[]- RFC2046 Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types
- RFC2119 Key words for use in RFCs to Indicate Requirement Levels
- RFC4627 The application/json Media Type for JavaScript Object Notation (JSON)
- RFC4648 The Base16, Base32, and Base64 Data Encodings
- RFC6839 Additional Media Type Structured Syntax Suffixes
- RFC8259 The JavaScript Object Notation (JSON) Data Interchange Format