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

add Attribute Categories section #139

Closed
wants to merge 1 commit into from
Closed

add Attribute Categories section #139

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
26 changes: 25 additions & 1 deletion spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -194,6 +194,31 @@ concurrently, including being both a producer and a consumer of events.
For this, the framework will need a suitable metadata discriminator
that frees it from having to understand the event details.

## Attribute Categories

The number of metadata attributes will be constrained to the minimal set needed
to achieve the stated goals. To that end, attributes defined by this
specification will fall into three categories:
- required
- optional
- extensions
Copy link
Contributor

Choose a reason for hiding this comment

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

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.

Copy link
Collaborator

Choose a reason for hiding this comment

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

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.


As the category names imply, "required" attributes will be the ones that are
considered vital to all events in all use cases, while "optional" ones will be
used in a majority of use cases. If an attribute is not common enough to fall
into those two categories but would still benefit from the level of
interoperability that comes from being well-defined, then it will be placed into
the "extensions" category and described in the (extensions)[extensions.md]
document. The spec will define how these extension attributes will appear within
a CloudEvent.

Core attributes, whether required or optional, are those that describe the event
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,
Copy link
Contributor

Choose a reason for hiding this comment

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

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.

and tracing.

## Status
At this time the specification is focused on the following scope:

Expand Down Expand Up @@ -399,4 +424,3 @@ that contains both context and data).
serverless function which listens on the source event, opens a connection to
the destination protocol and maps every incoming event (received through
event API) to an event message over the destination protocol.