Initial attempt at batch clarification (cloudevents#1154)

jskeet · web-flow · commit 4af4b73585fb · 2023-02-23T13:02:57.000-05:00
* Initial attempt at batch clarification.

This treats batch-mode as a full-on third content mode (as it really
is). It attempts to clarify support in each transport and event
format, as well as removing duplication (e.g. in JSON format) of
what batch mode is about, and the odd "JSON batch format is a
separate event format" aspect.

Some parts may have been missed, and I'm thoroughly expecting some
push back :)

Signed-off-by: Jon Skeet &lt;jonskeet@google.com&gt;

* Address review feedback

(This includes removing some italics around content modes - we should probably do more of that, to be honest.)

Signed-off-by: Jon Skeet &lt;jonskeet@google.com&gt;

---------

Signed-off-by: Jon Skeet &lt;jonskeet@google.com&gt;
diff --git a/cloudevents/SDK.md b/cloudevents/SDK.md
@@ -109,9 +109,18 @@ based on the parameters set, most importantly the CloudEvents spec version.
 
 #### Encode/Decode an Event
 
-Each SDK will support encoding and decoding an Event with regards to a transport
-and encoding. `Structured` encoding is the easiest to support, as it is just
-`json`, but `Binary` is fairly custom for each transport.
+Each SDK MUST support encoding and decoding an Event with regards to a transport
+and encoding:
+
+- Each SDK MUST support structured-mode messages for each transport that it
+  supports.
+- Each SDK SHOULD support binary-mode messages for each transport that it
+  supports.
+- Each SDK SHOULD support batch-mode messages for each transport that it
+  supports (where the event format and transport combination supports batch mode).
+- Each SDK SHOULD indicate which modes it supports for each supported event
+  format, both in the [table below](#feature-support) and in any SDK-specific
+  documentation provided.
 
 #### Data
 
diff --git a/cloudevents/bindings/amqp-protocol-binding.md b/cloudevents/bindings/amqp-protocol-binding.md
@@ -55,9 +55,10 @@ format][message-format].
 
 ### 1.3. Content Modes
 
-The specification defines two content modes for transferring events:
-_structured_ and _binary_. Every compliant implementation SHOULD support both
-modes.
+The CloudEvents specification defines three content modes for transferring
+events: _structured_, _binary_ and _batch_. The AMQP protocol binding does not
+currently support the batch content mode. Every compliant implementation SHOULD
+support both structured and binary modes.
 
 In the _structured_ content mode, event metadata attributes and event data are
 placed into the AMQP message's [application data][data] section using an
diff --git a/cloudevents/bindings/http-protocol-binding.md b/cloudevents/bindings/http-protocol-binding.md
@@ -61,9 +61,10 @@ which is compatible with HTTP 1.1 semantics.
 
 ### 1.3. Content Modes
 
-This specification defines three content modes for transferring events:
-_binary_, _structured_ and _batched_. Every compliant implementation SHOULD
-support the _structured_ and _binary_ modes.
+The CloudEvents specification defines three content modes for transferring
+events: _structured_, _binary_ and _batch_. The HTTP protocol binding supports
+all three content modes. Every compliant implementation SHOULD
+support both structured and binary modes.
 
 In the _binary_ content mode, the value of the event `data` is placed into the
 HTTP request, or response, body as-is, with the `datacontenttype` attribute
