Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Introducing "subject" #406

Merged
merged 3 commits into from
Apr 10, 2019
+44 −16
Merged

Introducing "subject" #406

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6a0014b
Introducing "subject"
Mar 19, 2019
41c5d14
typo fix
Apr 4, 2019
d394d69
fixup of source/subject references
Apr 4, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 44 additions & 16 deletions spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# CloudEvents - Version 0.2
# CloudEvents - Version 0.2
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

weird

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The updated version adds a extra whitespace to the end of 0.2.


## Abstract

Expand Down Expand Up @@ -186,20 +186,47 @@ 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:[email protected]
* Type: `URI-reference`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

- is more clear than * that it is suppose to be a list. The rest of the spec uses -

* 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:[email protected]

### subject
* Type: `String`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps Subject is a URIRef? and it relates to the source uri?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's some sort of subject identifier. I can be a filename or just some name of a thing that the source knows. I wouldn't constrain that as much as source.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

URIRef does all:

this is a valid uri ref

http://so.is/this

* 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.

Identifying the subject of the event in context metadata (opposed to only in
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For source, we have these examples:

Would using subject turn them into:

* source: https://github.com/cloudevents/spec/
* subject: pull/123

* source: /cloudevents/spec/pull/123
* subject: pull/123

* source: urn:event:from:myapi/resourse/123
* subject: UPDATE `<-- ? picked a verb`

* source: mailto:[email protected]
* subject: Help

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The last example bring the point home rather nicely. That's exactly what subject is.

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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/subject/subject/

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this paragraph. Would it be helpful to add something about how putting this info into the "source" URI is just as hard to parse/filter-on ? And that's why we creating this property. Before this property I think people were pushed towards merging it into 'source' - if they wanted it outside of 'data'. Or, if this is too much text for the spec, perhaps in the primer?

constructing a simple and efficient string-suffix filter for that subset of
events.
* Constraints:
* OPTIONAL
* MUST be a non-empty string
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If Present, MUST be a non-empty string

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no pushy?

* Example:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this example because it shows how all of the key properties relate to each other, and better explains what people should expect in each. So, can we move this example out from under the definition of this one property so it can be view in the bigger context? And then show "id" and "type" too - or even a total CE.

* 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

Expand Down Expand Up @@ -372,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",
Expand Down