add Attribute Categories section #139
Conversation
|
@markfisher you'll need to sign your commit so the DCO check passes |
|
We're gonna have to figure out how to deal with the use of RFC keywords.... I wonder if an easy out is to put this into the README, or even into the extensions.md doc. Need to think about this one. |
| specification will fall into three categories: | ||
| - required | ||
| - optional | ||
| - extensions |
There was a problem hiding this comment.
nit: we seem to be dividing extensions into two categories as well:
- Registered extensions that vendors publish to encourage interoperability of a use case
- Private extensions
This concept was taken directly from the JWT spec where private claims may be registered claims.
There was a problem hiding this comment.
true - I guess originally I was thinking that we'd just talk about the stuff that might appear in our docs, but you're right, we should mention that people can do "other extensions" that this WG has no knowledge of.
| itself. For example those attributes may relate to the source, the content type, | ||
| the time the event occurred, or any identifying information. Attributes that are | ||
| relevant only for certain contexts within which the event may be used will be in | ||
| the extensions category. Examples might include grouping, sampling, correlation, |
There was a problem hiding this comment.
I'm not sure I take for granted that these are extensions cases, and if they were they should certainly be registered extensions. These are all cases where multiple parts of a distributed stack need to interoperate to work correctly.
|
@markfisher will you have time to finish this one up? if not, I can try to find someone else to run with it. |
|
@duglin I can handle it. Did you decide if you'd prefer to keep it here but avoid RFC keywords or whether we should move it to the README? |
|
My preference would be to move it out of the spec since explaining what goes into each doc is broader than that one doc (meaning the spec). |
|
Perhaps we need some kind of Primer doc as an intro that explains all of the pieces. |
|
actually a Primer doc would be a good place for the Usage Scenarios section: https://github.com/cloudevents/spec/blob/master/spec.md#usage-scenarios - it feels out of place in the spec to me |
|
@duglin if you want to create an initial Primer doc, I can resubmit the PR to add to that instead. |
|
if #238 is adopted then I think it should cover this |
|
agreed @duglin |
The added section describes the different categories of attributes (required, optional, and extensions) and provides general criteria for an attribute's inclusion in a given category.
The text was originally based off of this suggestion from @duglin: master...duglin:propguidelines