@@ -401,14 +402,12 @@ Content-Length: nnnn
 
 In the _batched_ content mode several events are batched into a single HTTP
 request or response body. The chosen [event format](#14-event-formats) MUST
-define how a batch is represented. Based on the [JSON format][json-format] (that
-MUST be supported by any compliant implementation), the [JSON Batch
-format][json-batch-format] is an event format that supports batching.
+define how a batch is represented, including a suitable media type.
 
 #### 3.3.1. HTTP Content-Type
 
 The [HTTP `Content-Type`][content-type] header MUST be set to the media type of
-an [event format](#14-event-formats).
+the batch mode for the [event format](#14-event-formats).
 
 Example for the [JSON Batch format][json-batch-format]:
 
diff --git a/cloudevents/bindings/kafka-protocol-binding.md b/cloudevents/bindings/kafka-protocol-binding.md
@@ -70,8 +70,14 @@ the records.
 
 ### 1.3. Content Modes
 
-The specification defines two content modes for transferring events:
-_structured_ and _binary_.
+The CloudEvents specification defines three content modes for transferring
+events: _structured_, _binary_ and _batch_. The Kafka protocol binding does not
+currently support the batch content mode. Every compliant implementation SHOULD
+support both structured and binary modes.
+
+The specification defines three content modes for transferring events:
+_structured_, _binary_ and _batch_. The Kafka protocol binding does not
+currently support the _batch_ content mode.
 
 In the _structured_ content mode, event metadata attributes and event data are
 placed into the Kafka message value section using an
diff --git a/cloudevents/bindings/mqtt-protocol-binding.md b/cloudevents/bindings/mqtt-protocol-binding.md
@@ -49,8 +49,10 @@ MQTT PUBLISH messages ([3.1.1][3-publish], [5.0][5-publish]).
 
 ### 1.3. Content Modes
 
-The specification defines two content modes for transferring events:
-_structured_ and _binary_.
+The CloudEvents specification defines three content modes for transferring
+events: _structured_, _binary_ and _batch_. The MQTT protocol binding does not
+currently support the batch content mode. Every compliant implementation SHOULD
+support both structured and binary modes.
 
 The _binary_ mode _only_ applies to MQTT 5.0, because of MQTT 3.1.1's lack of
 support for custom metadata.
diff --git a/cloudevents/bindings/nats-protocol-binding.md b/cloudevents/bindings/nats-protocol-binding.md
@@ -50,8 +50,10 @@ the NATS protocol as client messages that are [produced][nats-pub-proto] and
 
 ### 1.3 Content Modes
 
-This specification defines two content modes for transferring events: _binary_
-and _structured_.
+The CloudEvents specification defines three content modes for transferring
+events: _structured_, _binary_ and _batch_. The NATS protocol binding does not
+currently support the batch content mode. Every compliant implementation SHOULD
+support both structured and binary modes.
 
 In the _binary_ content mode, event metadata attributes are placed in message
 headers and the event data are placed in the NATS message payload. Binary mode
diff --git a/cloudevents/bindings/websockets-protocol-binding.md b/cloudevents/bindings/websockets-protocol-binding.md
@@ -53,8 +53,8 @@ format][ce-event-format].
 
 ### 1.3. Content Modes
 
-The [CloudEvents specification][ce-message] defines two content modes for
-transferring events: _structured_ and _binary_.
+The [CloudEvents specification][ce-message] defines three content modes for
+transferring events: _structured_, _binary_ and _batch_.
 
 Because of the nature of WebSockets messages, this specification supports only
 _structured_ data mode, hence event metadata attributes and event data are
diff --git a/cloudevents/formats/avro-format.md b/cloudevents/formats/avro-format.md
@@ -27,6 +27,8 @@ This specification does not define an envelope format. The Avro type system's
 intent is primarily to provide a consistent type system for Avro itself and not
 for message payloads.
 
+The Avro event format does not currently define a batch mode format.
+
 ### 1.1. Conformance
 
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
diff --git a/cloudevents/formats/json-format.md b/cloudevents/formats/json-format.md
@@ -423,11 +423,6 @@ 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][json-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.
-
 ### 4.1. Mapping CloudEvents
 
 This section defines how a batch of CloudEvents is mapped to JSON.
diff --git a/cloudevents/formats/protobuf-format.md b/cloudevents/formats/protobuf-format.md
@@ -135,12 +135,9 @@ Transports that support content identification MUST use the following designatio
 
 ## 5. Batch Format
 
-Batch format allows for a set of CloudEvents to be represented, no relationship
-between those events is implied.
-
-Although the _protobuf batch format_ builds on the _protobuf format_ it is considered
-separate, that is to say that support of _protobuf format_ does not indicate support
-of the batch representation. The batch format MUST only be used where supported.
+In the _Protobuf Batch Format_ several CloudEvents are batched into a single Protobuf
+message. The message contains a repeated field filled with independent CloudEvent messages
+in the structured mode Protobuf event format.
 
 ### 5.1 Envelope
 
@@ -242,7 +239,6 @@ private static Spec.CloudEvent protoExample() {
 [proto-wellknown]: https://developers.google.com/protocol-buffers/docs/reference/google.protobuf
 [proto-timestamp]: https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp
 [proto-schema]: ./cloudevents.proto
-[json-format]: ./json-format.md
 [ce]: ../spec.md
 [ce-types]: ../spec.md#type-system
 [rfc2119]: https://tools.ietf.org/html/rfc2119
diff --git a/cloudevents/spec.md b/cloudevents/spec.md
@@ -124,12 +124,15 @@ Stand-alone event formats, such as the [JSON format](formats/json-format.md),
 specify serialization independent of any protocol or storage medium. Protocol
 Bindings MAY define formats that are dependent on the protocol.
 
+Each Event Format MUST define a structured-mode representation, and MAY define
+a batch-mode representation.
+
 #### Message
 
 Events are transported from a source to a destination via messages.
 
 A "structured-mode message" is one where the entire event (attributes and data)
-are encoded in the message body.
+are encoded in the message body, according to a specific event format.
 
 A "binary-mode message" is one where the event data is stored in the message
 body, and event attributes are stored as part of message metadata.
@@ -142,6 +145,10 @@ metadata typically allows for extension attributes. In other words, a binary
 formatted CloudEvent would work for both a CloudEvents enabled receiver as well
 as one that is unaware of CloudEvents.
 
+A "batch-mode message" is one where multiple (zero or more) events are
+encoded in a single message body, according to a specific event format. Not
+all event formats or protocol bindings support batch-mode messages.
+
 #### Protocol
 
 Messages can be delivered through various industry standard protocol (e.g. HTTP,
diff --git a/cloudevents/working-drafts/xml-format.md b/cloudevents/working-drafts/xml-format.md
@@ -209,11 +209,6 @@ In the _XML Batch Format_ several CloudEvents are batched into a single XML
 The `<event>` element MUST NOT contain any direct child text nodes with non-whitespace
 content.
 
-Although the _XML Batch Format_ builds on top of the _XML Format_, it is
-considered as a separate format: a valid implementation of the _XML Format_
-doesn't need to support it. The _XML Batch Format_ MUST NOT be used when only
-support for the _XML Format_ is indicated.
-
 An XML Batch of CloudEvents MUST use the media type
 `application/cloudevents-batch+xml`.
 
