cloudevents · duglin · Mar 29, 2018 · Mar 19, 2018 · Mar 19, 2018 · Mar 21, 2018
diff --git a/spec.md b/spec.md
@@ -48,6 +48,172 @@ The following will not be part of the specification:
 * Language-specific runtime APIs
 * Selecting a single identity/access control system
 
+## Usage Scenarios
+
+The list below enumerates key usage scenarios and developer perspectives
+that have been considered for the development of this specification.
+These usage scenarios are by no means exhaustive, and the specification
+does not aim to be prescriptive about usage.
+
+These scenarios are not normative; anyone is free to create a system that
+mixes these scenarios. These cases establish a common vocabulary of event
+producer, consumer, middleware, and framework.
+
+In these scenarios, we keep the roles of event producer and event consumer
+distinct. A single application context can always take on multiple roles
+concurrently, including being both a producer and a consumer of events.
+
+1) Applications produce events for consumption by other parties, for instance
+   for providing consumers with insights about end-user activities, state
+   changes or environment observations, or for allowing complementing the
+   application's capabilities with event-driven extensions.
+
+   Events are typically produced related to a context or a producer-chosen
+   classification. For example, a temperature sensor in a room might be
+   context-qualified by mount position, room, floor, and building. A sports
+   result might be classified by league and team.
+
+   The producer application could run anywhere, such as on a server or a device.
+
+   The produced events might be rendered and emitted directly by the producer
+   or by an intermediary; as example for the latter, consider event data
+   transmitted by a device over payload-size-constrained networks such as
+   LoRaWAN or ModBus, and where events compliant to this
+   specification will be rendered by a network gateway on behalf of the
+   producer.
+
+   For example, a weather station transmits a 12-byte, proprietary event
+   payload indicating weather conditions once every 5 minutes over LoRaWAN. A
+   LoRaWAN gateway is then used to publish the event to an Internet destination
+   in the Cloud Events format. The LoRaWAN gateway is the event producer,
+   publishing on behalf of the weather station, and will set event metadata
+   appropriately to reflect the source of the event.
+
+2) Applications consume events for the purposes such as display, archival,
+   analytics, workflow processing, monitoring the condition and/or providing
+   transparency into the operation of a business solution and its foundational
+   building blocks.
+
+   The consumer application could run anywhere, such as on a server or a
+   device.
+
+   A consuming application will typically be interested in:
+   - distinguishing events such that the exact same event is not
+     processed twice.
+   - identifying and selecting the origin context or the
+     producer-assigned classification.
+   - identifying the temporal order of the events relative to the
+     originating context and/or relative to a wall-clock.
+   - understanding the context-related detail information carried
+     in the event.
+   - correlating event instances from multiple event producers and send
+     them to the same consumer context.
+
+   In some cases, the consuming application might be interested in:
+   - obtaining further details about the event's subject from the
+     originating context, like obtaining detail information about a
+     changed object that requires privileged access authorization.
+     For example, a HR solution might only publish very limited
+     information in events for privacy reasons, and any event consumer
+     needing more data will have to obtain details related to the event
+     from the HR system under their own authorization context.
+   - interact with the event's subject at the originating context,
+     for instance reading a storage blob after having been informed
+     that this blob has just been created.
+
+   Consumer interests motivate requirements for which information
+   producers ought to include an event.
+
+3) Middleware routes events from producers to consumers, or onwards
+   to other middleware. Applications producing events might delegate
+   certain tasks arising from their consumers' requirements to
+   middleware:
+
+   - Management of many concurrent interested consumers for one of
+     multiple classes or originating contexts of events
+   - Processing of filter conditions over a class or originating context
+     of events on behalf of consumers.
+   - Transcoding, like encoding in MsgPack after decoding from JSON
+   - Transformation that changes the event's structure, like mapping from
+     a proprietary format to Cloud Events, while preserving the
+     identity and semantic integrity of the event.
+   - Instant "push-style" delivery to interested consumers.
+   - Storing events for eventual delivery, either for pick-up initiated
+     by the consumer ("pull"), or initiated by the middleware ("push")
+     after a delay.
+   - Observing event content or event flow for monitoring or
+     diagnostics purposes.
+
+   To satisfy these needs, middleware will be interested in:
+   - A metadata discriminator usable for classification or
+     contextualization of events so that consumers can express interest
+     in one or multiple such classes or contexts.
+     For instance, a consumer might be interested in all events related
+     to a specific directory inside a file storage account.
+   - A metadata discriminator that allows distinguishing the subject of
+     a particular event of that class or context.
+     For instance, a consumer might want to filter out all events related
+     to new files ending with ".jpg" (the file name being the "new file"
+     event's subject) for the context describing specific directory
+     inside a file storage account that it has registered interest on.
+   - An indicator for the encoding of the event and its data.
+   - An indicator for the structural layout (schema) for the event and
+     its data.
+
+   Whether its events are available for consumption via a middleware is
+   a delegation choice of the producer.
+
+   In practice, middleware can take on role of a producer when it changes
+   the semantic meaning of an event, a consumer when it takes action based
+   on an event, or middleware when it routes events without making semantic
+   changes.
+
+4) Frameworks and other abstractions make interactions with event platform
+   infrastructure simpler, and often provide common API surface areas
+   for multiple event platform infrastructures.
+
+   Frameworks are often used for turning events into an object graph,
+   and to dispatch the event to some specific handling user-code or
+   user-rule that permits the consuming application to react to
+   a particular kind of occurrence in the originating context and
+   on a particular subject.
+
+   Frameworks are most interested in semantic metadata commonality
+   across the platforms they abstract, so that similar activities can
+   be handled uniformly.
+
+   For a sports application, a developer using the framework might be
+   interested in all events from today's game (subject) of a team in a
+   league (topic of interest), but wanting to handle reports
+   of "goal" differently than reports of "substitution".
+   For this, the framework will need a suitable metadata discriminator
+   that frees it from having to understand the event details.
+
+## Status
+At this time the specification is focused on the following scope:
+
+* Agree upon a set of event metadata attributes (“context”) that:
+  * Offer a basic description of the event and the data it carries.
+  * Are currently implemented and semantically similar across multiple
+    platforms.
+  * Can be delivered separately from the event data in the transport headers
+    (e.g. HTTP, AMQP, Kafka) or together with the data in a serialized fashion
+    (e.g. JSON, protobuf, Avro).
+  * Include a description of the transport/protocol and encoding, with an
+    initial focus on HTTP.
+  * Can be extended to support experimental or uncommon features, while being
+    clearly indicated as an extension (e.g. extensions use a common prefix).
+  * Allow for evolution of both the payload and CloudEvents definition (e.g.
+    versioning).
+  * Can be embedded at different stages along the route of the event by
+    middleware (e.g. a router can add transport or auth information).
+* Establish a backlog of prospective event metadata attributes (“context”)
+  for potential inclusion in the future.
+* Include use-case examples to help users understand the value of CloudEvents,
+  with an initial focus on HTTP and Functions-as-a-Service/Serverless computing.
+* Determine process and overall governance of the specification.
+* Discuss additional architecture components that complement this specification.
+
 ## Notations and Terminology
 
 ### Notational Conventions