Skip to content

Latest commit

 

History

History
210 lines (166 loc) · 7.41 KB

json-format.md

File metadata and controls

210 lines (166 loc) · 7.41 KB
Raw

JSON Event Format for CloudEvents - Version 0.1

Abstract

The JSON Format for CloudEvents defines how events are expressed in JavaScript Object Notation (JSON) Data Interchange Format (RFC8259).

Status of this document

This document is a working draft.

Table of Contents

  1. Introduction
  2. Attributes
  3. Envelope
  4. References

1. Introduction

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.

1.1. Conformance

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.

2. Attributes

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.

2.1. Base Type System

The core CloudEvents specification defines a minimal abstract type system, which this mapping leans on.

2.2. Type System Mapping

The CloudEvents type system is mapped to JSON types as follows:

CloudEvents JSON
String string
Binary string, Base64-encoded binary
URI string
Timestamp string
Map JSON object
Object JSON value

2.3. Mapping Object-typed Attributes

The CloudEvents data attribute is Object-typed, meaning that it either holds a String, or a Binary value, or a Map. Map entry values are also Object typed.

If an implementation determines that the actual type of an Object 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.

2.4. Examples

The following table shows exemplary mappings:

CloudEvents Type Exemplary JSON Value
eventType String "com.example.someevent"
eventTypeVersion String "1.0"
cloudEventsVersion String "0.1"
source URI "/mycontext"
eventID String "1234-1234-1234"
eventTime Timestamp "2018-04-05T17:31:00Z"
contentType String "application/json"
extensions Map { "extA" : "vA", "extB", "vB" }
data String "<much wow="xml"/>"
data Binary "Q2xvdWRFdmVudHM="
data Map { "objA" : "vA", "objB", "vB" }

3. Envelope

Each CloudEvents event can be wholly represented as a JSON object.

Such a representation uses 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.

3.1. Special Handling of the "data" Attribute

The mapping of the Object-typed data attribute follows the rules laid out in Section 2.3., with one additional rule:

If an implementation determines that the type of the data attribute is Binary or String, it MUST inspect the contentType attribute to determine whether it is indicated that the data value contains JSON data.

If the contentType value is "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 member of the envelope JSON object to this JSON value.

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.

3.2. Examples

Example event with String-valued data:

{
    "cloudEventsVersion" : "0.1",
    "eventType" : "com.example.someevent",
    "eventTypeVersion" : "1.0",
    "source" : "/mycontext",
    "eventID" : "A234-1234-1234",
    "eventTime" : "2018-04-05T17:31:00Z",
    "extensions" : {
      "comExampleExtension" : "value"
    },
    "contentType" : "text/xml",
    "data" : "<much wow=\"xml\"/>"
}

Example event with Binary-valued data

{
    "cloudEventsVersion" : "0.1",
    "eventType" : "com.example.someevent",
    "eventTypeVersion" : "1.0",
    "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 ..."
}

Example event with JSON data for the "data" member, either derived from a Map or JSON data data:

{
    "cloudEventsVersion" : "0.1",
    "eventType" : "com.example.someevent",
    "eventTypeVersion" : "1.0",
    "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
    }
}

4. References

  • 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