From 6a0014ba86e3bc6d9d8d326ee3e12628cc332505 Mon Sep 17 00:00:00 2001 From: Clemens Vasters Date: Tue, 19 Mar 2019 10:20:17 +0100 Subject: [PATCH 1/3] Introducing "subject" Signed-off-by: Clemens Vasters --- spec.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/spec.md b/spec.md index 5be89012a..bb7d41e5c 100644 --- a/spec.md +++ b/spec.md @@ -201,6 +201,30 @@ within the same JSON object. - urn:event:from:myapi/resourse/123 - mailto:cncf-wg-serverless@lists.cncf.io +### subject +* Type: `String` +* Description: This describes the subject of the event in the context of the + event producer (identified by `source`). In publish-subscribe scenarios, + a subscriber will typically subscribe to events emitted by a `source`, + but the `source` identifier alone might not be sufficient as a qualifier for + any specific event if the `source` context has internal sub-structure. +* Example: A subscriber might register interest for when new blobs are created + inside a blob-storage container. In this case, the event `source` identifies + the subscription scope (storage container), the `type` identifies the "blob + created" event, and the `id` uniquely identifies the event instance to + distinguish separate occurrences of a same-named blog having been created; + the name of the newly created blob is carried in `subject`. + + Identifying the subject of the event in context metadata (opposed to only in + the `data` payload) is particularly helpful in generic subscription filtering + scenarios where middleware is unable to interpret the `data` content. In the + above example, the subscriber might only be interested in blobs with names + ending with '.jpg' or '.jpeg' and the subject attribute allows for constructing + a simple and efficient string-suffix filter for that subset of events. +* Constraints: + * OPTIONAL + * MUST be a non-empty string + ### id - Type: `String` From 41c5d1468db22d3ef996966769de039bfef2bcf7 Mon Sep 17 00:00:00 2001 From: Clemens Vasters Date: Thu, 4 Apr 2019 09:09:43 +0200 Subject: [PATCH 2/3] typo fix Signed-off-by: Clemens Vasters --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index bb7d41e5c..5d9a2c820 100644 --- a/spec.md +++ b/spec.md @@ -212,7 +212,7 @@ within the same JSON object. inside a blob-storage container. In this case, the event `source` identifies the subscription scope (storage container), the `type` identifies the "blob created" event, and the `id` uniquely identifies the event instance to - distinguish separate occurrences of a same-named blog having been created; + distinguish separate occurrences of a same-named blob having been created; the name of the newly created blob is carried in `subject`. Identifying the subject of the event in context metadata (opposed to only in From d394d69dc505acc12370571bb3b1529a9dd4ee82 Mon Sep 17 00:00:00 2001 From: Clemens Vasters Date: Thu, 4 Apr 2019 10:22:11 +0200 Subject: [PATCH 3/3] fixup of source/subject references Signed-off-by: Clemens Vasters --- spec.md | 52 ++++++++++++++++++++++++++++------------------------ 1 file changed, 28 insertions(+), 24 deletions(-) diff --git a/spec.md b/spec.md index 5d9a2c820..dd24af737 100644 --- a/spec.md +++ b/spec.md @@ -1,4 +1,4 @@ -# CloudEvents - Version 0.2 +# CloudEvents - Version 0.2 ## Abstract @@ -186,20 +186,19 @@ within the same JSON object. - MUST be a non-empty string ### source - -- Type: `URI-reference` -- Description: This describes the event producer. Often this will include - information such as the type of the event source, the organization publishing - the event, the process that produced the event, and some unique identifiers. - The exact syntax and semantics behind the data encoded in the URI is event - producer defined. -- Constraints: - - REQUIRED -- Examples - - https://github.com/cloudevents/spec/pull/123 - - /cloudevents/spec/pull/123 - - urn:event:from:myapi/resourse/123 - - mailto:cncf-wg-serverless@lists.cncf.io +* Type: `URI-reference` +* Description: This describes the event producer. Often this will include + information such as the type of the event source, the organization + publishing the event, the process that produced the event, and some unique + identifiers. The exact syntax and semantics behind the data encoded in the URI + is event producer defined. +* Constraints: + * REQUIRED +* Examples + * https://github.com/cloudevents/spec/pull + * /cloudevents/spec/pull + * urn:event:from:myapi/resource + * mailto:cncf-wg-serverless@lists.cncf.io ### subject * Type: `String` @@ -208,22 +207,26 @@ within the same JSON object. a subscriber will typically subscribe to events emitted by a `source`, but the `source` identifier alone might not be sufficient as a qualifier for any specific event if the `source` context has internal sub-structure. -* Example: A subscriber might register interest for when new blobs are created - inside a blob-storage container. In this case, the event `source` identifies - the subscription scope (storage container), the `type` identifies the "blob - created" event, and the `id` uniquely identifies the event instance to - distinguish separate occurrences of a same-named blob having been created; - the name of the newly created blob is carried in `subject`. Identifying the subject of the event in context metadata (opposed to only in the `data` payload) is particularly helpful in generic subscription filtering scenarios where middleware is unable to interpret the `data` content. In the above example, the subscriber might only be interested in blobs with names - ending with '.jpg' or '.jpeg' and the subject attribute allows for constructing - a simple and efficient string-suffix filter for that subset of events. + ending with '.jpg' or '.jpeg' and the subject attribute allows for + constructing a simple and efficient string-suffix filter for that subset of + events. * Constraints: * OPTIONAL * MUST be a non-empty string +* Example: + * A subscriber might register interest for when new blobs are created + inside a blob-storage container. In this case, the event `source` identifies + the subscription scope (storage container), the `type` identifies the "blob + created" event, and the `id` uniquely identifies the event instance to + distinguish separate occurrences of a same-named blob having been created; + the name of the newly created blob is carried in `subject`: + * `source`: https://example.com/storage/tenant/container + * `subject`: mynewfile.jpg ### id @@ -396,7 +399,8 @@ The following example shows a CloudEvent serialized as JSON: { "specversion" : "0.2", "type" : "com.github.pull.create", - "source" : "https://github.com/cloudevents/spec/pull/123", + "source" : "https://github.com/cloudevents/spec/pull", + "subject" : "123", "id" : "A234-1234-1234", "time" : "2018-04-05T17:31:00Z", "comexampleextension1" : "value",