feat: add the recordedtime extension attribute (cloudevents#1201)

* feat: add `recordedtime` extension attribute

This extension defines an attribute that represents the time when an occurrence
was recorded in a particular event, i.e. the time when the CloudEvent was
created by a producer.

This enables bitemporal data to be represented with CloudEvents which enables
several use cases described in the specification of the extension attribute.

Signed-off-by: Iwan Aucamp <[email protected]>

* changes for review comments

- Mark the attribute as REQUIRED
- Fix a broken sentence
- Removed terminology section as it just repeats what was already
  established earlier.

Signed-off-by: Iwan Aucamp <[email protected]>

* Add constraint for relation to occurence time

Given ideal clocks, and given causality holds, occurences should always
be recorded at or after the time of the occurence. But as we don't have
ideal clocks, and might not have causality, it is best to just make this
a loose requirement (i.e. SHOULD) rather than a hard requirement (i.e.
MUST).

Signed-off-by: Iwan Aucamp <[email protected]>

---------

Signed-off-by: Iwan Aucamp <[email protected]>

cloudevents/documented-extensions.md

@@ -43,5 +43,6 @@ for more information.
 - [Dataref (Claim Check Pattern)](extensions/dataref.md)
 - [Distributed Tracing](extensions/distributed-tracing.md)
 - [Partitioning](extensions/partitioning.md)
+- [Recorded Time](extensions/recordedtime.md)
 - [Sampling](extensions/sampledrate.md)
 - [Sequence](extensions/sequence.md)

cloudevents/extensions/recordedtime.md

@@ -0,0 +1,69 @@
+# Recorded Time Extension
+
+This extension defines an attribute that represents the time when an
+[_occurrence_](../spec.md#occurrence)
+was recorded in a particular
+[_event_](../spec.md#event),
+which is the time when the CloudEvent was created by a producer.
+
+This attribute is distinct from the [`time`
+attribute](https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#time),
+which, according to the CloudEvents specification, SHOULD be the time when the
+occurrence happened, if it can be determined.
+
+This attribute makes it possible to represent
+[bitemporal](https://en.wikipedia.org/wiki/Bitemporal_modeling) data with
+CloudEvents so that, for every event, both of the following times can be known
+by consumers:
+
+- _Occurrence time_: timestamp of when the occurrence recorded in the event
+  happened, which corresponds to the `time` attribute.
+- _Recorded time_: the timestamp of when the occurrence was recorded in a
+  specific CloudEvent instance, which is represented by this extension.
+
+## Attributes
+
+### recordedtime
+
+- Type: `Timestamp`
+- Description: Timestamp of when the occurrence was recorded in this CloudEvent,
+  i.e. when the CloudEvent was created by a producer.
+- Constraints:
+  - REQUIRED
+  - If present, MUST adhere to the format specified in
+    [RFC 3339](https://tools.ietf.org/html/rfc3339)
+  - SHOULD be equal to or later than the _occurrence time_.
+
+## Usage
+
+When this extension is used, producers MUST set the value of the `recordedtime`
+attribute to the timestamp of when they create the owning CloudEvent.
+
+If the same occurrence MUST be recorded differently, or the event data or
+attributes of a previous record of the occurrence MUST be amended or redacted,
+then the new CloudEvent with the necessary changes SHOULD have a different
+`recordedtime` attribute value than the previous record of the occurrence.
+
+Intermediaries MUST NOT change the value of the `recordedtime` attribute.
+
+## Use cases
+
+Examples of when an occurrence might need to be recorded differently are:
+
+- When incompatible changes to the event data schema are made, and there are
+  systems that can only process the new schema.
+- When a previous record contains incorrect information.
+- When a previous record contains personal information that can no longer be
+  kept because of regulatory or statutory reasons and needs to be redacted.
+
+Having bitemporal data makes it easier to get reproducible datasets for
+analytics and data science, as the datasets can be created by placing
+constraints on both the `time` and `recordedtime` attributes of events.
+
+Knowing when an occurrence was recorded in a particular event also makes it
+possible to determine latency between event producers and consumers. It also
+makes it possible to do operations which are sensitive to the time when an event
+was recorded, such as capturing events into time-intervalled files.
+
+The recorded time also makes it easier to differentiate different records of the
+same occurrence in analytical data stores.

cloudevents/languages/he/extensions/recordedtime.md

@@ -0,0 +1,2 @@
+# Recorded Time Extension
+מסמך זה טרם תורגם. בבקשה תשתמשו [בגרסה האנגלית של המסמך](../../../extensions/recordedtime.md) לבינתיים.

cloudevents/languages/zh-CN/extensions/recordedtime.md

@@ -0,0 +1,6 @@
+# Recorded Time Extension
+
+本文档尚未被翻译，请先阅读英文[原版文档](../../../extensions/recordedtime.md) 。
+
+如果您迫切地需要此文档的中文翻译，请[提交一个issue](https://github.com/cloudevents/spec/issues) ，
+我们会尽快安排专人进行翻译。