diff --git a/documented-extensions.md b/documented-extensions.md index 485953dc1..fe8232203 100644 --- a/documented-extensions.md +++ b/documented-extensions.md @@ -45,3 +45,4 @@ As a convention, extensions of scalar types (e.g. `String`, `Binary`, `URI`, * [Distributed Tracing](extensions/distributed-tracing.md) * [Sampling](extensions/sampled-rate.md) +* [Sequence](extensions/sequence.md) diff --git a/extensions/sequence.md b/extensions/sequence.md new file mode 100644 index 000000000..5cec023f8 --- /dev/null +++ b/extensions/sequence.md @@ -0,0 +1,46 @@ +# Sequence + +This extension defines two attributes that can be included within a CloudEvent +to describe the position of an event in the ordered sequence of events produced +by a unique event source. + +The `sequence` attribute represents the value of this event's +order in the stream of events. The exact value and meaning of this +attribute is defined by the `sequenceType` attribute. +If the `sequenceType` is missing, or not defined in this specification, +event consumers will need to have some out-of-band communication with the +event producer to understand how to interpret the value of the attribute. + +## Attributes + +### sequence +* Type: `String` +* Description: Value expressing the relative order of the event. This enables + interpretation of data supercedence. +* Constraints + * REQUIRED + * MUST be a non-empty lexicographically-orderable string + * RECOMMENDED as monotonically increasing and contiguous + +### sequenceType +* Type: `String` +* Description: Specifies the semantics of the sequence attribute. + See the [SequenceType Values](#sequencetype-values) section for more + information. +* Constraints: + * OPTIONAL + * If present, MUST be a non-empty string + +## SequenceType Values + +This specification defines the following values for `sequenceType`. +Additional values MAY be defined by other specifications. + +### Integer +If the `sequenceType` is set to `Integer`, the `sequence` attribute has +the following semantics: +* The values of `sequence` are string-encoded signed 32-bit Integers. +* The sequence MUST start with a value of `1` and increase by `1` for each + subsequent value (i.e. be contiguous and monotonically increasing). +* The sequence wraps around from 2,147,483,647 (2^31 -1) to + -2,147,483,648 (-2^31).