Skip to content

Commit

Permalink
Clarify interoperability of extensions (cloudevents#508)
Browse files Browse the repository at this point in the history
Minor clarification to #type-system.

Deleted confusing and non-normative section on extension serialization.
The discussion of "serialization locations" and "general patterns of extension
serialization" is specific to the HTTP, AMQP and JSON bindings/formats and may
not apply to future bindings/formats.

An event serialization MUST describe how to encode/decode an abstract event
correctly, that's all. This spec should not constrain what that looks like on
the wire. It's up to other specs (HTTP, AMQP etc.) to do that.

Signed-off-by: Alan Conway <aconway@redhat.com>
  • Loading branch information
alanconway committed Sep 20, 2019
1 parent f41061e commit f0049cd
Showing 1 changed file with 10 additions and 26 deletions.
36 changes: 10 additions & 26 deletions spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,13 +193,15 @@ string-encoding for each type that MUST be supported by all implementations.
- `Timestamp` - Date and time expression using the Gregorian Calendar.
- String encoding: [RFC 3339](https://tools.ietf.org/html/rfc3339).

All content attributes MUST be of scalar type (e.g. string, integer)
that have a string-encoding defined. They MUST NOT be of complex type
(e.g. structures, map).
All context attribute values MUST be of one of the types listed above.

A strongly-typed programming model that represents a CloudEvent or any extension
MUST be able to convert from and to the canonical string-encoding to the
runtime/language native type that best corresponds to the abstract type.
A programming model that represents a CloudEvent or any extension MUST be able
to convert between the canonical string-encoding and the runtime/language native
type that best corresponds to the abstract type.

Attribute values MAY be presented as native types or canonical strings.
Extension attribute values presented as strings MUST use the canonical
string-encoding to avoid potential ambiguity with other string encodings.

For example, the `time` attribute might be represented by the language's native
_datetime_ type in a given implementation, but it MUST be settable providing an
Expand All @@ -218,7 +220,7 @@ language/runtime types at the producer and consumer ends, and never materialize
as a string.

The choice of serialization mechanism will determine how the context attributes
and the event data will be materialized. For example, in the case of a JSON
and the event data will be serialized. For example, in the case of a JSON
serialization, the context attributes and the event data might both appear
within the same JSON object.

Expand Down Expand Up @@ -419,25 +421,7 @@ the set of known extensions - not just for possible name conflicts but for
extensions that might be of interest.

Each specification that defines how to serialize a CloudEvent will define how
extension attributes will appear.

Extension attribtue MUST be serialized using the same general pattern as all
CloudEvents context attributes. For example, in binary HTTP, that means they
MUST appear as HTTP headers with the `ce-` prefix. The specification of an
attribute MAY define a secondary serialization where the data is duplicated
in some other location within the message.

In cases where a secondary serialization is defined, the extension
specification MUST also state what a receiver of the CloudEvent is to do
if the data differs between those two serialization locations. Additionally,
senders need to be prepared for intermediaries, and receivers, to not
know about their extension and therefore the specialized serialization version
version will most likely not be processed as a CloudEvent extension attribute.

Many transports support the ability for senders to include additonal metadata,
for example as HTTP headers. While a CloudEvents receiver is not mandated to
process and pass them along, it is RECOMMENDED that they do so via some
mechanism that makes it clear they are non-CloudEvents metadata.
extension attributes will be serialized.

Here is an example that illustrates the need for additional attributes. In many
IoT and enterprise use cases, an event could be used in a serverless application
Expand Down

0 comments on commit f0049cd

Please sign in to comment.