json-batch-format.md

JSON Batch Event Format for CloudEvents - Version 0.1

Abstract

The JSON Batch Format for CloudEvents defines how a batch of events is expressed in JavaScript Object Notation (JSON) Data Interchange Format (RFC8259), based on the inner JSON Event Format

Status of this document

This document is a working draft.

Table of Contents

1. Introduction
2. Envelope
3. 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) when a batch of events is represented. This is possible in the HTTP transport's Structured mode.

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. Envelope

A batch of CloudEvents events can be represented as an array of JSON objects.

Such a representation uses the media type application/cloudevents+json-batch

Every object in the array must conform to the JSON Event Format

3.2. Examples

Example events with String-valued data:

[{
    "cloudEventsVersion" : "0.1",
    "eventType" : "com.example.someevent",
    "source" : "/mycontext",
    "eventID" : "A234-1234-1234",
    "eventTime" : "2018-04-05T17:31:00Z",
    "comExampleExtension1" : "value",
    "comExampleExtension2" : {
        "otherValue": 5
    },
    "contentType" : "text/xml",
    "data" : "<much wow=\"xml\"/>"
},
{
    "cloudEventsVersion" : "0.1",
    "eventType" : "com.example.someevent",
    "source" : "/mycontext",
    "eventID" : "A234-1234-5678",
    "eventTime" : "2018-04-05T17:32:00Z",
    "comExampleExtension1" : "value",
    "comExampleExtension2" : {
        "otherValue": 6
    },
    "contentType" : "text/xml",
    "data" : "<much wow=\"xml\" such=\"doge\"/>"
}
]

Example events with Binary-valued data

[
{
    "cloudEventsVersion" : "0.1",
    "eventType" : "com.example.someevent",
    "source" : "/mycontext",
    "eventID" : "B234-1234-1234",
    "eventTime" : "2018-04-05T17:31:00Z",
    "comExampleExtension1" : "value",
    "comExampleExtension2" : {
        "otherValue": 5
    },
    "contentType" : "application/vnd.apache.thrift.binary",
    "data" : "... base64 encoded string ..."
},
{
    "cloudEventsVersion" : "0.1",
    "eventType" : "com.example.someevent",
    "source" : "/mycontext",
    "eventID" : "B234-1234-5678",
    "eventTime" : "2018-04-05T17:32:00Z",
    "comExampleExtension1" : "value",
    "comExampleExtension2" : {
        "otherValue": 6
    },
    "contentType" : "application/vnd.apache.thrift.binary",
    "data" : "... base64 encoded string ..."
}
]

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

[
{
    "cloudEventsVersion" : "0.1",
    "eventType" : "com.example.someevent",
    "source" : "/mycontext",
    "eventID" : "C234-1234-1234",
    "eventTime" : "2018-04-05T17:31:00Z",
    "comExampleExtension1" : "value",
    "comExampleExtension2" : {
        "otherValue": 5
    },
    "contentType" : "application/json",
    "data" : {
        "appinfoA" : "abc",
        "appinfoB" : 123,
        "appinfoC" : true
    }
},
{
    "cloudEventsVersion" : "0.1",
    "eventType" : "com.example.someevent",
    "source" : "/mycontext",
    "eventID" : "C234-1234-5678",
    "eventTime" : "2018-04-05T17:32:00Z",
    "comExampleExtension1" : "value",
    "comExampleExtension2" : {
        "otherValue": 6
    },
    "contentType" : "application/json",
    "data" : {
        "appinfoA" : "foo",
        "appinfoB" : 543,
        "appinfoC" : false
    }
}
]

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