From 169b1e823d77d5a6296dd32a442f6dac0e5f73f3 Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Thu, 16 Aug 2018 08:37:24 -0700 Subject: [PATCH 1/4] Add 'ordinal' attribute Fixes: #191 I didn't address any of the comments in #191 because I wasn't sure how the WG in general felt about them. So please speak up in this PR if you'd like to see a change. Signed-off-by: Doug Davis --- documented-extensions.md | 1 + extensions/ordinal.md | 15 +++++++++++++++ 2 files changed, 16 insertions(+) create mode 100644 extensions/ordinal.md diff --git a/documented-extensions.md b/documented-extensions.md index 485953dc1..702c2674b 100644 --- a/documented-extensions.md +++ b/documented-extensions.md @@ -44,4 +44,5 @@ As a convention, extensions of scalar types (e.g. `String`, `Binary`, `URI`, ## Known Extensions * [Distributed Tracing](extensions/distributed-tracing.md) +* [Ordinal](extensions/ordinal.md) * [Sampling](extensions/sampled-rate.md) diff --git a/extensions/ordinal.md b/extensions/ordinal.md new file mode 100644 index 000000000..1b936181d --- /dev/null +++ b/extensions/ordinal.md @@ -0,0 +1,15 @@ +# Ordinal + +This extension defines an attribute that can be included within a CloudEvent +to represent the ordinal position of the event relative to the other events +from the same event source. + +## Attributes +### ordinal +* 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 + From 008f59880881691ee43e2fa779efeb3ce88b1347 Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Mon, 3 Sep 2018 02:51:10 -0700 Subject: [PATCH 2/4] use sequence and add more clarifying text Signed-off-by: Doug Davis --- documented-extensions.md | 2 +- extensions/ordinal.md | 15 --------------- extensions/sequence.md | 19 +++++++++++++++++++ 3 files changed, 20 insertions(+), 16 deletions(-) delete mode 100644 extensions/ordinal.md create mode 100644 extensions/sequence.md diff --git a/documented-extensions.md b/documented-extensions.md index 702c2674b..fe8232203 100644 --- a/documented-extensions.md +++ b/documented-extensions.md @@ -44,5 +44,5 @@ As a convention, extensions of scalar types (e.g. `String`, `Binary`, `URI`, ## Known Extensions * [Distributed Tracing](extensions/distributed-tracing.md) -* [Ordinal](extensions/ordinal.md) * [Sampling](extensions/sampled-rate.md) +* [Sequence](extensions/sequence.md) diff --git a/extensions/ordinal.md b/extensions/ordinal.md deleted file mode 100644 index 1b936181d..000000000 --- a/extensions/ordinal.md +++ /dev/null @@ -1,15 +0,0 @@ -# Ordinal - -This extension defines an attribute that can be included within a CloudEvent -to represent the ordinal position of the event relative to the other events -from the same event source. - -## Attributes -### ordinal -* 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 - diff --git a/extensions/sequence.md b/extensions/sequence.md new file mode 100644 index 000000000..ca1791f3a --- /dev/null +++ b/extensions/sequence.md @@ -0,0 +1,19 @@ +# Sequence + +This extension defines an attribute that can be included within a CloudEvent +to represent the position of the event relative to the other events +from the same event source. The exact value and meaning of this attribute +is not defined by this specification. Event consumers will need to +have some out-of-band communication with the event producer to understand +how to interpret its value. + +## 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 contiguous + From bfcaae1e4309f6b247ab90c988c2da38d675857c Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Mon, 10 Sep 2018 05:06:01 -0700 Subject: [PATCH 3/4] grab Christoph's suggested text Signed-off-by: Doug Davis --- extensions/sequence.md | 44 ++++++++++++++++++++++++++++++++++++------ 1 file changed, 38 insertions(+), 6 deletions(-) diff --git a/extensions/sequence.md b/extensions/sequence.md index ca1791f3a..6c886f69b 100644 --- a/extensions/sequence.md +++ b/extensions/sequence.md @@ -1,13 +1,18 @@ # Sequence -This extension defines an attribute that can be included within a CloudEvent -to represent the position of the event relative to the other events -from the same event source. The exact value and meaning of this attribute -is not defined by this specification. Event consumers will need to -have some out-of-band communication with the event producer to understand -how to interpret its value. +This extension defines two attributes that can be included within a CloudEvent +to describe the position of the event relative to the other events from the +same 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 @@ -17,3 +22,30 @@ how to interpret its value. * MUST be a non-empty lexicographically-orderable string * RECOMMENDED as contiguous +### sequenceType +* Type: `String` +* Description: Defines 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 first CloudEvent in an `Integer` sequence MUST have the value + `1`, the second `2`, etc. +* The sequence MUST be contiguous. In other words, if the event consumer + receives two CloudEvents with `sequence` values of `1` and `3`, another + CloudEvent with a `sequence` value of `2` exists, but has not been received + yet. +* The sequence wraps around from 2,147,483,647 (2^31 -1) to + -2,147,483,648 (-2^31). + From f000004244f019cdee3fd3d27f815f755e82e284 Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Fri, 14 Sep 2018 06:31:36 -0700 Subject: [PATCH 4/4] more tweaks Signed-off-by: Doug Davis --- extensions/sequence.md | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/extensions/sequence.md b/extensions/sequence.md index 6c886f69b..5cec023f8 100644 --- a/extensions/sequence.md +++ b/extensions/sequence.md @@ -1,8 +1,8 @@ # Sequence This extension defines two attributes that can be included within a CloudEvent -to describe the position of the event relative to the other events from the -same event source. +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 @@ -20,11 +20,11 @@ event producer to understand how to interpret the value of the attribute. * Constraints * REQUIRED * MUST be a non-empty lexicographically-orderable string - * RECOMMENDED as contiguous + * RECOMMENDED as monotonically increasing and contiguous ### sequenceType * Type: `String` -* Description: Defines the semantics of the sequence attribute. +* Description: Specifies the semantics of the sequence attribute. See the [SequenceType Values](#sequencetype-values) section for more information. * Constraints: @@ -39,13 +39,8 @@ 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 first CloudEvent in an `Integer` sequence MUST have the value - `1`, the second `2`, etc. -* The sequence MUST be contiguous. In other words, if the event consumer - receives two CloudEvents with `sequence` values of `1` and `3`, another - CloudEvent with a `sequence` value of `2` exists, but has not been received - yet. +* 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). -