From 98ae14b9892729bbd9982eaa854a46d1ea60ed3e Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Wed, 13 Jul 2022 12:33:55 +0000 Subject: [PATCH] Clean-up of Sequence Signed-off-by: Doug Davis --- cloudevents/extensions/sequence.md | 45 ++++++++++-------------------- 1 file changed, 15 insertions(+), 30 deletions(-) diff --git a/cloudevents/extensions/sequence.md b/cloudevents/extensions/sequence.md index 1bcfd229f..341152f7a 100644 --- a/cloudevents/extensions/sequence.md +++ b/cloudevents/extensions/sequence.md @@ -1,15 +1,18 @@ # Sequence -This extension defines two attributes that can be included within a CloudEvent +This extension defines an attribute 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. +stream of events. This specification does not define the meaning or set of +valid value of this attribute, rather it only mandates that the value be +a string that can be lexicographically compared to other `sequence` values +to determine which one comes first. The `sequence` with a lower lexicographical +value comes first. + +Produces and consumers are free to define an out-of-band agreement on the +semantic meaning, or valid values, for the attribute. ## Attributes @@ -23,27 +26,9 @@ of the attribute. - 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). +The entity creating the CloudEvent MUST ensure that the `sequence` values +used are formatted such that across the entire set of values used a receiver +can determine the order of the events via a simple string-compare type of +operation. This means that it might be necessary for the value to include +some kind of padding (e.g. leading zeros in the case of the value being the +string representation of an integer).