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 Oct 10, 2019
1 parent 5aa00c3 commit f72f2c2
Showing 1 changed file with 13 additions and 27 deletions.
40 changes: 13 additions & 27 deletions spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -192,13 +192,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 context 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 @@ -217,7 +219,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 @@ -416,26 +418,10 @@ extension authors SHOULD check the
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 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.
Each specification that defines how to serialize a CloudEvent MUST define clear
and unambiguous rules for serializing extension attributes. Serialization MAY
replace a strongly-typed extension attribute value with its canonical string
representation.

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 f72f2c2

Please sign in to comment.