diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2064dcb49..c9d914cbd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,37 +1,37 @@ # Contributing to CloudEvents -This page contains information about reporting issues, how to suggest changes -as well as the guidelines we follow for how our documents are formatted. +This page contains information about reporting issues, how to suggest changes as +well as the guidelines we follow for how our documents are formatted. ## Table of Contents -* [Reporting an Issue](#reporting-an-issue) -* [Suggesting a Change](#suggesting-a-change) -* [Spec Formatting Conventions](#spec-formatting-conventions) + +- [Reporting an Issue](#reporting-an-issue) +- [Suggesting a Change](#suggesting-a-change) +- [Spec Formatting Conventions](#spec-formatting-conventions) ## Reporting an Issue -To report an issue, or to suggest an idea for a change that you haven't -had time to write-up yet, open an -[issue](https://github.com/cloudevents/spec/issues). It is best to check -our existing [issues](https://github.com/cloudevents/spec/issues) first -to see if a similar one has already been opened and discussed. +To report an issue, or to suggest an idea for a change that you haven't had time +to write-up yet, open an [issue](https://github.com/cloudevents/spec/issues). It +is best to check our existing +[issues](https://github.com/cloudevents/spec/issues) first to see if a similar +one has already been opened and discussed. ## Suggesting a Change -To suggest a change to this repository, submit a [pull -request](https://github.com/cloudevents/spec/pulls)(PR) with the complete +To suggest a change to this repository, submit a +[pull request](https://github.com/cloudevents/spec/pulls)(PR) with the complete set of changes you'd like to see. See the -[Spec Formatting Conventions](#spec-formatting-conventions) section for -the guidelines we follow for how documents are formatted. +[Spec Formatting Conventions](#spec-formatting-conventions) section for the +guidelines we follow for how documents are formatted. Each PR must be signed per the following section. ### Assigning and Owning work If you want to own and work on an issue, add a comment or “#dibs” it asking -about ownership. A maintainer will then add the Assigned label and modify -the first comment in the issue to include `Assigned to: @person` - +about ownership. A maintainer will then add the Assigned label and modify the +first comment in the issue to include `Assigned to: @person` ### Sign your work @@ -88,8 +88,8 @@ Use your real name (sorry, no pseudonyms or anonymous contributions.) If you set your `user.name` and `user.email` git configs, you can sign your commit automatically with `git commit -s`. -Note: If your git config information is set properly then viewing the - `git log` information for your commit will look something like this: +Note: If your git config information is set properly then viewing the `git log` +information for your commit will look something like this: ``` Author: Joe Smith @@ -100,13 +100,13 @@ Date: Thu Feb 2 11:41:15 2018 -0800 Signed-off-by: Joe Smith ``` -Notice the `Author` and `Signed-off-by` lines match. If they don't -your PR will be rejected by the automated DCO check. +Notice the `Author` and `Signed-off-by` lines match. If they don't your PR will +be rejected by the automated DCO check. ## Spec Formatting Conventions Documents in this repository will adhere to the following rules: - * Lines are wrapped at 80 columns (when possible) - * Specifications will use [RFC2119](https://tools.ietf.org/html/rfc2119) - keywords to indicate normative requirements +- Lines are wrapped at 80 columns (when possible) +- Specifications will use [RFC2119](https://tools.ietf.org/html/rfc2119) + keywords to indicate normative requirements diff --git a/GOVERNANCE.md b/GOVERNANCE.md index b1404cf4c..4cc1c1f49 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -5,121 +5,120 @@ project will manage this repository. ## Meetings -In order to provide equitable rights to all members, -the following process will be followed: - -* Official conference calls will be announced at least a week in advance. -* Official face-to-face meetings will be announced at least 4 weeks in - advance. -* Proposed changes to any document will be done via a Pull Request (PR). -* PRs will be reviewed during official meetings, but off-line reviews - (LGTMs, NOT LGTMs) and comments are strongly encouraged to gauge the - group's opinion on the proposed change prior to the meeting. -* During meetings, priority will be given to PRs that appear to be ready for - a vote over those that appear to require discussions. -* PRs should not be merged if they have had substantial changes made within - two days of the meeting. - Rebases, typo fixes, etc. do not count as substantial. - Note, administrivia PRs that do not materially modify output documents - may be processed by admins as needed. -* Resolving PRs ("merging" or "closing with no action") will be done as a - result of a motion made during a meeting, and approved. -* Reopening a PR can be done if new information is made available, and a - motion to do so is approved. -* Any motion that does not have "unanimous consent" will result in a formal +In order to provide equitable rights to all members, the following process will +be followed: + +- Official conference calls will be announced at least a week in advance. +- Official face-to-face meetings will be announced at least 4 weeks in advance. +- Proposed changes to any document will be done via a Pull Request (PR). +- PRs will be reviewed during official meetings, but off-line reviews (LGTMs, + NOT LGTMs) and comments are strongly encouraged to gauge the group's opinion + on the proposed change prior to the meeting. +- During meetings, priority will be given to PRs that appear to be ready for a + vote over those that appear to require discussions. +- PRs should not be merged if they have had substantial changes made within two + days of the meeting. Rebases, typo fixes, etc. do not count as substantial. + Note, administrivia PRs that do not materially modify output documents may be + processed by admins as needed. +- Resolving PRs ("merging" or "closing with no action") will be done as a result + of a motion made during a meeting, and approved. +- Reopening a PR can be done if new information is made available, and a motion + to do so is approved. +- Any motion that does not have "unanimous consent" will result in a formal vote. See [Voting](#voting). ## Membership There are three categories of project membership: -1 - Member. This is anyone who participates in the group's activities in any - of our communication channels (email, github issues/PRs, meetings, etc.). - No formal registration process is needed. -2 - Voting Member. See the (Voting)[#voting]section below for more information - on how the list of Voting Members are determined. During the normal - operations of the group, Voting Members and Members are the same with - respect to influence over the groups actions. The rights associated with - being a Voting Member only apply in the event of a formal vote being taken. -3 - Admin. Admins are Members of the group but have the ability to perform - administrative actions on behalf of the group. For example, manage the - website, github repos and moderate the meetings. Their actions should - be done with the knowledge and consent of the group. They also have the - ability to merge/close PRs, but only per the group's approval. See - the [OWNERS](OWNERS) file for the current list of Admins. + +1. **Member.** This is anyone who participates in the group's activities in any + of our communication channels (email, github issues/PRs, meetings, etc.). No + formal registration process is needed. + +2. **Voting Member.** See the (Voting)[#voting]section below for more + information on how the list of Voting Members are determined. During the + normal operations of the group, Voting Members and Members are the same with + respect to influence over the groups actions. The rights associated with + being a Voting Member only apply in the event of a formal vote being taken. + +3. **Admin.** Admins are Members of the group but have the ability to perform + administrative actions on behalf of the group. For example, manage the + website, github repos and moderate the meetings. Their actions should be done + with the knowledge and consent of the group. They also have the ability to + merge/close PRs, but only per the group's approval. See the [OWNERS](OWNERS) + file for the current list of Admins. ## PRs Typically, PRs are expected to meet the following criteria prior to being merged: -* The author of the PR indicates that it is ready for review by asking for it - to be discussed in an upcoming meeting - eg. by adding it to the agenda - document. -* All comments have been addressed. -* PRs that have objections/concerns will be discussed off-line by interested +- The author of the PR indicates that it is ready for review by asking for it to + be discussed in an upcoming meeting - eg. by adding it to the agenda document. +- All comments have been addressed. +- PRs that have objections/concerns will be discussed off-line by interested parties. A resolution, updated PR, will be expected from those talks. ## Voting If a vote is taken during a meeting, the follow rules will be followed: -* There is only 1 vote per participating company, or nonaffiliated individual. -* Each participating company can assign a primary and secondary representative. -* A participating company, or nonaffiliated individual, attains voting rights - by having any of the entity's assigned representative(s), in aggregate, - attend 3 out of the last 4 meetings. The people listed as "primary" or - "alternate" for an entity can be changed no more than once a month and can - be changed by notifying one of the admins. The entity obtains voting rights - after the 3rd meeting, not during. -* Only members with voting rights will be allowed to vote. -* A vote passes if more than 50% of the votes cast approve the motion. -* Only "yes" or "no" votes count, "abstain" votes do not count towards the +- There is only 1 vote per participating company, or nonaffiliated individual. +- Each participating company can assign a primary and secondary representative. +- A participating company, or nonaffiliated individual, attains voting rights by + having any of the entity's assigned representative(s), in aggregate, attend 3 + out of the last 4 meetings. The people listed as "primary" or "alternate" for + an entity can be changed no more than once a month and can be changed by + notifying one of the admins. The entity obtains voting rights after the 3rd + meeting, not during. +- Only members with voting rights will be allowed to vote. +- A vote passes if more than 50% of the votes cast approve the motion. +- Only "yes" or "no" votes count, "abstain" votes do not count towards the total. -* Meeting attendance will be formally tracked +- Meeting attendance will be formally tracked [here](https://docs.google.com/spreadsheets/d/1bw5s9sC2ggYyAiGJHEk7xm-q2KG6jyrfBy69ifkdmt0/edit#gid=0). - Members must acknowledge their presence verbally, meaning, adding yourself - to the "Attendees" section of the Agenda document is not sufficient. -* When a vote is called, unless all voting members have voted, the vote will be + Members must acknowledge their presence verbally, meaning, adding yourself to + the "Attendees" section of the Agenda document is not sufficient. +- When a vote is called, unless all voting members have voted, the vote will be tallied no less than one week after calling the vote. -* Voting process: - * Comment on the PR: "YES VOTE", "NO VOTE", or "ABSTAIN". - * Any person is encouraged to vote with a statement of support or dissent to +- Voting process: + - Comment on the PR: "YES VOTE", "NO VOTE", or "ABSTAIN". + - Any person is encouraged to vote with a statement of support or dissent to help undecided voters to reach a decision - * Comments are welcome from non-members - * Voting tally will reflect the above qualification and recorded in PR + - Comments are welcome from non-members + - Voting tally will reflect the above qualification and recorded in PR ## Release Process and Versioning The specifications produced will adhere to the following: -* The versioning scheme used will follow [semver](https://semver.org/) -* All normative specifications, and the Primer, will be grouped together into - a single logical unit and released at the same time, at the same version - number. This is true regardless of whether each individual document actually - changed during the release cycle. + +- The versioning scheme used will follow [semver](https://semver.org/) +- All normative specifications, and the Primer, will be grouped together into a + single logical unit and released at the same time, at the same version number. + This is true regardless of whether each individual document actually changed + during the release cycle. Note that these rules do not apply to the [documented extensions](documented-extensions.md). To create a new release: -* Create a PR that modifies the [README](README.md), and all specifications - (ie. \*.md files) that include a version string, to the new release - version string. -* Merge the PR. -* Create a [new release](https://github.com/cloudevents/spec/releases/new): - * Choose a "Tag version" of the form: `vX.Y`, e.g. `v0.1` - * Target should be `master`, the default value - * Release title should be the same as the Tag - `vX.Y` - * Add some descriptive text, or the list of PRs that have been merged - since the previous release. - The git query to get the list commits since the last release is: - `git log --pretty=format:%s master...v0.1`. - Just replace "v0.1" with the name of the previous release. - * Press `Publish release` button -* Create an "announcement" highlighting the key features of the new release - and any potential noteworthy activities of the group: - * Send it to the mailing list - * Announce the release on our + +- Create a PR that modifies the [README](README.md), and all specifications (ie. + \*.md files) that include a version string, to the new release version string. +- Merge the PR. +- Create a [new release](https://github.com/cloudevents/spec/releases/new): + - Choose a "Tag version" of the form: `vX.Y`, e.g. `v0.1` + - Target should be `master`, the default value + - Release title should be the same as the Tag - `vX.Y` + - Add some descriptive text, or the list of PRs that have been merged since + the previous release. The git query to get the list commits since the last + release is: `git log --pretty=format:%s master...v0.1`. Just replace "v0.1" + with the name of the previous release. + - Press `Publish release` button +- Create an "announcement" highlighting the key features of the new release and + any potential noteworthy activities of the group: + - Send it to the mailing list + - Announce the release on our [twitter account](https://twitter.com/cloudeventsio) - * Add it to the "announcement" section of our + - Add it to the "announcement" section of our [website](https://cloudevents.io/) - diff --git a/README.md b/README.md index 901e76cf4..d36da64fe 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,21 @@ - # CloudEvents ![CloudEvents logo](https://github.com/cncf/artwork/blob/master/cloudevents/horizontal/color/cloudevents-horizontal-color.png) -Events are everywhere. However, event producers tend to describe events +Events are everywhere. However, event producers tend to describe events differently. The lack of a common way of describing events means developers must constantly -re-learn how to consume events. This also limits the potential for libraries, +re-learn how to consume events. This also limits the potential for libraries, tooling and infrastructure to aide the delivery of event data across -environments, like SDKs, event routers or tracing systems. The portability and +environments, like SDKs, event routers or tracing systems. The portability and productivity we can achieve from event data is hindered overall. CloudEvents is a specification for describing event data in common formats to provide interoperability across services, platforms and systems. -CloudEvents has received a large amount of industry interest, ranging from -major cloud providers to popular SaaS companies. CloudEvents is hosted by the +CloudEvents has received a large amount of industry interest, ranging from major +cloud providers to popular SaaS companies. CloudEvents is hosted by the [Cloud Native Computing Foundation](https://cncf.io) (CNCF) and was approved as a Cloud Native sandbox level project on [May 15, 2018](https://docs.google.com/presentation/d/1KNSv70fyTfSqUerCnccV7eEC_ynhLsm9A_kjnlmU_t0/edit#slide=id.g37acf52904_1_41). @@ -25,34 +24,34 @@ a Cloud Native sandbox level project on The following documents are available: -| | Latest Release | Working Draft | -| :--- | :---: | :---: | -| **Core Specification:** | -| CloudEvents | [v0.2](https://github.com/cloudevents/spec/blob/v0.2/spec.md) | [master](https://github.com/cloudevents/spec/blob/master/spec.md) | -| | -| **Optional Specifications:** | -| HTTP Transport Binding | [v0.2](https://github.com/cloudevents/spec/blob/v0.2/http-transport-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/http-transport-binding.md) | -| JSON Event Format | [v0.2](https://github.com/cloudevents/spec/blob/v0.2/json-format.md) | [master](https://github.com/cloudevents/spec/blob/master/json-format.md) | -| Web hook | [v0.2](https://github.com/cloudevents/spec/blob/v0.2/http-webhook.md) | [master](https://github.com/cloudevents/spec/blob/master/http-webhook.md) | -| MQTT Transport Binding | [v0.2](https://github.com/cloudevents/spec/blob/v0.2/mqtt-transport-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/mqtt-transport-binding.md) | -| NATS Transport Binding | [v0.2](https://github.com/cloudevents/spec/blob/v0.2/nats-transport-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/nats-transport-binding.md) | -| AMQP Event Format | [v0.2](https://github.com/cloudevents/spec/blob/v0.2/amqp-format.md) | [master](https://github.com/cloudevents/spec/blob/master/amqp-format.md) | -| AMQP Transport Binding | [v0.2](https://github.com/cloudevents/spec/blob/v0.2/amqp-transport-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/amqp-transport-binding.md) | -| | +| | Latest Release | Working Draft | +| :---------------------------- | :-----------------------------------------------------------------------------: | :---------------------------------------------------------------------------------: | +| **Core Specification:** | +| CloudEvents | [v0.2](https://github.com/cloudevents/spec/blob/v0.2/spec.md) | [master](https://github.com/cloudevents/spec/blob/master/spec.md) | +| | +| **Optional Specifications:** | +| HTTP Transport Binding | [v0.2](https://github.com/cloudevents/spec/blob/v0.2/http-transport-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/http-transport-binding.md) | +| JSON Event Format | [v0.2](https://github.com/cloudevents/spec/blob/v0.2/json-format.md) | [master](https://github.com/cloudevents/spec/blob/master/json-format.md) | +| Web hook | [v0.2](https://github.com/cloudevents/spec/blob/v0.2/http-webhook.md) | [master](https://github.com/cloudevents/spec/blob/master/http-webhook.md) | +| MQTT Transport Binding | [v0.2](https://github.com/cloudevents/spec/blob/v0.2/mqtt-transport-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/mqtt-transport-binding.md) | +| NATS Transport Binding | [v0.2](https://github.com/cloudevents/spec/blob/v0.2/nats-transport-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/nats-transport-binding.md) | +| AMQP Event Format | [v0.2](https://github.com/cloudevents/spec/blob/v0.2/amqp-format.md) | [master](https://github.com/cloudevents/spec/blob/master/amqp-format.md) | +| AMQP Transport Binding | [v0.2](https://github.com/cloudevents/spec/blob/v0.2/amqp-transport-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/amqp-transport-binding.md) | +| | | **Additional Documentation:** | -| Primer | [v0.2](https://github.com/cloudevents/spec/blob/v0.2/primer.md) | [master](https://github.com/cloudevents/spec/blob/master/primer.md) | -| Documented Extensions | - | [master](https://github.com/cloudevents/spec/blob/master/documented-extensions.md) | -| Proprietary Specifications | - | [master](https://github.com/cloudevents/spec/blob/master/proprietary-specs.md) | +| Primer | [v0.2](https://github.com/cloudevents/spec/blob/v0.2/primer.md) | [master](https://github.com/cloudevents/spec/blob/master/primer.md) | +| Documented Extensions | - | [master](https://github.com/cloudevents/spec/blob/master/documented-extensions.md) | +| Proprietary Specifications | - | [master](https://github.com/cloudevents/spec/blob/master/proprietary-specs.md) | -If you are new to CloudEvents, it is recommended that you start by -reading the [Primer](primer.md) for an overview of the specification's -goals and design decisions, and then move on to the -[core specification](spec.md). +If you are new to CloudEvents, it is recommended that you start by reading the +[Primer](primer.md) for an overview of the specification's goals and design +decisions, and then move on to the [core specification](spec.md). ## SDKs -In addition to the documentation mentioned above, there are also an [SDK proposal](SDK.md) and a set of SDKs -being developed: +In addition to the documentation mentioned above, there are also an +[SDK proposal](SDK.md) and a set of SDKs being developed: + - [CSharp](https://github.com/cloudevents/sdk-csharp) - [Go](https://github.com/cloudevents/sdk-go) - [Java](https://github.com/cloudevents/sdk-java) @@ -61,14 +60,13 @@ being developed: ## Community -Learn more about the people and organizations who are creating a dynamic -cloud native ecosystem by making our systems interoperable with CloudEvents. - -* [Contributors](community/contributors.md): people and organizations who helped -us get started or are actively working on the CloudEvents specification. -* Coming soon: [demos & open source](community/README.md) -- if you have -something to share about your use of CloudEvents, please submit a PR! +Learn more about the people and organizations who are creating a dynamic cloud +native ecosystem by making our systems interoperable with CloudEvents. +- [Contributors](community/contributors.md): people and organizations who helped + us get started or are actively working on the CloudEvents specification. +- Coming soon: [demos & open source](community/README.md) -- if you have + something to share about your use of CloudEvents, please submit a PR! ## Process @@ -77,15 +75,17 @@ based on [design goals](primer.md#design-goals) which focus on interoperability between systems which generate and respond to events. In order to achieve these goals, the project must describe: -- Common attributes of an *event* that facilitate interoperability -- One or more common architectures that are in active use today or planned to - be built by its members + +- Common attributes of an _event_ that facilitate interoperability +- One or more common architectures that are in active use today or planned to be + built by its members - How events are transported from producer to consumer via at least one protocol - Identify and resolve whatever else is needed for interoperability ## Communications The mailing list for e-mail communications: + - Send emails to: [cncf-cloudevents](mailto:cncf-cloudevents@lists.cncf.io) - To subscribe see: https://lists.cncf.io/g/cncf-cloudevents - Archives are at: https://lists.cncf.io/g/cncf-cloudevents/topics @@ -97,8 +97,8 @@ And a #cloudevents Slack channel under See the [CNCF public events calendar](https://www.cncf.io/community/calendar/). This specification is being developed by the -[CNCF Serverless Working Group](https://github.com/cncf/wg-serverless). -This working group meets every Thursday at 9AM PT (USA Pacific): +[CNCF Serverless Working Group](https://github.com/cncf/wg-serverless). This +working group meets every Thursday at 9AM PT (USA Pacific): Join from PC, Mac, Linux, iOS or Android: https://zoom.us/my/cncfserverlesswg @@ -115,7 +115,7 @@ Or Telephone: Meeting ID: 336 102 9682 International numbers available: - https://zoom.us/zoomconference?m=QpOqQYfTzY_Gbj9_8jPtsplp1pnVUKDr +https://zoom.us/zoomconference?m=QpOqQYfTzY_Gbj9_8jPtsplp1pnVUKDr NOTE: Please use \*6 to mute/un-mute your phone during the call. @@ -130,8 +130,7 @@ The minutes from our calls are available Recording from our calls are available [here](https://www.youtube.com/playlist?list=PLj6h78yzYM2Ph7YoBIgsZNW_RGJvNlFOt). -Periodically, the group may have in-person meetings that coincide with -a major conference. Please see the +Periodically, the group may have in-person meetings that coincide with a major +conference. Please see the [meeting minutes](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) for any future plans. - diff --git a/SDK.md b/SDK.md index 886956354..56c504260 100644 --- a/SDK.md +++ b/SDK.md @@ -1,66 +1,65 @@ # CloudEvents SDK -The intent of this document to describe bare minimum set of -requirements for a new SDKs. +The intent of this document to describe bare minimum set of requirements for a +new SDKs. ## Status of this document -Since [CloudEvent spec](spec.md) still considered as a working draft this +Since [CloudEvent spec](spec.md) still considered as a working draft this document also suppose to be considered as a working draft. ## Contribution acceptance -Being an open source community CloudEvents team is open for a new members -as well open to their contribution. -In order to ensure that an SDK is going to be supported and maintained -CloudEvents community would like to ensured that: +Being an open source community CloudEvents team is open for a new members as +well open to their contribution. In order to ensure that an SDK is going to be +supported and maintained CloudEvents community would like to ensured that: - - a person (developer, committer) is going to become a maintainer - - a person commits to support ongoing changes to the [CloudEvent spec](spec.md) +- a person (developer, committer) is going to become a maintainer +- a person commits to support ongoing changes to the [CloudEvent spec](spec.md) ## Officially maintained software development kits (SDK) -Software Development Kit (SDK) is a set of helpers designed and implemented to -enhance and speed up a CloudEvents integration. -As part of community efforts CloudEvents team committed to support and maintain -the following SDKs: +Software Development Kit (SDK) is a set of helpers designed and implemented to +enhance and speed up a CloudEvents integration. As part of community efforts +CloudEvents team committed to support and maintain the following SDKs: - - [Go SDK](https://github.com/cloudevents/sdk-go) - - [Java SDK](https://github.com/cloudevents/sdk-java) - - [Python SDK](https://github.com/cloudevents/sdk-python) - - [CSharp](https://github.com/cloudevents/sdk-csharp) - - [JavaScript SDK](https://github.com/cloudevents/sdk-javascript) +- [Go SDK](https://github.com/cloudevents/sdk-go) +- [Java SDK](https://github.com/cloudevents/sdk-java) +- [Python SDK](https://github.com/cloudevents/sdk-python) +- [CSharp](https://github.com/cloudevents/sdk-csharp) +- [JavaScript SDK](https://github.com/cloudevents/sdk-javascript) ## SDK contribution -That's said, being an open source community CloudEvents is all about building -open for contribution. -In order to keep the development/user experience the same (as much as possible) -CloudEvents team agreed to establish minimum requirements for a new SDK. +That's said, being an open source community CloudEvents is all about building +open for contribution. In order to keep the development/user experience the same +(as much as possible) CloudEvents team agreed to establish minimum requirements +for a new SDK. ### Technical requirements -Supports CloudEvents spec milestones and ongoing development version. -HTTP transport support (both structured and binary). -Widely used programming language version. - +Supports CloudEvents spec milestones and ongoing development version. HTTP +transport support (both structured and binary). Widely used programming language +version. ### Preferable API signature guidelines -In order to remain developer/user UX the same among existing officially supported -SDKs CloudEvents team asks maintainers to align with the following API signatures. -Please consider the following code as pseudo-code. +In order to remain developer/user UX the same among existing officially +supported SDKs CloudEvents team asks maintainers to align with the following API +signatures. Please consider the following code as pseudo-code. #### Event object constructor API Event build considered to be an event constructor: + ``` v01.Event() ``` -#### Event object setters API +#### Event object setters API This particular code sample represents bare minimum number of setters: + ``` v01.Event(). SetDataContentType("application/json"). @@ -72,50 +71,58 @@ This particular code sample represents bare minimum number of setters: ``` Content type setter represents an event MIME content type setter: + ``` SetDataContentType(content_type string) ``` Data setter represents an event data setter: + ``` SetData(event_data serializable) ``` ID setter represents an event ID setter: + ``` SetEventID(id string) ``` Source setter represents an event source setter: + ``` SetSource(source URL) ``` Time setter represents event emit time setter: + ``` SetEventTime(time RFC3339) ``` Type setter represents an event type setter: + ``` SetEventType(type string) ``` Extensions setter represents an event type setter: + ``` SetExtensions(exts map[string]string) ``` Generic setter represents an event attribute setter: + ``` Set(key string, value serializable) ``` - #### Event object getters API Event getters are set of methods designed to retrieve an event attributes. Here's the list of getters: + ``` EventType() -> string Source() -> URL @@ -125,7 +132,7 @@ Here's the list of getters: DataContentType() -> string Data() -> serializable Extensions() -> map[string]string - + Get(key string) -> serializable ``` @@ -134,18 +141,17 @@ All these getters correspond to setters from above. #### HTTP API -CloudEvents spec defines an HTTP transport, that's said, SDK suppose to -support an HTTP transport routine. -As part of an CloudEvent spec, defines two formats: +CloudEvents spec defines an HTTP transport, that's said, SDK suppose to support +an HTTP transport routine. As part of an CloudEvent spec, defines two formats: - - [structured](http-transport-binding.md#32-structured-content-mode) - - [binary](http-transport-binding.md#31-binary-content-mode) +- [structured](http-transport-binding.md#32-structured-content-mode) +- [binary](http-transport-binding.md#31-binary-content-mode) #### HTTP API unmarshaller -An HTTP unmarshaller should be capable of detecting a CloudEvent format from -an HTTP request headers and a body. -Here's the signature of an unmarshaller: +An HTTP unmarshaller should be capable of detecting a CloudEvent format from an +HTTP request headers and a body. Here's the signature of an unmarshaller: + ``` FromRequest( headers HTTP-Headers, @@ -156,19 +162,20 @@ Here's the signature of an unmarshaller: In this signature: - - `headers` could be a `map of string to string` or a - `map of string to list of strings`, the type of this parameter may vary - - `body` is a stream, since CloudEvent spec does not define exact type of an - event data, SDK should not be responsible for data coercing - - `data_unmarshaller` is a function that performs data unmarshaller, - logic of this method may vary depending on the type of an event format - - the return statement is a CloudEvent of the particular spec +- `headers` could be a `map of string to string` or a + `map of string to list of strings`, the type of this parameter may vary +- `body` is a stream, since CloudEvent spec does not define exact type of an + event data, SDK should not be responsible for data coercing +- `data_unmarshaller` is a function that performs data unmarshaller, logic of + this method may vary depending on the type of an event format +- the return statement is a CloudEvent of the particular spec #### HTTP API marshaller -An HTTP marshaller is a method that should be capable to convert a CloudEvent -into a combination of an HTTP request headers and a body. -Here's the signature of a marshaller: +An HTTP marshaller is a method that should be capable to convert a CloudEvent +into a combination of an HTTP request headers and a body. Here's the signature +of a marshaller: + ``` ToRequest( event CloudEvent, @@ -179,43 +186,44 @@ Here's the signature of a marshaller: In this signature: - - `event` is a CloudEvent of the particular spec - - `converter_type` represents a type of an HTTP binding format - ([binary](http-transport-binding.md#31-binary-content-mode) or - [structured](http-transport-binding.md#32-structured-content-mode)) - - `data_marshaller` is a function that serialized an event data - - the return statement is a set of an HTTP headers and request body - -The reason for such signature is that in most of programming languages -there are a lot if different HTTP frameworks and route handling signature may vary, -but HTTP headers and a request body is common -(or may be easily converted to the appropriate type). +- `event` is a CloudEvent of the particular spec +- `converter_type` represents a type of an HTTP binding format + ([binary](http-transport-binding.md#31-binary-content-mode) or + [structured](http-transport-binding.md#32-structured-content-mode)) +- `data_marshaller` is a function that serialized an event data +- the return statement is a set of an HTTP headers and request body +The reason for such signature is that in most of programming languages there are +a lot if different HTTP frameworks and route handling signature may vary, but +HTTP headers and a request body is common (or may be easily converted to the +appropriate type). #### HTTP Converters API -Each transport binding unmarshaller/marshaller is a set of converters. -In terms of an SDK the converter is a set API methods that are actually converting -a CloudEvent of the particular spec into a transport binding-ready data. +Each transport binding unmarshaller/marshaller is a set of converters. In terms +of an SDK the converter is a set API methods that are actually converting a +CloudEvent of the particular spec into a transport binding-ready data. Converter API consists of at least two methods: + ``` Read(...) Write(...) ``` -Signature of these methods may vary depending on the the type of a transport binding. +Signature of these methods may vary depending on the the type of a transport +binding. +HTTP Converters API is the example of Converters API implementation for the +[HTTP transport binding](http-transport-binding.md). Taking into account that +the CloudEvent spec defines 2 (structured and binary) formats, an SDK suppose to +implement two converters (one per each format): -HTTP Converters API is the example of Converters API implementation -for the [HTTP transport binding](http-transport-binding.md). -Taking into account that the CloudEvent spec defines 2 (structured and binary) formats, -an SDK suppose to implement two converters (one per each format): - - - `BinaryHTTPCloudEventConverter` - - `StructuredHTTPCloudEventConverter` +- `BinaryHTTPCloudEventConverter` +- `StructuredHTTPCloudEventConverter` HTTP Converters suppose to comply the following signature: + ``` Read( event CloudEvent, @@ -223,32 +231,33 @@ HTTP Converters suppose to comply the following signature: body Stream, data_unmarshaller function(data serializable) -> object ) -> CloudEvent - + Write( event CloudEvent, data_marshaller function(data serializable) -> object ) -> HTTP-Headers, Stream - + ``` -As you may see, Converter signature follows the signature of marshaller/unmarshaller. -It means that an HTTP marshaller/unmarshaller is a set of binary and structured converters. +As you may see, Converter signature follows the signature of +marshaller/unmarshaller. It means that an HTTP marshaller/unmarshaller is a set +of binary and structured converters. In `Read`: - - `event` - a placeholder (empty event object), see [event constructor](#event-object-constructor-api). - - `headers` - an HTTP request headers - - `body` - an HTTP request body - - `data_unmarshaller` - a function that turns an event data into an object of - the particular type - - returns a valid CloudEvent of the particular spec +- `event` - a placeholder (empty event object), see + [event constructor](#event-object-constructor-api). +- `headers` - an HTTP request headers +- `body` - an HTTP request body +- `data_unmarshaller` - a function that turns an event data into an object of + the particular type +- returns a valid CloudEvent of the particular spec In `Write`: - - `event` - a CloudEvent - - `data_marshaller` - a function that marshals an event data - - returns a set of an HTTP headers and a body. - +- `event` - a CloudEvent +- `data_marshaller` - a function that marshals an event data +- returns a set of an HTTP headers and a body. ### AMQP API diff --git a/amqp-format.md b/amqp-format.md index 7359816bc..3dd1d79db 100644 --- a/amqp-format.md +++ b/amqp-format.md @@ -17,24 +17,24 @@ This document is a working draft. ## 1. Introduction -[CloudEvents][CE] is a standardized and transport-neutral definition of the -structure and metadata description of events. This specification defines how -the elements defined in the CloudEvents specification are to be represented in -the [AMQP 1.0 Type System][amqp-types]. +[CloudEvents][ce] is a standardized and transport-neutral definition of the +structure and metadata description of events. This specification defines how the +elements defined in the CloudEvents specification are to be represented in the +[AMQP 1.0 Type System][amqp-types]. The [Attributes](#2-attributes) section describes the naming conventions and data type mappings for CloudEvents attributes for use as AMQP message properties. This specification does not define an envelope format. The AMQP type system's -intent is primarily to provide a consistent type system for AMQP itself and -not for message payloads. +intent is primarily to provide a consistent type system for AMQP itself and not +for message payloads. ### 1.1. Conformance The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC2119][RFC2119]. +interpreted as described in [RFC2119][rfc2119]. ## 2. Attributes @@ -45,65 +45,73 @@ CloudEvents attributes, including extensions. ### 2.1. Base Type System -The core [CloudEvents specification][CE] defines a minimal abstract type -system, which this mapping leans on. +The core [CloudEvents specification][ce] defines a minimal abstract type system, +which this mapping leans on. ### 2.2. Type System Mapping -The CloudEvents type system MUST be mapped to AMQP types as follows, -with exceptions noted below. +The CloudEvents type system MUST be mapped to AMQP types as follows, with +exceptions noted below. -| CloudEvents | AMQP -|---------------|------------------------------------------------------------- -| String | [string][AMQP-String] -| Integer | [long][AMQP-Long] -| Binary | [binary][AMQP-Binary] -| URI-reference | [string][AMQP-String] -| Timestamp | [timestamp][AMQP-Timestamp] -| Map | [map][AMQP-Map] -| Any | See 2.3. +| CloudEvents | AMQP | +| ------------- | --------------------------- | +| String | [string][amqp-string] | +| Integer | [long][amqp-long] | +| Binary | [binary][amqp-binary] | +| URI-reference | [string][amqp-string] | +| Timestamp | [timestamp][amqp-timestamp] | +| Map | [map][amqp-map] | +| Any | See 2.3. | Extension specifications MAY define diverging mapping rules for the values of attributes they define. -For instance, the attribute value may be a data structure -defined in a standard outside of CloudEvents, with a formal AMQP mapping, and -there might be risk of translation errors or information loss when the original -format is not preserved. +For instance, the attribute value may be a data structure defined in a standard +outside of CloudEvents, with a formal AMQP mapping, and there might be risk of +translation errors or information loss when the original format is not +preserved. -An extension specification that defines a diverging mapping rule for AMQP, -and any revision of such a specification, MUST also define explicit mapping -rules for all other event formats that are part of the CloudEvents core at -the time of the submission or revision. +An extension specification that defines a diverging mapping rule for AMQP, and +any revision of such a specification, MUST also define explicit mapping rules +for all other event formats that are part of the CloudEvents core at the time of +the submission or revision. ### 2.3. Mapping Any-typed Attributes -`Any`-typed CloudEvents values can either hold a `String`, or a `Binary` -value, or a `Map`. `Map` entry values are also `Any` typed. AMQP's type -system natively represents dynamic typing in its [type system -encoding][type-system-encoding], and therefore immediately allows for the required -variant type representation. +`Any`-typed CloudEvents values can either hold a `String`, or a `Binary` value, +or a `Map`. `Map` entry values are also `Any` typed. AMQP's type system natively +represents dynamic typing in its [type system encoding][type-system-encoding], +and therefore immediately allows for the required variant type representation. ## 3. References -* [RFC2046][RFC2046] Multipurpose Internet Mail Extensions (MIME) Part Two: +- [RFC2046][rfc2046] Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types -* [RFC2119][RFC2119] Key words for use in RFCs to Indicate Requirement Levels -* [OASIS-AMQP-1.0][OASIS-AMQP-1.0] OASIS Advanced Message Queuing Protocol (AMQP) Version 1.0 - -[CE]: ./spec.md -[Content-Type]: https://tools.ietf.org/html/rfc7231#section-3.1.1.5 -[type-system]: https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html -[type-system-encoding]: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html#section-encodings -[AMQP-String]: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html#type-string -[AMQP-Long]: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html#type-long -[AMQP-Binary]: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html#type-binary -[AMQP-Timestamp]: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html#type-timestamp -[AMQP-Map]: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html#type-map -[AMQP-DescribedType]: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html#doc-idp38080 -[RFC2046]: https://tools.ietf.org/html/rfc2046 -[RFC2119]: https://tools.ietf.org/html/rfc2119 -[RFC4627]: https://tools.ietf.org/html/rfc4627 -[RFC4648]: https://tools.ietf.org/html/rfc4648 -[RFC6839]: https://tools.ietf.org/html/rfc6839#section-3.1 -[RFC8259]: https://tools.ietf.org/html/rfc8259 +- [RFC2119][rfc2119] Key words for use in RFCs to Indicate Requirement Levels +- [OASIS-AMQP-1.0][oasis-amqp-1.0] OASIS Advanced Message Queuing Protocol + (AMQP) Version 1.0 + +[ce]: ./spec.md +[content-type]: https://tools.ietf.org/html/rfc7231#section-3.1.1.5 +[type-system]: + https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html +[type-system-encoding]: + http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html#section-encodings +[amqp-string]: + http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html#type-string +[amqp-long]: + http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html#type-long +[amqp-binary]: + http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html#type-binary +[amqp-timestamp]: + http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html#type-timestamp +[amqp-map]: + http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html#type-map +[amqp-describedtype]: + http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html#doc-idp38080 +[rfc2046]: https://tools.ietf.org/html/rfc2046 +[rfc2119]: https://tools.ietf.org/html/rfc2119 +[rfc4627]: https://tools.ietf.org/html/rfc4627 +[rfc4648]: https://tools.ietf.org/html/rfc4648 +[rfc6839]: https://tools.ietf.org/html/rfc6839#section-3.1 +[rfc8259]: https://tools.ietf.org/html/rfc8259 diff --git a/amqp-transport-binding.md b/amqp-transport-binding.md index 722632b79..7fbe9bb99 100644 --- a/amqp-transport-binding.md +++ b/amqp-transport-binding.md @@ -3,7 +3,7 @@ ## Abstract The AMQP Transport Binding for CloudEvents defines how events are mapped to -OASIS AMQP 1.0 ([OASIS][OASIS-AMQP-1.0]; ISO/IEC 19464:2014) messages. +OASIS AMQP 1.0 ([OASIS][oasis-amqp-1.0]; ISO/IEC 19464:2014) messages. ## Status of this document @@ -12,69 +12,77 @@ This document is a working draft. ## Table of Contents 1. [Introduction](#1-introduction) + - 1.1. [Conformance](#11-conformance) - 1.2. [Relation to AMQP](#12-relation-to-amqp) - 1.3. [Content Modes](#13-content-modes) - 1.4. [Event Formats](#14-event-formats) - 1.5. [Security](#15-security) + 2. [Use of CloudEvents Attributes](#2-use-of-cloudevents-attributes) + - 2.1. [datacontenttype Attribute](#21-datacontenttype-attribute) - 2.2. [data Attribute](#22-data-attribute) + 3. [AMQP Message Mapping](#3-amqp-message-mapping) + - 3.2. [Binary Content Mode](#31-binary-content-mode) - 3.1. [Structured Content Mode](#32-structured-content-mode) + 4. [References](#4-references) ## 1. Introduction -[CloudEvents][CE] is a standardized and transport-neutral definition of the -structure and metadata description of events. This specification defines how -the elements defined in the CloudEvents specification are to be used in -[AMQP][OASIS-AMQP-1.0] messages. +[CloudEvents][ce] is a standardized and transport-neutral definition of the +structure and metadata description of events. This specification defines how the +elements defined in the CloudEvents specification are to be used in +[AMQP][oasis-amqp-1.0] messages. ### 1.1. Conformance The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC2119][RFC2119]. +interpreted as described in [RFC2119][rfc2119]. ### 1.2. Relation to AMQP -This specification does not prescribe rules constraining transfer or -settlement of event messages with AMQP; it solely defines how CloudEvents -are expressed as AMQP 1.0 messages. +This specification does not prescribe rules constraining transfer or settlement +of event messages with AMQP; it solely defines how CloudEvents are expressed as +AMQP 1.0 messages. AMQP-based messaging and eventing infrastructures often provide higher-level -programming-level abstractions that do not expose all AMQP protocol elements, -or map AMQP protocol elements or names to proprietary constructs. This +programming-level abstractions that do not expose all AMQP protocol elements, or +map AMQP protocol elements or names to proprietary constructs. This specification uses AMQP terminology, and implementers can refer the the -respective infrastructure's AMQP documentation to determine the mapping into -a programming-level abstraction. +respective infrastructure's AMQP documentation to determine the mapping into a +programming-level abstraction. -This specification assumes use of the default AMQP [message format][message-format]. +This specification assumes use of the default AMQP [message +format][message-format]. ### 1.3. Content Modes The specification defines two content modes for transferring events: -*structured* and *binary*. Every compliant implementation SHOULD support both +_structured_ and _binary_. Every compliant implementation SHOULD support both modes. -In the *structured* content mode, event metadata attributes and event data are -placed into the AMQP message's [application data][data] section -using an [event format](#14-event-formats). +In the _structured_ content mode, event metadata attributes and event data are +placed into the AMQP message's [application data][data] section using an +[event format](#14-event-formats). -In the *binary* content mode, the value of the event `data` attribute is placed -into the AMQP message's [application data][data] section as-is, with -the `datacontenttype` attribute value declaring its media type; all other event -attributes are mapped to the AMQP [application-properties][app-properties] section. +In the _binary_ content mode, the value of the event `data` attribute is placed +into the AMQP message's [application data][data] section as-is, with the +`datacontenttype` attribute value declaring its media type; all other event +attributes are mapped to the AMQP [application-properties][app-properties] +section. ### 1.4. Event Formats -Event formats, used with the *stuctured* content mode, define how an event is -expressed in a particular data format. All implementations of this -specification MUST support the [JSON event format][JSON-format] as well as the -[AMQP event format][AMQP-format] for the [application-properties][app-properties] -section, but MAY support any additional, including proprietary, formats. +Event formats, used with the _stuctured_ content mode, define how an event is +expressed in a particular data format. All implementations of this specification +MUST support the [JSON event format][json-format] as well as the [AMQP event +format][amqp-format] for the [application-properties][app-properties] section, +but MAY support any additional, including proprietary, formats. ### 1.5. Security @@ -83,21 +91,21 @@ mandate specific existing features to be used. ## 2. Use of CloudEvents Attributes -This specification does not further define any of the [CloudEvents][CE] event +This specification does not further define any of the [CloudEvents][ce] event attributes. Two of the event attributes, `datacontenttype` and `data` are handled specially and mapped onto AMQP constructs, all other attributes are transferred as metadata without further interpretation. -This mapping is intentionally robust against changes, including the addition -and removal of event attributes, and also accommodates vendor extensions to the +This mapping is intentionally robust against changes, including the addition and +removal of event attributes, and also accommodates vendor extensions to the event metadata. Any mention of event attributes other than `datacontenttype` and `data` is exemplary. ### 2.1. datacontenttype Attribute -The `datacontenttype` attribute is assumed to contain a [RFC2046][RFC2046] +The `datacontenttype` attribute is assumed to contain a [RFC2046][rfc2046] compliant media-type expression. ### 2.2. data Attribute @@ -112,21 +120,20 @@ available as a sequence of bytes. For instance, if the declared `datacontenttype` is `application/json;charset=utf-8`, the expectation is that the `data` attribute -value is made available as [UTF-8][RFC3629] encoded JSON text for use in -AMQP. +value is made available as [UTF-8][rfc3629] encoded JSON text for use in AMQP. ## 3. AMQP Message Mapping The content mode is chosen by the sender of the event, which is either the requesting or the responding party. Protocol interaction patterns that might -allow solicitation of events using a particular content mode might be defined -by an application, but are not defined here. +allow solicitation of events using a particular content mode might be defined by +an application, but are not defined here. The receiver of the event can distinguish between the two modes by inspecting the `content-type` message property field. If the value is prefixed with the -CloudEvents media type `application/cloudevents`, indicating the use of a -known [event format](#14-event-formats), the receiver uses *structured* mode, -otherwise it defaults to *binary* mode. +CloudEvents media type `application/cloudevents`, indicating the use of a known +[event format](#14-event-formats), the receiver uses _structured_ mode, +otherwise it defaults to _binary_ mode. If a receiver detects the CloudEvents media type, but with an event format that it cannot handle, for instance `application/cloudevents+avro`, it MAY still @@ -134,12 +141,12 @@ treat the event as binary and forward it to another party as-is. ### 3.1. Binary Content Mode -The *binary* content mode accommodates any shape of event data, and allows for +The _binary_ content mode accommodates any shape of event data, and allows for efficient transfer and without transcoding effort. #### 3.1.1. AMQP content-type -For the *binary* mode, the AMQP `content-type` property field value maps +For the _binary_ mode, the AMQP `content-type` property field value maps directly to the CloudEvents `datacontenttype` attribute. #### 3.1.2. Event Data Encoding @@ -149,21 +156,20 @@ The [`data` attribute](#22-data-attribute) byte-sequence is used as the AMQP #### 3.1.3. Metadata Headers -All [CloudEvents][CE] attributes with exception of `datacontenttype` and `data` +All [CloudEvents][ce] attributes with exception of `datacontenttype` and `data` MUST be individually mapped to and from the AMQP -[application-properties][app-properties] section, with exceptions noted -below. +[application-properties][app-properties] section, with exceptions noted below. -CloudEvents extensions that define their own attributes MAY define a -diverging mapping to AMQP properties for those attributes, also in -different message sections, especially if specific attributes or their -names need to align with AMQP features or with other specifications that -have explicit AMQP header bindings. +CloudEvents extensions that define their own attributes MAY define a diverging +mapping to AMQP properties for those attributes, also in different message +sections, especially if specific attributes or their names need to align with +AMQP features or with other specifications that have explicit AMQP header +bindings. -An extension specification that defines a diverging mapping rule for AMQP, -and any revision of such a specification, MUST also define explicit mapping -rules for all other transport bindings that are part of the CloudEvents core at -the time of the submission or revision. +An extension specification that defines a diverging mapping rule for AMQP, and +any revision of such a specification, MUST also define explicit mapping rules +for all other transport bindings that are part of the CloudEvents core at the +time of the submission or revision. ##### 3.1.3.1 AMQP Application Property Names @@ -180,14 +186,14 @@ Examples: The value for each AMQP application property is constructed from the respective attribute's AMQP type representation, compliant with the [AMQP event -format][AMQP-format] specification. +format][amqp-format] specification. #### 3.1.4 Examples -This example shows the *binary* mode mapping of an event into the -[bare message][message-format] sections of AMQP: +This example shows the _binary_ mode mapping of an event into the [bare +message][message-format] sections of AMQP: -``` text +```text --------------- properties ------------------ to: myqueue @@ -213,7 +219,7 @@ cloudEvents:source: "/mycontext/subcontext" ### 3.2. Structured Content Mode -The *structured* content mode keeps event metadata and data together in the +The _structured_ content mode keeps event metadata and data together in the payload, allowing simple forwarding of the same event across multiple routing hops, and across multiple transports. @@ -222,9 +228,9 @@ hops, and across multiple transports. The [AMQP `content-type`][content-type] property field is set to the media type of an [event format](#14-event-formats). -Example for the [JSON format][JSON-format]: +Example for the [JSON format][json-format]: -``` text +```text content-type: application/cloudevents+json; charset=UTF-8 ``` @@ -233,9 +239,9 @@ content-type: application/cloudevents+json; charset=UTF-8 The chosen [event format](#14-event-formats) defines how all attributes, including the `data` attribute, are represented. -The event metadata and data is then rendered in accordance with the event -format specification and the resulting data becomes the AMQP application -[data][data] section. +The event metadata and data is then rendered in accordance with the event format +specification and the resulting data becomes the AMQP application [data][data] +section. #### 3.2.3. Metadata Headers @@ -246,7 +252,7 @@ the [binary mode](#313-metadata-headers). This example shows a JSON event format encoded event: -``` text +```text --------------- properties ------------------------------ to: myqueue @@ -272,28 +278,34 @@ content-type: application/cloudevents+json; charset=utf-8 ## 4. References -- [RFC2046][RFC2046] Multipurpose Internet Mail Extensions (MIME) Part Two: +- [RFC2046][rfc2046] Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types -- [RFC2119][RFC2119] Key words for use in RFCs to Indicate Requirement Levels -- [RFC3629][RFC3629] UTF-8, a transformation format of ISO 10646 -- [RFC4627][RFC4627] The application/json Media Type for JavaScript Object +- [RFC2119][rfc2119] Key words for use in RFCs to Indicate Requirement Levels +- [RFC3629][rfc3629] UTF-8, a transformation format of ISO 10646 +- [RFC4627][rfc4627] The application/json Media Type for JavaScript Object Notation (JSON) -- [RFC7159][RFC7159] The JavaScript Object Notation (JSON) Data Interchange Format -- [OASIS-AMQP-1.0][OASIS-AMQP-1.0] OASIS Advanced Message Queuing Protocol (AMQP) Version 1.0 - -[CE]: ./spec.md -[JSON-format]: ./json-format.md -[AMQP-format]: ./amqp-format.md +- [RFC7159][rfc7159] The JavaScript Object Notation (JSON) Data Interchange + Format +- [OASIS-AMQP-1.0][oasis-amqp-1.0] OASIS Advanced Message Queuing Protocol + (AMQP) Version 1.0 + +[ce]: ./spec.md +[json-format]: ./json-format.md +[amqp-format]: ./amqp-format.md [data-section]: 3.2.6 -[Content-Type]: https://tools.ietf.org/html/rfc7231#section-3.1.1.5 -[JSON-Value]: https://tools.ietf.org/html/rfc7159#section-3 -[RFC2046]: https://tools.ietf.org/html/rfc2046 -[RFC2119]: https://tools.ietf.org/html/rfc2119 -[RFC3629]: https://tools.ietf.org/html/rfc3629 -[RFC4627]: https://tools.ietf.org/html/rfc4627 -[RFC6839]: https://tools.ietf.org/html/rfc6839#section-3.1 -[RFC7159]: https://tools.ietf.org/html/rfc7159 -[OASIS-AMQP-1.0]: http://docs.oasis-open.org/amqp/core/v1.0/amqp-core-overview-v1.0.html -[message-format]: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#section-message-format -[data]: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-data -[app-properties]: http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-application-properties +[content-type]: https://tools.ietf.org/html/rfc7231#section-3.1.1.5 +[json-value]: https://tools.ietf.org/html/rfc7159#section-3 +[rfc2046]: https://tools.ietf.org/html/rfc2046 +[rfc2119]: https://tools.ietf.org/html/rfc2119 +[rfc3629]: https://tools.ietf.org/html/rfc3629 +[rfc4627]: https://tools.ietf.org/html/rfc4627 +[rfc6839]: https://tools.ietf.org/html/rfc6839#section-3.1 +[rfc7159]: https://tools.ietf.org/html/rfc7159 +[oasis-amqp-1.0]: + http://docs.oasis-open.org/amqp/core/v1.0/amqp-core-overview-v1.0.html +[message-format]: + http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#section-message-format +[data]: + http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-data +[app-properties]: + http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-application-properties diff --git a/artwork/README.md b/artwork/README.md index 777789bfa..1e3f955e8 100644 --- a/artwork/README.md +++ b/artwork/README.md @@ -1,8 +1,20 @@ # CloudEvents logos +In the [CNCF artwork repo](https://github.com/cncf/artwork), CloudEvents logos +are available in 3 formats (PNG/SVG/AI), 3 layouts -- horizontal (also known as +landscape format), stacked (which is closer to square), and icon (which does not +include the name and is square), and 3 versions (color/black/white). For +questions about using terms in text, please see the CNCF +[Style Guide](https://github.com/cncf/foundation/blob/master/style-guide.md). -In the [CNCF artwork repo](https://github.com/cncf/artwork), CloudEvents logos are available in 3 formats (PNG/SVG/AI), 3 layouts -- horizontal (also known as landscape format), stacked (which is closer to square), and icon (which does not include the name and is square), and 3 versions (color/black/white). For questions about using terms in text, please see the CNCF [Style Guide](https://github.com/cncf/foundation/blob/master/style-guide.md). + +      +  +    + -             - -             \ No newline at end of file + +      +  +    + diff --git a/community/README.md b/community/README.md index aa1810c29..c04b9626a 100644 --- a/community/README.md +++ b/community/README.md @@ -4,7 +4,7 @@ We have an amazing community working together to build a dynamic cloud native ecosystem by increasing interoperability between systems which generate and respond to events. -* [Contributors](contributors.md): the people and companies contributing to - the CloudEvents specification and ecosystem -* [Open Source](open-source.md): open source libraries that support CloudEvents -* [Demos](demos.md): CloudEvents in action \ No newline at end of file +- [Contributors](contributors.md): the people and companies contributing to the + CloudEvents specification and ecosystem +- [Open Source](open-source.md): open source libraries that support CloudEvents +- [Demos](demos.md): CloudEvents in action diff --git a/community/contributors.md b/community/contributors.md index db1d3086c..14f95d001 100644 --- a/community/contributors.md +++ b/community/contributors.md @@ -1,77 +1,78 @@ ## CloudEvents contributors We welcome you to join us! This list acknowledges those who contribute whether -it be via GitHub pull request or in real life in the project, as well as -those who contributed before this became a CNCF project. If you -are participating in some way, please add your information via pull request. +it be via GitHub pull request or in real life in the project, as well as those +who contributed before this became a CNCF project. If you are participating in +some way, please add your information via pull request. -This list is intended to build community, helping the project to connect -github handles to real world identities and get to know each other, and for new -folks to see who has been involved already. +This list is intended to build community, helping the project to connect github +handles to real world identities and get to know each other, and for new folks +to see who has been involved already. Contributions do not constitute an official endorsement. -* **Alibaba** - * [Alibaba Cloud Function Compute](https://www.alibabacloud.com/product/function-compute) - * Ryan Zhang - [@nerdyyatrice](https://github.com/nerdyyatrice) - * Haoran Yang, Hongqi Wang -* **Amazon** - * [AWS Lambda events](https://docs.aws.amazon.com/lambda/latest/dg/invoking-lambda-function.html) - * Arun Gupta, Ajay Nair, Rob Leidle, Orr Weinstein -* **Google** - * [Google Cloud Functions](https://cloud.google.com/functions/) and [Cloud Functions for Firebase](https://firebase.google.com/docs/functions/) - * Sarah Allen - [@ultrasaurus](https://github.com/ultrasaurus) - * Rachel Myers - [@rachelmyers](https://github.com/rachelmyers) - * Thomas Bouldin - [@inlined](https://github.com/inlined) - * Mike McDonald, Morgan Hallmon, Robert-Jan Huijsman -* **Huawei** - * [Huawei Function Stage](http://www.huaweicloud.com/en-us/product/functionstage.html) - * [Huawei Function Graph](https://www.huaweicloud.com/en-us/product/functiongraph.html) - * Cathy Hong Zhang - [@cathyhongzhang](https://github.com/cathyhongzhang) - * Louis Fourie - [@lfourie](https://github.com/lfourie) -* **IBM** - * [IBM Cloud Functions](https://console.bluemix.net/openwhisk/) - * Doug Davis - [@duglin](https://github.com/duglin) - * Daniel Krook - [@krook](https://github.com/krook) - * Matt Rutkowski - [@mrutkows](https://github.com/mrutkows) - * Michael M Behrendt - [@mbehrendt](https://github.com/mbehrendt) -* **Iguazio** - * [nuclio (serverless)](https://github.com/nuclio/nuclio) - * [iguazio data platform](https://www.iguazio.com/) - * Yaron Haviv - [@yaronha](https://github.com/yaronha) - * Orit Nissan-Messing - [@oritnm](https://github.com/oritnm) -* **Intel** - * David Lyle - [@dklyle](https://github.com/dklyle) -* **Microsoft** - * [Microsoft Event Grid](https://azure.microsoft.com/en-us/services/event-grid/) - * Clemens Vasters - [@clemensv](https://github.com/clemensv) - * Bahram Banisadr - [@banisadr](https://github.com/banisadr) - * Dan Rosanova - [@djrosanova](https://github.com/djrosanova) - * Cesar Ruiz-Meraz, Raja Ravipati -* **Oracle** - * [Fn Project](https://fnproject.io/) - * Chad Arimura - [@carimura](https://github.com/banisadr) - * Stanley Halka - [@shalka](https://github.com/banisadr) - * Travis Reeder - [@treeder](https://github.com/banisadr) -* **PayPal** - * Vladimir Bacvanski - * Jem Day - [@JemDay](https://github.com/JemDay) -* **Red Hat** - * Jim Curtis - [@jimcurtis64](https://github.com/jimcurtis2) - * William Markito Oliveira - [@william_markito](https://github.com/markito) -* **SAP** - * [kubeless](https://kubeless.io) - * Nathan Oyler - [@notque](https://github.com/notque) - * Stevo Slavić - [@sslavic](https://github.com/sslavic) - * Klaus Deissner - [@deissnerk](https://github.com/deissnerk) -* **Serverless Inc** - * [Serverless Framework and Event Gateway](https://serverless.com/) - * Austen Collins - [@ac360](https://github.com/ac360) - * Rupak Ganguly - [@rupakg](https://github.com/rupakg) - * Brian Neisler - [@brianneisler](https://github.com/brianneisler) - * Jeremy Coffield, Ganesh Radhakirshnan -* **SolarWinds** - * Lee Calcote - [@leecalcote](https://github.com/leecalcote) -* **VMWare** - * [Dispatch Functions Framework](http://dispatchframework.io) - * Mark Peek - [@markpeek](https://github.com/markpeek) +- **Alibaba** + - [Alibaba Cloud Function Compute](https://www.alibabacloud.com/product/function-compute) + - Ryan Zhang - [@nerdyyatrice](https://github.com/nerdyyatrice) + - Haoran Yang, Hongqi Wang +- **Amazon** + - [AWS Lambda events](https://docs.aws.amazon.com/lambda/latest/dg/invoking-lambda-function.html) + - Arun Gupta, Ajay Nair, Rob Leidle, Orr Weinstein +- **Google** + - [Google Cloud Functions](https://cloud.google.com/functions/) and + [Cloud Functions for Firebase](https://firebase.google.com/docs/functions/) + - Sarah Allen - [@ultrasaurus](https://github.com/ultrasaurus) + - Rachel Myers - [@rachelmyers](https://github.com/rachelmyers) + - Thomas Bouldin - [@inlined](https://github.com/inlined) + - Mike McDonald, Morgan Hallmon, Robert-Jan Huijsman +- **Huawei** + - [Huawei Function Stage](http://www.huaweicloud.com/en-us/product/functionstage.html) + - [Huawei Function Graph](https://www.huaweicloud.com/en-us/product/functiongraph.html) + - Cathy Hong Zhang - [@cathyhongzhang](https://github.com/cathyhongzhang) + - Louis Fourie - [@lfourie](https://github.com/lfourie) +- **IBM** + - [IBM Cloud Functions](https://console.bluemix.net/openwhisk/) + - Doug Davis - [@duglin](https://github.com/duglin) + - Daniel Krook - [@krook](https://github.com/krook) + - Matt Rutkowski - [@mrutkows](https://github.com/mrutkows) + - Michael M Behrendt - [@mbehrendt](https://github.com/mbehrendt) +- **Iguazio** + - [nuclio (serverless)](https://github.com/nuclio/nuclio) + - [iguazio data platform](https://www.iguazio.com/) + - Yaron Haviv - [@yaronha](https://github.com/yaronha) + - Orit Nissan-Messing - [@oritnm](https://github.com/oritnm) +- **Intel** + - David Lyle - [@dklyle](https://github.com/dklyle) +- **Microsoft** + - [Microsoft Event Grid](https://azure.microsoft.com/en-us/services/event-grid/) + - Clemens Vasters - [@clemensv](https://github.com/clemensv) + - Bahram Banisadr - [@banisadr](https://github.com/banisadr) + - Dan Rosanova - [@djrosanova](https://github.com/djrosanova) + - Cesar Ruiz-Meraz, Raja Ravipati +- **Oracle** + - [Fn Project](https://fnproject.io/) + - Chad Arimura - [@carimura](https://github.com/banisadr) + - Stanley Halka - [@shalka](https://github.com/banisadr) + - Travis Reeder - [@treeder](https://github.com/banisadr) +- **PayPal** + - Vladimir Bacvanski + - Jem Day - [@JemDay](https://github.com/JemDay) +- **Red Hat** + - Jim Curtis - [@jimcurtis64](https://github.com/jimcurtis2) + - William Markito Oliveira - [@william_markito](https://github.com/markito) +- **SAP** + - [kubeless](https://kubeless.io) + - Nathan Oyler - [@notque](https://github.com/notque) + - Stevo Slavić - [@sslavic](https://github.com/sslavic) + - Klaus Deissner - [@deissnerk](https://github.com/deissnerk) +- **Serverless Inc** + - [Serverless Framework and Event Gateway](https://serverless.com/) + - Austen Collins - [@ac360](https://github.com/ac360) + - Rupak Ganguly - [@rupakg](https://github.com/rupakg) + - Brian Neisler - [@brianneisler](https://github.com/brianneisler) + - Jeremy Coffield, Ganesh Radhakirshnan +- **SolarWinds** + - Lee Calcote - [@leecalcote](https://github.com/leecalcote) +- **VMWare** + - [Dispatch Functions Framework](http://dispatchframework.io) + - Mark Peek - [@markpeek](https://github.com/markpeek) diff --git a/community/demos.md b/community/demos.md index 1a8ccc8cb..1c448e948 100644 --- a/community/demos.md +++ b/community/demos.md @@ -1,23 +1,24 @@ - If you have a demo of CloudEvents in action, please add a link here. - If there isn't an associated blog or github repo, feel free to add - descriptive text as a markdown file in `community/demos/`. +If you have a demo of CloudEvents in action, please add a link here. If there +isn't an associated blog or github repo, feel free to add descriptive text as a +markdown file in `community/demos/`. +- CNCF/Kube-Con EU May 2018 -* CNCF/Kube-Con EU May 2018 - * CloudEvents interop demo during Austen Collins' + - CloudEvents interop demo during Austen Collins' [session](https://kccnceu18.sched.com/event/Dqvg/the-serverless-and-event-driven-future-austen-collins-serverless-intermediate-skill-level) - * Participants: Alibaba, Google, IBM, iguazio, RedHat, Serverless.com, VMware - * Info on demo structure: https://github.com/ac360/cloudevents-demo - * Code from demo: - * [Oracle Fn](https://github.com/fnproject/cloudevents-demo) - * [Serverless Compute/FaaS](https://github.com/ac360/cloudevents-demo) - * [VMware Dispatch](https://github.com/dispatchframework/cloudevents-twitter-demo) + - Participants: Alibaba, Google, IBM, iguazio, RedHat, Serverless.com, VMware + - Info on demo structure: https://github.com/ac360/cloudevents-demo + - Code from demo: + - [Oracle Fn](https://github.com/fnproject/cloudevents-demo) + - [Serverless Compute/FaaS](https://github.com/ac360/cloudevents-demo) + - [VMware Dispatch](https://github.com/dispatchframework/cloudevents-twitter-demo) -* CNCF/Kube-Con NA December 2018 - * CloudEvents interop demo during Serverless WG Intro +- CNCF/Kube-Con NA December 2018 + - CloudEvents interop demo during Serverless WG Intro [session](https://sched.co/Grcc) ([video](https://www.youtube.com/watch?v=iNlqLr9vlD4&feature=youtu.be)) - * Participants: IBM, Knative, Oracle, OpenFaaS, VMware, Microsoft, Huawei, + - Participants: IBM, Knative, Oracle, OpenFaaS, VMware, Microsoft, Huawei, SAP, PayPal - * Info on demo structure: [doc](https://docs.google.com/document/d/1Vkrmz0vLyiJnUmHUeJfmFbBldDyD-DOFcBNOU-eEKeg/edit#bookmark=id.umb4bpvgj3x1) - * Demo web site (if still available): http://srcdog.com/madlibs + - Info on demo structure: + [doc](https://docs.google.com/document/d/1Vkrmz0vLyiJnUmHUeJfmFbBldDyD-DOFcBNOU-eEKeg/edit#bookmark=id.umb4bpvgj3x1) + - Demo web site (if still available): http://srcdog.com/madlibs diff --git a/community/open-source.md b/community/open-source.md index 01d480596..93862f1a7 100644 --- a/community/open-source.md +++ b/community/open-source.md @@ -1,32 +1,45 @@ -If you have created (or know of) an open source library or product that -uses CloudEvents, please include in the list below. +If you have created (or know of) an open source library or product that uses +CloudEvents, please include in the list below. -* [CloudEvents.NET](https://github.com/aliencube/CloudEvents.NET): is a .NET +- [CloudEvents.NET](https://github.com/aliencube/CloudEvents.NET): is a .NET implementation of the CloudEvents [spec](../spec.md) and - [HTTP transport binding](../http-transport-binding.md). It has been released to - [nuget.org](https://www.nuget.org/packages?q=Aliencube.CloudEventsNet). - It also contains some app + [HTTP transport binding](../http-transport-binding.md). It has been released + to [nuget.org](https://www.nuget.org/packages?q=Aliencube.CloudEventsNet). It + also contains some app [samples](https://github.com/aliencube/CloudEvents.NET/tree/master/sample) of 1) console app to Web API, and 2) Web API to Azure Event Grid, which demonstrates how CloudEvent messages are generated and sent to Web API and Azure Event Grid over HTTP. -* [microBean CloudEvents](https://microbean.github.io/microbean-cloudevents/): +- [microBean CloudEvents](https://microbean.github.io/microbean-cloudevents/): CloudEvents represented as plain Java objects. Satellite projects add [Jackson and CDI event integration](https://microbean.github.io/microbean-cloudevents-jackson-cdi). -* [jCloudEvents](https://github.com/project-streamzi/jcloudevents): - Java POJO implementation of the CloudEvents specification and some CDI bindings. -* [Strombrau Gateway](https://github.com/project-streamzi/event-gateway): - Vert.x based gateway routing CloudEvent metadata to internal Apache Kafka topic -* [Event Gateway](https://github.com/serverless/event-gateway): - It's dataflow for event-driven, serverless architectures. The Event Gateway combines both API Gateway and Pub/Sub functionality into a single event-driven experience. -* [CloudEvents Extend API](https://github.com/goextend/cloudevents-extend-api) is a JavaScript programming model for [Extend](https://goextend.io) which allows handling Cloud Events. -* [CloudEvents Verify](https://github.com/btbd/CEVerify): - is a tool to help verify CloudEvents according to the proper specifications. It is currently being hosted publicly [here](http://soaphub.org/ceverify). -* [Gloo](https://github.com/solo-io/gloo): - is a function gateway built on top of [Envoy Proxy](https://envoyproxy.io/) by [Solo.io](https://www.solo.io/) that supports CloudEvents. -* [Dispatch](https://github.com/vmware/dispatch): - is a function framework / gateway by [VMWare](https://vmware.github.io/dispatch/) that support CloudEvents. -* [cloudevents-python](https://github.com/williamhogman/cloudevents-python): A CloudEvents library for python. -* [CloudEvents.live](https://cloudevents.live/): A real-time debugger/request bin for the CloudEvents webhook format. Submit events to the bin and immediately see them in the web UI (Sources: [Backend](https://github.com/klira/cloudevents-bin) [Frontend](https://github.com/klira/cloudevents-debugger)) -* [Argo-Events](https://github.com/argoproj/argo-events): An event-based dependency manager for Kubernetes which uses sensors to act on CloudEvents. -* [cloudevent.js](https://github.com/smartiniOnGitHub/cloudevent.js): A CloudEvents library for Node.js. +- [jCloudEvents](https://github.com/project-streamzi/jcloudevents): Java POJO + implementation of the CloudEvents specification and some CDI bindings. +- [Strombrau Gateway](https://github.com/project-streamzi/event-gateway): Vert.x + based gateway routing CloudEvent metadata to internal Apache Kafka topic +- [Event Gateway](https://github.com/serverless/event-gateway): It's dataflow + for event-driven, serverless architectures. The Event Gateway combines both + API Gateway and Pub/Sub functionality into a single event-driven experience. +- [CloudEvents Extend API](https://github.com/goextend/cloudevents-extend-api) + is a JavaScript programming model for [Extend](https://goextend.io) which + allows handling Cloud Events. +- [CloudEvents Verify](https://github.com/btbd/CEVerify): is a tool to help + verify CloudEvents according to the proper specifications. It is currently + being hosted publicly [here](http://soaphub.org/ceverify). +- [Gloo](https://github.com/solo-io/gloo): is a function gateway built on top of + [Envoy Proxy](https://envoyproxy.io/) by [Solo.io](https://www.solo.io/) that + supports CloudEvents. +- [Dispatch](https://github.com/vmware/dispatch): is a function framework / + gateway by [VMWare](https://vmware.github.io/dispatch/) that support + CloudEvents. +- [cloudevents-python](https://github.com/williamhogman/cloudevents-python): A + CloudEvents library for python. +- [CloudEvents.live](https://cloudevents.live/): A real-time debugger/request + bin for the CloudEvents webhook format. Submit events to the bin and + immediately see them in the web UI (Sources: + [Backend](https://github.com/klira/cloudevents-bin) + [Frontend](https://github.com/klira/cloudevents-debugger)) +- [Argo-Events](https://github.com/argoproj/argo-events): An event-based + dependency manager for Kubernetes which uses sensors to act on CloudEvents. +- [cloudevent.js](https://github.com/smartiniOnGitHub/cloudevent.js): A + CloudEvents library for Node.js. diff --git a/documented-extensions.md b/documented-extensions.md index 529e91b34..0c17a107e 100644 --- a/documented-extensions.md +++ b/documented-extensions.md @@ -1,48 +1,45 @@ # CloudEvents Extension Attributes The [CloudEvents specification](spec.md) defines a set of metadata attributes -than can be used when transforming a generic event into a CloudEvent. -The list of attributes specified in that document represent the minimal set -that the specification authors deemed most likely to be used in a majority of -situations. - -This document defines some addition attributes that, while not as commonly -used as the ones specified in the [CloudEvents specification](spec.md), -could still benefit from being formally specified in the hopes of providing -some degree of interoperability. This also allows for attributes to be -defined in an experimental manner and tested prior to being considered for -inclusion in the [CloudEvents specification](spec.md). - -Implementations of the [CloudEvents specification](spec.md) are not mandated -to limit their use of extension attributes to just the ones specified in -this document. The attributes defined in this document have no official -standing and might be changed, or removed, at any time. As such, inclusion -of an attribute in this document does not need to meet the same level of -maturity, or popularity, as attributes defined in the -[CloudEvents specification](spec.md). To be included in this document, -aside from the normal PR review process, the attribute needs to have at least -two [Voting](GOVERNANCE.md#membership) member organizations stating their -support for its inclusion as comments in the PR. If the author of the PR is -also a Voting member, then they are allowed to be one of two. +than can be used when transforming a generic event into a CloudEvent. The list +of attributes specified in that document represent the minimal set that the +specification authors deemed most likely to be used in a majority of situations. + +This document defines some addition attributes that, while not as commonly used +as the ones specified in the [CloudEvents specification](spec.md), could still +benefit from being formally specified in the hopes of providing some degree of +interoperability. This also allows for attributes to be defined in an +experimental manner and tested prior to being considered for inclusion in the +[CloudEvents specification](spec.md). + +Implementations of the [CloudEvents specification](spec.md) are not mandated to +limit their use of extension attributes to just the ones specified in this +document. The attributes defined in this document have no official standing and +might be changed, or removed, at any time. As such, inclusion of an attribute in +this document does not need to meet the same level of maturity, or popularity, +as attributes defined in the [CloudEvents specification](spec.md). To be +included in this document, aside from the normal PR review process, the +attribute needs to have at least two [Voting](GOVERNANCE.md#membership) member +organizations stating their support for its inclusion as comments in the PR. If +the author of the PR is also a Voting member, then they are allowed to be one of +two. ## Usage Support for any extension is OPTIONAL. When an extension definition uses -[RFC 2199](https://www.ietf.org/rfc/rfc2119.txt) keywords (e.g. MUST, -SHOULD, MAY), this usage only applies to events that use the extension. - -Extensions always follow a common placement strategy for in-memory -formats (e.g. [JSON](json-format.md), XML, Protobuffer) that are -decided by those representations. Transport bindings (e.g. -[HTTP](http-transport-binding.md), [MQTT](mqtt-transport-binding.md), -[AMPQ](amqp-transport-binding.md), [NATS](nats-transport-binding.md)) provide -default placement for extensions, but an extension MAY require special -representation when transported (e.g. tracing standards that require -specific headers). Extension authors SHOULD only require special -representation in transport bindings where extensions integrate with -pre-existing specs; extensions with custom transport bindings are much -more likely to be dropped by middleware that does not understand the -extension. +[RFC 2199](https://www.ietf.org/rfc/rfc2119.txt) keywords (e.g. MUST, SHOULD, +MAY), this usage only applies to events that use the extension. + +Extensions always follow a common placement strategy for in-memory formats (e.g. +[JSON](json-format.md), XML, Protobuffer) that are decided by those +representations. Transport bindings (e.g. [HTTP](http-transport-binding.md), +[MQTT](mqtt-transport-binding.md), [AMPQ](amqp-transport-binding.md), +[NATS](nats-transport-binding.md)) provide default placement for extensions, but +an extension MAY require special representation when transported (e.g. tracing +standards that require specific headers). Extension authors SHOULD only require +special representation in transport bindings where extensions integrate with +pre-existing specs; extensions with custom transport bindings are much more +likely to be dropped by middleware that does not understand the extension. As a convention, extensions of scalar types (e.g. `String`, `Binary`, `URI-reference`, `Number`) document their `Value` and structured types document @@ -50,6 +47,6 @@ their `Attributes`. ## Known Extensions -* [Distributed Tracing](extensions/distributed-tracing.md) -* [Sampling](extensions/sampled-rate.md) -* [Sequence](extensions/sequence.md) +- [Distributed Tracing](extensions/distributed-tracing.md) +- [Sampling](extensions/sampled-rate.md) +- [Sequence](extensions/sequence.md) diff --git a/extensions/distributed-tracing.md b/extensions/distributed-tracing.md index 46b35ae33..1b78ee553 100644 --- a/extensions/distributed-tracing.md +++ b/extensions/distributed-tracing.md @@ -1,35 +1,40 @@ # Distributed Tracing extension -This extension embeds context from -[Distributed Tracing](https://w3c.github.io/trace-context/) -so that distributed systems can include traces that span an event-driven system. -This is the foundation of many other systems, such as Open Tracing, on which -platforms like Prometheus are built. +This extension embeds context from +[Distributed Tracing](https://w3c.github.io/trace-context/) so that distributed +systems can include traces that span an event-driven system. This is the +foundation of many other systems, such as Open Tracing, on which platforms like +Prometheus are built. ## Attributes + #### traceparent -* Type: `String` -* Description: Contains a version, trace ID, span ID, and trace options as defined in - [section 2.2.2](https://w3c.github.io/trace-context/#field-value) -* Constraints - * REQUIRED + +- Type: `String` +- Description: Contains a version, trace ID, span ID, and trace options as + defined in [section 2.2.2](https://w3c.github.io/trace-context/#field-value) +- Constraints + - REQUIRED #### tracestate -* Type: `String` -* Description: a comma-delimited list of key-value pairs, defined by + +- Type: `String` +- Description: a comma-delimited list of key-value pairs, defined by [section 2.3.2](https://w3c.github.io/trace-context/#header-value). -* Constraints - * OPTIONAL - +- Constraints + - OPTIONAL + ## Encoding ### In-memory formats -The Distributed Tracing extension uses the key `distributedtracing` for in-memory formats + +The Distributed Tracing extension uses the key `distributedtracing` for +in-memory formats ### HTTP -To integrate with existing tracing libraries, the Distributed Tracing attributes MUST -be encoded over HTTP(S) as headers. E.g. +To integrate with existing tracing libraries, the Distributed Tracing attributes +MUST be encoded over HTTP(S) as headers. E.g. ```bash CURL -X POST example/webhook.json \ diff --git a/extensions/sampled-rate.md b/extensions/sampled-rate.md index 06c2a59ec..00b683016 100644 --- a/extensions/sampled-rate.md +++ b/extensions/sampled-rate.md @@ -1,10 +1,10 @@ # Sampling extension There are many cases in an Event's life when a system (either the system -creating the event or a system transporting the event) might wish to only emit -a portion of the events that actually happened. In a high throughput system -where creating the event is costly, a system might wish to only create an event -for 1/100 of the times that something happened. Additionally, during the +creating the event or a system transporting the event) might wish to only emit a +portion of the events that actually happened. In a high throughput system where +creating the event is costly, a system might wish to only create an event for +1/100 of the times that something happened. Additionally, during the transmission of an event from the source to the eventual recipient, any step along the way might choose to only pass along a fraction of the events it receives. @@ -19,21 +19,22 @@ they impose additional sampling. ## Value -* Type: `Integer` -* Description: The rate at which this event has already been sampled. Represents +- Type: `Integer` +- Description: The rate at which this event has already been sampled. Represents the number of similar events that happened but were not sent plus this event. For example, if a system sees 30 occurrences and emits a single event, `rate` - would be 30 (29 not sent and 1 sent). - A value of `1` is the equivalent of this extension not being used at all. -* Constraints - * The rate MUST be greater than zero. + would be 30 (29 not sent and 1 sent). A value of `1` is the equivalent of this + extension not being used at all. +- Constraints + - The rate MUST be greater than zero. ## Encoding ### In-memory formats + The Sampling extension uses the key `sampledrate` for in-memory formats. ### Transport bindings -The Sampling extension does not customize any transport binding's storage -for extensions. +The Sampling extension does not customize any transport binding's storage for +extensions. diff --git a/extensions/sequence.md b/extensions/sequence.md index ad272b458..1bcfd229f 100644 --- a/extensions/sequence.md +++ b/extensions/sequence.md @@ -4,43 +4,46 @@ This extension defines two attributes that can be included within a CloudEvent to describe the position of an event in the ordered sequence of events produced by a unique event source. -The `sequence` attribute represents the value of this event's -order in the stream of events. The exact value and meaning of this -attribute is defined by the `sequencetype` attribute. -If the `sequencetype` is missing, or not defined in this specification, -event consumers will need to have some out-of-band communication with the -event producer to understand how to interpret the value of the attribute. +The `sequence` attribute represents the value of this event's order in the +stream of events. The exact value and meaning of this attribute is defined by +the `sequencetype` attribute. If the `sequencetype` is missing, or not defined +in this specification, event consumers will need to have some out-of-band +communication with the event producer to understand how to interpret the value +of the attribute. ## Attributes ### sequence -* Type: `String` -* Description: Value expressing the relative order of the event. This enables + +- Type: `String` +- Description: Value expressing the relative order of the event. This enables interpretation of data supercedence. -* Constraints - * REQUIRED - * MUST be a non-empty lexicographically-orderable string - * RECOMMENDED as monotonically increasing and contiguous +- Constraints + - REQUIRED + - MUST be a non-empty lexicographically-orderable string + - RECOMMENDED as monotonically increasing and contiguous ### sequencetype -* Type: `String` -* Description: Specifies the semantics of the sequence attribute. - See the [SequenceType Values](#sequencetype-values) section for more - information. -* Constraints: - * OPTIONAL - * If present, MUST be a non-empty string + +- Type: `String` +- Description: Specifies the semantics of the sequence attribute. See the + [SequenceType Values](#sequencetype-values) section for more information. +- Constraints: + - OPTIONAL + - If present, MUST be a non-empty string ## SequenceType Values -This specification defines the following values for `sequencetype`. -Additional values MAY be defined by other specifications. +This specification defines the following values for `sequencetype`. Additional +values MAY be defined by other specifications. ### Integer -If the `sequencetype` is set to `Integer`, the `sequence` attribute has -the following semantics: -* The values of `sequence` are string-encoded signed 32-bit Integers. -* The sequence MUST start with a value of `1` and increase by `1` for each + +If the `sequencetype` is set to `Integer`, the `sequence` attribute has the +following semantics: + +- The values of `sequence` are string-encoded signed 32-bit Integers. +- The sequence MUST start with a value of `1` and increase by `1` for each subsequent value (i.e. be contiguous and monotonically increasing). -* The sequence wraps around from 2,147,483,647 (2^31 -1) to - -2,147,483,648 (-2^31). +- The sequence wraps around from 2,147,483,647 (2^31 -1) to -2,147,483,648 + (-2^31). diff --git a/http-transport-binding.md b/http-transport-binding.md index 5b9aa12bf..7205d2423 100644 --- a/http-transport-binding.md +++ b/http-transport-binding.md @@ -2,8 +2,8 @@ ## Abstract -The HTTP Transport Binding for CloudEvents defines how events are mapped to -HTTP 1.1 request and response messages. +The HTTP Transport Binding for CloudEvents defines how events are mapped to HTTP +1.1 request and response messages. ## Status of this document @@ -12,38 +12,44 @@ This document is a working draft. ## Table of Contents 1. [Introduction](#1-introduction) + - 1.1. [Conformance](#11-conformance) - 1.2. [Relation to HTTP](#12-relation-to-http) - 1.3. [Content Modes](#13-content-modes) - 1.4. [Event Formats](#14-event-formats) - 1.5. [Security](#15-security) + 2. [Use of CloudEvents Attributes](#2-use-of-cloudevents-attributes) + - 2.1. [datacontenttype Attribute](#21-datacontenttype-attribute) - 2.2. [data Attribute](#22-data-attribute) + 3. [HTTP Message Mapping](#3-http-message-mapping) + - 3.1. [Binary Content Mode](#31-binary-content-mode) - 3.2. [Structured Content Mode](#32-structured-content-mode) - 3.3. [Batched Content Mode](#33-batched-content-mode) + 4. [References](#4-references) ## 1. Introduction -[CloudEvents][CE] is a standardized and transport-neutral definition of the -structure and metadata description of events. This specification defines how -the elements defined in the CloudEvents specification are to be used in -[HTTP 1.1][RFC7230] requests and response messages. +[CloudEvents][ce] is a standardized and transport-neutral definition of the +structure and metadata description of events. This specification defines how the +elements defined in the CloudEvents specification are to be used in [HTTP +1.1][rfc7230] requests and response messages. ### 1.1. Conformance The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC2119][RFC2119]. +interpreted as described in [RFC2119][rfc2119]. ### 1.2. Relation to HTTP This specification does not prescribe rules constraining the use or handling of -specific [HTTP methods][RFC7231-Section-4], and it also does not constrain the -[HTTP target resource][RFC7230-Section-5-1] that is used for transferring or +specific [HTTP methods][rfc7231-section-4], and it also does not constrain the +[HTTP target resource][rfc7230-section-5-1] that is used for transferring or soliciting events. Events can be transferred with all standard or application-defined HTTP request @@ -54,37 +60,37 @@ transfers. All examples herein that show HTTP methods, HTTP target URIs, and HTTP status codes are non-normative illustrations. -This specification also applies equivalently to HTTP/2 ([RFC7540][RFC7540]), +This specification also applies equivalently to HTTP/2 ([RFC7540][rfc7540]), which is compatible with HTTP 1.1 semantics. ### 1.3. Content Modes This specification defines three content modes for transferring events: -*binary*, *structured* and *batched*. Every compliant implementation SHOULD -support the *structured* and *binary* modes. +_binary_, _structured_ and _batched_. Every compliant implementation SHOULD +support the _structured_ and _binary_ modes. -In the *binary* content mode, the value of the event `data` attribute is placed +In the _binary_ content mode, the value of the event `data` attribute is placed into the HTTP request or response body as-is, with the `datacontenttype` -attribute value declaring its media type; all other event attributes are -mapped to HTTP headers. +attribute value declaring its media type; all other event attributes are mapped +to HTTP headers. -In the *structured* content mode, event metadata attributes and event data are -placed into the HTTP request or response body using an [event -format](#14-event-formats). +In the _structured_ content mode, event metadata attributes and event data are +placed into the HTTP request or response body using an +[event format](#14-event-formats). -In the *batched* content mode several events are batched into a single HTTP +In the _batched_ content mode several events are batched into a single HTTP request or response body using an [event format](#14-event-formats) that supports batching. ### 1.4. Event Formats -Event formats, used with the *structured* content mode, define how an event is -expressed in a particular data format. All implementations of this -specification MUST support the non-batching [JSON event format][JSON-format], -but MAY support any additional, including proprietary, formats. +Event formats, used with the _structured_ content mode, define how an event is +expressed in a particular data format. All implementations of this specification +MUST support the non-batching [JSON event format][json-format], but MAY support +any additional, including proprietary, formats. Event formats MAY additionally define how a batch of events is expressed. Those -can be used with the *batched* content mode +can be used with the _batched_ content mode ### 1.5. Security @@ -94,21 +100,21 @@ identically to [HTTP over TLS]([RFC2818][RFC2818]). ## 2. Use of CloudEvents Attributes -This specification does not further define any of the [CloudEvents][CE] event +This specification does not further define any of the [CloudEvents][ce] event attributes. Two of the event attributes, `datacontenttype` and `data` are handled specially and mapped onto HTTP constructs, all other attributes are transferred as metadata without further interpretation. -This mapping is intentionally robust against changes, including the addition -and removal of event attributes, and also accommodates vendor extensions to the +This mapping is intentionally robust against changes, including the addition and +removal of event attributes, and also accommodates vendor extensions to the event metadata. Any mention of event attributes other than `datacontenttype` and `data` is exemplary. ### 2.1. datacontenttype Attribute -The `datacontenttype` attribute is assumed to contain a [RFC2046][RFC2046] +The `datacontenttype` attribute is assumed to contain a [RFC2046][rfc2046] compliant media-type expression. ### 2.2. data Attribute @@ -123,7 +129,7 @@ available as a sequence of bytes. For instance, if the declared `datacontenttype` is `application/json;charset=utf-8`, the expectation is that the `data` attribute -value is made available as [UTF-8][RFC3629] encoded JSON text to HTTP. +value is made available as [UTF-8][rfc3629] encoded JSON text to HTTP. ## 3. HTTP Message Mapping @@ -132,15 +138,15 @@ The event binding is identical for both HTTP request and response messages. The content mode is chosen by the sender of the event, which is either the requesting or the responding party. Gestures that might allow solicitation of events using a particular mode might be defined by an application, but are not -defined here. The *batched* mode MUST NOT be used unless solicited, and the +defined here. The _batched_ mode MUST NOT be used unless solicited, and the gesture SHOULD allow the receiver to choose the maximum size of a batch. The receiver of the event can distinguish between the three modes by inspecting the `Content-Type` header value. If the value is prefixed with the CloudEvents -media type `application/cloudevents`, indicating the use of a known [event -format](#14-event-formats), the receiver uses *structured* mode. If the value -is prefixed with `application/cloudevents-batch`, the receiver uses the -*batched* mode. Otherwise it defaults to *binary* mode. +media type `application/cloudevents`, indicating the use of a known +[event format](#14-event-formats), the receiver uses _structured_ mode. If the +value is prefixed with `application/cloudevents-batch`, the receiver uses the +_batched_ mode. Otherwise it defaults to _binary_ mode. If a receiver detects the CloudEvents media type, but with an event format that it cannot handle, for instance `application/cloudevents+avro`, it MAY still @@ -148,12 +154,12 @@ treat the event as binary and forward it to another party as-is. ### 3.1. Binary Content Mode -The *binary* content mode accommodates any shape of event data, and allows for +The _binary_ content mode accommodates any shape of event data, and allows for efficient transfer and without transcoding effort. #### 3.1.1. HTTP Content-Type -For the *binary* mode, the HTTP `Content-Type` value maps directly to the +For the _binary_ mode, the HTTP `Content-Type` value maps directly to the CloudEvents `datacontenttype` attribute. #### 3.1.2. Event Data Encoding @@ -163,23 +169,24 @@ message body. #### 3.1.3. Metadata Headers -All [CloudEvents][CE] attributes with exception of `datacontenttype` and `data` -MUST be individually mapped to and from distinct HTTP message headers, -with exceptions noted below. +All [CloudEvents][ce] attributes with exception of `datacontenttype` and `data` +MUST be individually mapped to and from distinct HTTP message headers, with +exceptions noted below. -CloudEvents extensions that define their own attributes MAY define a -diverging mapping to HTTP headers for those attributes, especially if -specific attributes need to align with HTTP features or with -other specifications that have explicit HTTP header bindings. +CloudEvents extensions that define their own attributes MAY define a diverging +mapping to HTTP headers for those attributes, especially if specific attributes +need to align with HTTP features or with other specifications that have explicit +HTTP header bindings. -An extension specification that defines a diverging mapping rule for HTTP, -and any revision of such a specification, MUST also define explicit mapping -rules for all other transport bindings that are part of the CloudEvents core at -the time of the submission or revision. +An extension specification that defines a diverging mapping rule for HTTP, and +any revision of such a specification, MUST also define explicit mapping rules +for all other transport bindings that are part of the CloudEvents core at the +time of the submission or revision. ##### 3.1.3.1 HTTP Header Names -Except for attributes [explicitly handled in this specification](#2-use-of-cloudevents-attributes), +Except for attributes +[explicitly handled in this specification](#2-use-of-cloudevents-attributes), the naming convention for the HTTP header mapping of well-known CloudEvents attributes is that each attribute name MUST be prefixed with "ce-". @@ -189,10 +196,10 @@ Examples: * `id` maps to `ce-id` * `specversion` maps to `ce-specversion` -`Map`-typed CloudEvents attributes MUST be flattened into a set -of HTTP headers, where by the name of each header carries the prefix -"ce-", an infix reflecting the map attribute followed by a dash -("-"), and the name of the map entry key, e.g. "ce-attrib-key". +`Map`-typed CloudEvents attributes MUST be flattened into a set of HTTP headers, +where by the name of each header carries the prefix "ce-", an infix reflecting +the map attribute followed by a dash ("-"), and the name of the map entry key, +e.g. "ce-attrib-key". Note: per the [HTTP](https://tools.ietf.org/html/rfc7230#section-3.2) specification, header names are case-insensitive. @@ -200,33 +207,33 @@ specification, header names are case-insensitive. ##### 3.1.3.2 HTTP Header Values The value for each HTTP header is constructed from the respective attribute's -[JSON value][JSON-value] representation, compliant with the [JSON event -format][JSON-format] specification. +[JSON value][json-value] representation, compliant with the [JSON event +format][json-format] specification. -Some CloudEvents metadata attributes can contain arbitrary UTF-8 string -content, and per [RFC7230 Section 3][RFC7230-Section-3], HTTP headers MUST only -use printable characters from the US-ASCII character set, and are terminated by -a CRLF sequence. +Some CloudEvents metadata attributes can contain arbitrary UTF-8 string content, +and per [RFC7230 Section 3][rfc7230-section-3], HTTP headers MUST only use +printable characters from the US-ASCII character set, and are terminated by a +CRLF sequence. Therefore, and analog to the encoding rules for Universal character set host -names in URIs [RFC3986 3.2.2][RFC3986], the JSON value MUST be encoded as +names in URIs [RFC3986 3.2.2][rfc3986], the JSON value MUST be encoded as follows: Non-printable ASCII characters and non-ASCII characters MUST first be encoded -according to UTF-8, and then each octet of the corresponding UTF-8 sequence -MUST be percent-encoded to be represented as HTTP header characters, in -compliance with [RFC7230, sections 3, 3.2, 3.2.6][RFC7230-Section-3]. The -rules for encoding of the percent character ('%') apply as defined in -[RFC 3986 Section 2.4.][RFC3986-Section-2-4]. +according to UTF-8, and then each octet of the corresponding UTF-8 sequence MUST +be percent-encoded to be represented as HTTP header characters, in compliance +with [RFC7230, sections 3, 3.2, 3.2.6][rfc7230-section-3]. The rules for +encoding of the percent character ('%') apply as defined in [RFC 3986 Section +2.4.][rfc3986-section-2-4]. JSON objects and arrays are NOT surrounded with single or double quotes. #### 3.1.4 Examples -This example shows the *binary* mode mapping of an event with an HTTP POST +This example shows the _binary_ mode mapping of an event with an HTTP POST request: -``` text +```text POST /someresource HTTP/1.1 Host: webhook.example.com ce-specversion: "0.2" @@ -245,7 +252,7 @@ Content-Length: nnnn This example shows a response containing an event: -``` text +```text HTTP/1.1 200 OK ce-specversion: "0.2" ce-type: "com.example.someevent" @@ -263,18 +270,18 @@ Content-Length: nnnn ### 3.2. Structured Content Mode -The *structured* content mode keeps event metadata and data together in the +The _structured_ content mode keeps event metadata and data together in the payload, allowing simple forwarding of the same event across multiple routing hops, and across multiple transports. #### 3.2.1. HTTP Content-Type -The [HTTP `Content-Type`][Content-Type] header MUST be set to the media type of +The [HTTP `Content-Type`][content-type] header MUST be set to the media type of an [event format](#14-event-formats). -Example for the [JSON format][JSON-format]: +Example for the [JSON format][json-format]: -``` text +```text Content-Type: application/cloudevents+json; charset=UTF-8 ``` @@ -283,13 +290,13 @@ Content-Type: application/cloudevents+json; charset=UTF-8 The chosen [event format](#14-event-formats) defines how all attributes, including the `data` attribute, are represented. -The event metadata and data is then rendered in accordance with the event -format specification and the resulting data becomes the HTTP message body. +The event metadata and data is then rendered in accordance with the event format +specification and the resulting data becomes the HTTP message body. #### 3.2.3. Metadata Headers -Implementations MAY include the same HTTP headers as defined for the [binary -mode](#313-metadata-headers). +Implementations MAY include the same HTTP headers as defined for the +[binary mode](#313-metadata-headers). All CloudEvents metadata attributes MUST be mapped into the payload, even if they are also mapped into HTTP headers. @@ -298,7 +305,7 @@ they are also mapped into HTTP headers. This example shows a JSON event format encoded event, sent with a PUT request: -``` text +```text PUT /myresource HTTP/1.1 Host: webhook.example.com @@ -320,7 +327,7 @@ Content-Length: nnnn This example shows a JSON encoded event returned in a response: -``` text +```text HTTP/1.1 200 OK Content-Type: application/cloudevents+json; charset=utf-8 @@ -341,21 +348,20 @@ Content-Length: nnnn ### 3.3. Batched Content Mode -In the *batched* content mode several events are batched into a single HTTP +In the _batched_ content mode several events are batched into a single HTTP request or response body. The chosen [event format](#14-event-formats) MUST -define how a batch is represented. -Based on the [JSON format][JSON-format] (that MUST be supported by any -compliant implementation), the [JSON Batch format][JSON-batch-format] is an -event format that supports batching. +define how a batch is represented. Based on the [JSON format][json-format] (that +MUST be supported by any compliant implementation), the [JSON Batch +format][json-batch-format] is an event format that supports batching. #### 3.3.1. HTTP Content-Type -The [HTTP `Content-Type`][Content-Type] header MUST be set to the media type of +The [HTTP `Content-Type`][content-type] header MUST be set to the media type of an [event format](#14-event-formats). -Example for the [JSON Batch format][JSON-batch-format]: +Example for the [JSON Batch format][json-batch-format]: -``` text +```text Content-Type: application/cloudevents-batch+json; charset=UTF-8 ``` @@ -367,15 +373,15 @@ all event attributes, including the `data` attribute, are represented. The batch of events is then rendered in accordance with the event format specification and the resulting data becomes the HTTP message body. -The batch MAY be empty. -All batched CloudEvents MUST have the same `specversion` attribute. Other -attributes MAY differ, including the `datacontenttype` attribute. +The batch MAY be empty. All batched CloudEvents MUST have the same `specversion` +attribute. Other attributes MAY differ, including the `datacontenttype` +attribute. #### 3.2.3 Examples This example shows two batched CloudEvents, sent with a PUT request: -``` text +```text PUT /myresource HTTP/1.1 Host: webhook.example.com @@ -409,7 +415,7 @@ Content-Length: nnnn This example shows two batched CloudEvents returned in a response: -``` text +```text HTTP/1.1 200 OK Content-Type: application/cloudevents-batch+json; charset=utf-8 @@ -442,42 +448,43 @@ Content-Length: nnnn ## 4. References -- [RFC2046][RFC2046] Multipurpose Internet Mail Extensions (MIME) Part Two: +- [RFC2046][rfc2046] Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types -- [RFC2119][RFC2119] Key words for use in RFCs to Indicate Requirement Levels -- [RFC2818][RFC2818] HTTP over TLS -- [RFC3629][RFC3629] UTF-8, a transformation format of ISO 10646 -- [RFC3986][RFC3986] Uniform Resource Identifier (URI): Generic Syntax -- [RFC4627][RFC4627] The application/json Media Type for JavaScript Object +- [RFC2119][rfc2119] Key words for use in RFCs to Indicate Requirement Levels +- [RFC2818][rfc2818] HTTP over TLS +- [RFC3629][rfc3629] UTF-8, a transformation format of ISO 10646 +- [RFC3986][rfc3986] Uniform Resource Identifier (URI): Generic Syntax +- [RFC4627][rfc4627] The application/json Media Type for JavaScript Object Notation (JSON) -- [RFC4648][RFC4648] The Base16, Base32, and Base64 Data Encodings -- [RFC6839][RFC6839] Additional Media Type Structured Syntax Suffixes -- [RFC7159][RFC7159] The JavaScript Object Notation (JSON) Data Interchange Format -- [RFC7230][RFC7230] Hypertext Transfer Protocol (HTTP/1.1): Message Syntax - and Routing -- [RFC7231][RFC7231] Hypertext Transfer Protocol (HTTP/1.1): Semantics and +- [RFC4648][rfc4648] The Base16, Base32, and Base64 Data Encodings +- [RFC6839][rfc6839] Additional Media Type Structured Syntax Suffixes +- [RFC7159][rfc7159] The JavaScript Object Notation (JSON) Data Interchange + Format +- [RFC7230][rfc7230] Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and + Routing +- [RFC7231][rfc7231] Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content -- [RFC7540][RFC7540] Hypertext Transfer Protocol Version 2 (HTTP/2) - -[CE]: ./spec.md -[JSON-format]: ./json-format.md -[JSON-batch-format]: ./json-format.md#4-json-batch-format -[Content-Type]: https://tools.ietf.org/html/rfc7231#section-3.1.1.5 -[JSON-Value]: https://tools.ietf.org/html/rfc7159#section-3 -[JSON-Array]: https://tools.ietf.org/html/rfc7159#section-5 -[RFC2046]: https://tools.ietf.org/html/rfc2046 -[RFC2119]: https://tools.ietf.org/html/rfc2119 -[RFC2818]: https://tools.ietf.org/html/rfc2818 -[RFC3629]: https://tools.ietf.org/html/rfc3629 -[RFC3986]: https://tools.ietf.org/html/rfc3986 -[RFC3986-Section-2-4]: https://tools.ietf.org/html/rfc3986#section-2.4 -[RFC4627]: https://tools.ietf.org/html/rfc4627 -[RFC4648]: https://tools.ietf.org/html/rfc4648 -[RFC6839]: https://tools.ietf.org/html/rfc6839#section-3.1 -[RFC7159]: https://tools.ietf.org/html/rfc7159 -[RFC7230]: https://tools.ietf.org/html/rfc7230 -[RFC7231]: https://tools.ietf.org/html/rfc7231 -[RFC7230-Section-3]: https://tools.ietf.org/html/rfc7230#section-3 -[RFC7231-Section-4]: https://tools.ietf.org/html/rfc7231#section-4 -[RFC7230-Section-5-1]: https://tools.ietf.org/html/rfc7230#section-5.1 -[RFC7540]: https://tools.ietf.org/html/rfc7540 +- [RFC7540][rfc7540] Hypertext Transfer Protocol Version 2 (HTTP/2) + +[ce]: ./spec.md +[json-format]: ./json-format.md +[json-batch-format]: ./json-format.md#4-json-batch-format +[content-type]: https://tools.ietf.org/html/rfc7231#section-3.1.1.5 +[json-value]: https://tools.ietf.org/html/rfc7159#section-3 +[json-array]: https://tools.ietf.org/html/rfc7159#section-5 +[rfc2046]: https://tools.ietf.org/html/rfc2046 +[rfc2119]: https://tools.ietf.org/html/rfc2119 +[rfc2818]: https://tools.ietf.org/html/rfc2818 +[rfc3629]: https://tools.ietf.org/html/rfc3629 +[rfc3986]: https://tools.ietf.org/html/rfc3986 +[rfc3986-section-2-4]: https://tools.ietf.org/html/rfc3986#section-2.4 +[rfc4627]: https://tools.ietf.org/html/rfc4627 +[rfc4648]: https://tools.ietf.org/html/rfc4648 +[rfc6839]: https://tools.ietf.org/html/rfc6839#section-3.1 +[rfc7159]: https://tools.ietf.org/html/rfc7159 +[rfc7230]: https://tools.ietf.org/html/rfc7230 +[rfc7231]: https://tools.ietf.org/html/rfc7231 +[rfc7230-section-3]: https://tools.ietf.org/html/rfc7230#section-3 +[rfc7231-section-4]: https://tools.ietf.org/html/rfc7231#section-4 +[rfc7230-section-5-1]: https://tools.ietf.org/html/rfc7230#section-5.1 +[rfc7540]: https://tools.ietf.org/html/rfc7540 diff --git a/http-webhook.md b/http-webhook.md index 372d22482..1144c6aef 100644 --- a/http-webhook.md +++ b/http-webhook.md @@ -5,7 +5,7 @@ "Webhooks" are a popular pattern to deliver notifications between applications and via HTTP endpoints. In spite of pattern usage being widespread, there is no formal definition for Web Hooks. This specification aims to provide such a -definition for use with [CNCF CloudEvents][CE], but is considered generally +definition for use with [CNCF CloudEvents][ce], but is considered generally usable beyond the scope of CloudEvents. ## Status of this document @@ -15,8 +15,10 @@ This document is a working draft. ## Table of Contents 1. [Introduction](#1-introduction) + - 1.1. [Conformance](#11-conformance) - 1.2. [Relation to HTTP](#12-relation-to-http) + 2. [Delivering notifications](#2-delivering-notifications) 3. [Authorization](#3-authorization) 4. [Abuse Protection](#4-abuse-protection) @@ -24,7 +26,7 @@ This document is a working draft. ## 1. Introduction -["Webhooks"][Webhooks] are a popular pattern to deliver notifications between +["Webhooks"][webhooks] are a popular pattern to deliver notifications between applications and via HTTP endpoints. Applications that make notifications available, allow for other applications to register an HTTP endpoint to which notifications are delivered. @@ -38,14 +40,14 @@ for flooding arbitrary HTTP sites with requests. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC2119][RFC2119]. +interpreted as described in [RFC2119][rfc2119]. ### 1.2. Relation to HTTP This specification prescribes rules constraining the use and handling of -specific [HTTP methods][RFC7231-Section-4] and headers. +specific [HTTP methods][rfc7231-section-4] and headers. -This specification also applies equivalently to HTTP/2 ([RFC7540][RFC7540]), +This specification also applies equivalently to HTTP/2 ([RFC7540][rfc7540]), which is compatible with HTTP 1.1 semantics. ## 2. Delivering notifications @@ -55,28 +57,29 @@ which is compatible with HTTP 1.1 semantics. Notifications are delivered using a HTTP request. The response indicates the resulting status of the delivery. -HTTP-over-TLS (HTTPS) [RFC2818][RFC2818] MUST be used for the connection. +HTTP-over-TLS (HTTPS) [RFC2818][rfc2818] MUST be used for the connection. -The HTTP method for the delivery request MUST be [POST][POST]. +The HTTP method for the delivery request MUST be [POST][post]. -The [`Content-Type`][Content-Type] header MUST be carried and the request MUST +The [`Content-Type`][content-type] header MUST be carried and the request MUST carry a notification payload of the given content type. Requests without -payloads, e.g. where the notification is entirely expressed in HTTP headers, -are not permitted by this specification. +payloads, e.g. where the notification is entirely expressed in HTTP headers, are +not permitted by this specification. This specification does not further constrain the content of the notification, -and it also does not prescribe the [HTTP target resource][RFC7230-Section-5-1] +and it also does not prescribe the [HTTP target resource][rfc7230-section-5-1] that is used for delivery. -If the delivery target supports and requires [Abuse Protection](#4-abuse-protection), -the delivery request MUST include the `Origin` header. The `Origin` header value -is a DNS name expression that identifies the sending system. +If the delivery target supports and requires +[Abuse Protection](#4-abuse-protection), the delivery request MUST include the +`Origin` header. The `Origin` header value is a DNS name expression that +identifies the sending system. ### 2.2. Delivery response -The delivery response MAY contain a payload providing detail status -information in the case of handling errors. This specification does not attempt -to define such a payload. +The delivery response MAY contain a payload providing detail status information +in the case of handling errors. This specification does not attempt to define +such a payload. The response MUST NOT use any of the [3xx HTTP Redirect status codes][3xx] and the client MUST NOT follow any such redirection. @@ -84,7 +87,7 @@ the client MUST NOT follow any such redirection. If the delivery has been accepted and processed, and if the response carries a payload with processing details, the response MUST have the [200 OK][200] or [201 Created][201] status code. In this case, the response MUST carry a -[`Content-Type`][Content-Type] header. +[`Content-Type`][content-type] header. If the delivery has been accepted and processed, but carries no payload, the response MUST have the [201 Created][201] or [204 No Content][204] status code. @@ -93,44 +96,44 @@ If the delivery has been accepted, but has not yet been processed or if the processing status is unknown, the response MUST have the [202 Accepted][202] status code. -If a delivery target has been retired, but the HTTP site still exists, the -site SHOULD return a [410 Gone][410] status code and the sender SHOULD refrain -from sending any further notifications. +If a delivery target has been retired, but the HTTP site still exists, the site +SHOULD return a [410 Gone][410] status code and the sender SHOULD refrain from +sending any further notifications. If the delivery target is unable to process the request due to exceeding a request rate limit, it SHOULD return a [429 Too Many Requests][429] status code -and MUST include the [`Retry-After`][Retry-After] header. The sender MUST +and MUST include the [`Retry-After`][retry-after] header. The sender MUST observe the value of the Retry-After header and refrain from sending further requests until the indicated time. -If the delivery cannot be accepted because the notification format has not -been understood, the service MUST respond with status code -[415 Unsupported Media Type][415]. +If the delivery cannot be accepted because the notification format has not been +understood, the service MUST respond with status code [415 Unsupported Media +Type][415]. -All further error status codes apply as specified in [RFC7231][RFC7231]. +All further error status codes apply as specified in [RFC7231][rfc7231]. ## 3. Authorization The delivery request MUST use one of the following two methods, both of which -lean on the OAuth 2.0 Bearer Token [RFC6750][RFC6750] model. +lean on the OAuth 2.0 Bearer Token [RFC6750][rfc6750] model. The delivery target MUST support both methods. -The client MAY use any token-based authorization scheme. The token can take any shape, -and can be a standardized token format or a simple key expression. +The client MAY use any token-based authorization scheme. The token can take any +shape, and can be a standardized token format or a simple key expression. Challenge-based schemes MUST NOT be used. -### 3.1. Authorization Request Header Field +### 3.1. Authorization Request Header Field -The access token is sent in the [`Authorization`][Authorization] request -header field defined by HTTP/1.1. +The access token is sent in the [`Authorization`][authorization] request header +field defined by HTTP/1.1. -For [OAuth 2.0 Bearer][Bearer] tokens, the "Bearer" scheme MUST be used. +For [OAuth 2.0 Bearer][bearer] tokens, the "Bearer" scheme MUST be used. Example: -``` text +```text POST /resource HTTP/1.1 Host: server.example.com Authorization: Bearer mF_9.B5f-4.1JqM @@ -140,12 +143,12 @@ Authorization: Bearer mF_9.B5f-4.1JqM When sending the access token in the HTTP request URI, the client adds the access token to the request URI query component as defined by "Uniform Resource -Identifier (URI): Generic Syntax" [RFC3986][RFC3986], using the "access_token" +Identifier (URI): Generic Syntax" [RFC3986][rfc3986], using the "access_token" parameter. For example, the client makes the following HTTP request: -``` text +```text POST /resource?access_token=mF_9.B5f-4.1JqM HTTP/1.1 Host: server.example.com ``` @@ -158,43 +161,44 @@ For example: https://server.example.com/resource?access_token=mF_9.B5f-4.1JqM&p=q -Clients using the URI Query Parameter method SHOULD also send a -Cache-Control header containing the "no-store" option. Server -success (2XX status) responses to these requests SHOULD contain a -Cache-Control header with the "private" option. +Clients using the URI Query Parameter method SHOULD also send a Cache-Control +header containing the "no-store" option. Server success (2XX status) responses +to these requests SHOULD contain a Cache-Control header with the "private" +option. -Because of the security weaknesses associated with the URI method (see -[RFC6750, Section 5][RFC6750]), including the high likelihood that the URL -containing the access token will be logged, it SHOULD NOT be used unless it is -impossible to transport the access token in the "Authorization" request header -field or the HTTP request entity-body. All further caveats cited in -[RFC6750][RFC6750] apply equivalently. +Because of the security weaknesses associated with the URI method (see [RFC6750, +Section 5][rfc6750]), including the high likelihood that the URL containing the +access token will be logged, it SHOULD NOT be used unless it is impossible to +transport the access token in the "Authorization" request header field or the +HTTP request entity-body. All further caveats cited in [RFC6750][rfc6750] apply +equivalently. ## 4. Abuse Protection Any system that allows registration of and delivery of notifications to arbitrary HTTP endpoints can potentially be abused such that someone maliciously or inadvertently registers the address of a system that does not expect such -requests and for which the registering party is not authorized to perform such -a registration. In extreme cases, a notification infrastructure could be abused -to launch denial-of-service attacks against an arbitrary web-site. +requests and for which the registering party is not authorized to perform such a +registration. In extreme cases, a notification infrastructure could be abused to +launch denial-of-service attacks against an arbitrary web-site. To protect the sender from being abused in such a way, a legitimate delivery -target needs to indicate that it agrees with notifications being delivered to it. +target needs to indicate that it agrees with notifications being delivered to +it. Reaching the delivery agreement is realized using the following validation -handshake. The handshake can either be executed immediately at registration -time or as a "pre-flight" request immediately preceding a delivery. If the -handshake outcome is that the delivery is denied, the sender MUST NOT deliver -events to the target. - -It is important to understand is that the handshake does not aim to establish -an authentication or authorization context. It only serves to protect the -sender from being told to a push to a destination that is not expecting the -traffic. While this specification mandates use of an authorization model, this -mandate is not sufficient to protect any arbitrary website from unwanted -traffic if that website doesn't implement access control and therefore ignores -the `Authorization` header. +handshake. The handshake can either be executed immediately at registration time +or as a "pre-flight" request immediately preceding a delivery. If the handshake +outcome is that the delivery is denied, the sender MUST NOT deliver events to +the target. + +It is important to understand is that the handshake does not aim to establish an +authentication or authorization context. It only serves to protect the sender +from being told to a push to a destination that is not expecting the traffic. +While this specification mandates use of an authorization model, this mandate is +not sufficient to protect any arbitrary website from unwanted traffic if that +website doesn't implement access control and therefore ignores the +`Authorization` header. Delivery targets SHOULD support the abuse protection feature. If a target does not support the feature, the sender MAY choose not to send to the target, at @@ -202,12 +206,11 @@ all, or send only at a very low request rate. ### 4.1. Validation request -The validation request uses the HTTP [OPTIONS][OPTIONS] method. The request -is directed to the exact resource target URI that is being registered. +The validation request uses the HTTP [OPTIONS][options] method. The request is +directed to the exact resource target URI that is being registered. -With the validation request, the sender asks the target for permission to -send notifications, and it can declare a desired request rate (requests per -minute). +With the validation request, the sender asks the target for permission to send +notifications, and it can declare a desired request rate (requests per minute). The delivery target will respond with a permission statement and the permitted request rate. @@ -229,8 +232,8 @@ of this header. Example: -``` text -WebHook-Request-Origin: eventemitter.example.com +```text +WebHook-Request-Origin: eventemitter.example.com ``` #### 4.1.3. WebHook-Request-Callback @@ -239,23 +242,24 @@ The `WebHook-Request-Callback` header is OPTIONAL and augments the `WebHook-Request-Origin` header. It allows the delivery target to grant send permission asynchronously, via a simple HTTPS callback. -If the receiving application does not explicitly support the handshake -described here, an administrator could nevertheless still find the callback URL -in the log, and call it manually and therewith grant access. +If the receiving application does not explicitly support the handshake described +here, an administrator could nevertheless still find the callback URL in the +log, and call it manually and therewith grant access. -The delivery target grants permission by issuing an HTTPS GET or POST request against -the given URL. The HTTP GET request can be performed manually using a browser -client. +The delivery target grants permission by issuing an HTTPS GET or POST request +against the given URL. The HTTP GET request can be performed manually using a +browser client. -The delivery target MAY include the `WebHook-Allowed-Rate` response in the callback. +The delivery target MAY include the `WebHook-Allowed-Rate` response in the +callback. The URL is not formally constrained, but it SHOULD contain an identifier for the -delivery target along with a secret key that makes the URL difficult to guess so that -3rd parties cannot spoof the delivery target. +delivery target along with a secret key that makes the URL difficult to guess so +that 3rd parties cannot spoof the delivery target. For example: -``` text +```text WebHook-Request-Callback: https://example.com/confirm?id=12345&key=...base64... ``` @@ -269,7 +273,7 @@ zero and expresses the request rate in "requests per minute". For example, the following header asks for permission to send 120 requests per minute: -``` text +```text WebHook-Request-Rate: 120 ``` @@ -279,18 +283,18 @@ If and only if the delivery target does allow delivery of the events, it MUST reply to the request by including the `WebHook-Allowed-Origin` and `WebHook-Allowed-Rate` headers. -If the delivery target chooses to grant permission by callback, it withholds -the response headers. +If the delivery target chooses to grant permission by callback, it withholds the +response headers. If the delivery target does not allow delivery of the events or does not expect delivery of events and nevertheless handles the HTTP OPTIONS method, the existing response ought not to be interpreted as consent, and therefore the -handshake cannot rely on status codes. If the delivery target otherwise does -not handle the HTTP OPTIONS method, it SHOULD respond with HTTP status code -405, as if OPTIONS were not supported. +handshake cannot rely on status codes. If the delivery target otherwise does not +handle the HTTP OPTIONS method, it SHOULD respond with HTTP status code 405, as +if OPTIONS were not supported. -The OPTIONS response SHOULD include the [Allow][Allow] header indicating the -[POST][POST] method being permitted. Other methods MAY be permitted on the +The OPTIONS response SHOULD include the [Allow][allow] header indicating the +[POST][post] method being permitted. Other methods MAY be permitted on the resource, but their function is outside the scope of this specification. #### 4.2.1. WebHook-Allowed-Origin @@ -298,79 +302,79 @@ resource, but their function is outside the scope of this specification. The `WebHook-Allowed-Origin` header MUST be returned when the delivery target agrees to notification delivery by the origin service. Its value MUST either be the origin name supplied in the `WebHook-Request-Origin` header, or a singular -asterisk character ('*'), indicating that the delivery target supports +asterisk character ('\*'), indicating that the delivery target supports notifications from all origins. -``` text +```text WebHook-Allowed-Origin: eventemitter.example.com ``` or -``` text +```text WebHook-Request-Origin: * ``` #### 4.2.2. WebHook-Allowed-Rate -The `WebHook-Allowed-Rate` header MUST be returned if the request contained -the `WebHook-Request-Rate`, otherwise it SHOULD be returned. +The `WebHook-Allowed-Rate` header MUST be returned if the request contained the +`WebHook-Request-Rate`, otherwise it SHOULD be returned. The header grants permission to send notifications at the specified rate. The -value is either an asterisk character or the string representation of a -positive integer number greater than zero. The asterisk indicates that there is -no rate limitation. An integer number expresses the permitted request rate in -"requests per minute". For request rates exceeding the granted notification -rate, the sender ought to expect request throttling. Throttling is indicated -by requests being rejected using HTTP status code [429 Too Many Requests][429]. - -For example, the following header permits to send 100 requests per -minute: +value is either an asterisk character or the string representation of a positive +integer number greater than zero. The asterisk indicates that there is no rate +limitation. An integer number expresses the permitted request rate in "requests +per minute". For request rates exceeding the granted notification rate, the +sender ought to expect request throttling. Throttling is indicated by requests +being rejected using HTTP status code [429 Too Many Requests][429]. + +For example, the following header permits to send 100 requests per minute: -``` text +```text WebHook-Allowed-Rate: 100 ``` ## 5. References -- [RFC2119][RFC2119] Key words for use in RFCs to Indicate Requirement Levels -- [RFC2818][RFC2818] HTTP over TLS -- [RFC6750][RFC6750] The OAuth 2.0 Authorization Framework: Bearer Token Usage -- [RFC6585][RFC6585] Additional HTTP Status Codes -- [RFC7230][RFC7230] Hypertext Transfer Protocol (HTTP/1.1): Message Syntax - and Routing -- [RFC7231][RFC7231] Hypertext Transfer Protocol (HTTP/1.1): Semantics and +- [RFC2119][rfc2119] Key words for use in RFCs to Indicate Requirement Levels +- [RFC2818][rfc2818] HTTP over TLS +- [RFC6750][rfc6750] The OAuth 2.0 Authorization Framework: Bearer Token Usage +- [RFC6585][rfc6585] Additional HTTP Status Codes +- [RFC7230][rfc7230] Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and + Routing +- [RFC7231][rfc7231] Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content -- [RFC7235][RFC7235] Hypertext Transfer Protocol (HTTP/1.1): Authentication -- [RFC7540][RFC7540] Hypertext Transfer Protocol Version 2 (HTTP/2) - -[CE]: ./spec.md -[Webhooks]: http://progrium.com/blog/2007/05/03/web-hooks-to-revolutionize-the-web/ -[Content-Type]: https://tools.ietf.org/html/rfc7231#section-3.1.1.5 -[Retry-After]: https://tools.ietf.org/html/rfc7231#section-7.1.3 -[Authorization]: https://tools.ietf.org/html/rfc7235#section-4.2 -[Allow]: https://tools.ietf.org/html/rfc7231#section-7.4.1 -[POST]: https://tools.ietf.org/html/rfc7231#section-4.3.3 -[OPTIONS]: https://tools.ietf.org/html/rfc7231#section-4.3.7 +- [RFC7235][rfc7235] Hypertext Transfer Protocol (HTTP/1.1): Authentication +- [RFC7540][rfc7540] Hypertext Transfer Protocol Version 2 (HTTP/2) + +[ce]: ./spec.md +[webhooks]: + http://progrium.com/blog/2007/05/03/web-hooks-to-revolutionize-the-web/ +[content-type]: https://tools.ietf.org/html/rfc7231#section-3.1.1.5 +[retry-after]: https://tools.ietf.org/html/rfc7231#section-7.1.3 +[authorization]: https://tools.ietf.org/html/rfc7235#section-4.2 +[allow]: https://tools.ietf.org/html/rfc7231#section-7.4.1 +[post]: https://tools.ietf.org/html/rfc7231#section-4.3.3 +[options]: https://tools.ietf.org/html/rfc7231#section-4.3.7 [3xx]: https://tools.ietf.org/html/rfc7231#section-6.4 [200]: https://tools.ietf.org/html/rfc7231#section-6.3.1 [201]: https://tools.ietf.org/html/rfc7231#section-6.3.2 [202]: https://tools.ietf.org/html/rfc7231#section-6.3.3 [204]: https://tools.ietf.org/html/rfc7231#section-6.3.5 -[410]:https://tools.ietf.org/html/rfc7231#section-6.5.9 +[410]: https://tools.ietf.org/html/rfc7231#section-6.5.9 [415]: https://tools.ietf.org/html/rfc7231#section-6.5.13 [429]: https://tools.ietf.org/html/rfc6585#section-4 -[Bearer]:https://tools.ietf.org/html/rfc6750#section-2.1 -[RFC2119]: https://tools.ietf.org/html/rfc2119 -[RFC3986]: https://tools.ietf.org/html/rfc3986 -[RFC2818]: https://tools.ietf.org/html/rfc2818 -[RFC6585]: https://tools.ietf.org/html/rfc6585 -[RFC6750]: https://tools.ietf.org/html/rfc6750 -[RFC7159]: https://tools.ietf.org/html/rfc7159 -[RFC7230]: https://tools.ietf.org/html/rfc7230 -[RFC7230-Section-3]: https://tools.ietf.org/html/rfc7230#section-3 -[RFC7231-Section-4]: https://tools.ietf.org/html/rfc7231#section-4 -[RFC7230-Section-5-1]: https://tools.ietf.org/html/rfc7230#section-5.1 -[RFC7231]: https://tools.ietf.org/html/rfc7231 -[RFC7235]: https://tools.ietf.org/html/rfc7235 -[RFC7540]: https://tools.ietf.org/html/rfc7540 \ No newline at end of file +[bearer]: https://tools.ietf.org/html/rfc6750#section-2.1 +[rfc2119]: https://tools.ietf.org/html/rfc2119 +[rfc3986]: https://tools.ietf.org/html/rfc3986 +[rfc2818]: https://tools.ietf.org/html/rfc2818 +[rfc6585]: https://tools.ietf.org/html/rfc6585 +[rfc6750]: https://tools.ietf.org/html/rfc6750 +[rfc7159]: https://tools.ietf.org/html/rfc7159 +[rfc7230]: https://tools.ietf.org/html/rfc7230 +[rfc7230-section-3]: https://tools.ietf.org/html/rfc7230#section-3 +[rfc7231-section-4]: https://tools.ietf.org/html/rfc7231#section-4 +[rfc7230-section-5-1]: https://tools.ietf.org/html/rfc7230#section-5.1 +[rfc7231]: https://tools.ietf.org/html/rfc7231 +[rfc7235]: https://tools.ietf.org/html/rfc7235 +[rfc7540]: https://tools.ietf.org/html/rfc7540 diff --git a/json-format.md b/json-format.md index 703c76580..647cf7076 100644 --- a/json-format.md +++ b/json-format.md @@ -2,8 +2,8 @@ ## Abstract -The JSON Format for CloudEvents defines how events are expressed in -JavaScript Object Notation (JSON) Data Interchange Format ([RFC8259][RFC8259]). +The JSON Format for CloudEvents defines how events are expressed in JavaScript +Object Notation (JSON) Data Interchange Format ([RFC8259][rfc8259]). ## Status of this document @@ -19,11 +19,10 @@ This document is a working draft. ## 1. Introduction -[CloudEvents][CE] is a standardized and transport-neutral definition of the -structure and metadata description of events. This specification defines how -the elements defined in the CloudEvents specification are to be represented in -the JavaScript Object Notation (JSON) Data Interchange Format -([RFC8259][RFC8259]). +[CloudEvents][ce] is a standardized and transport-neutral definition of the +structure and metadata description of events. This specification defines how the +elements defined in the CloudEvents specification are to be represented in the +JavaScript Object Notation (JSON) Data Interchange Format ([RFC8259][rfc8259]). The [Attributes](#2-attributes) section describes the naming conventions and data type mappings for CloudEvents attributes. @@ -35,89 +34,89 @@ attributes and an associated media type. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC2119][RFC2119]. +interpreted as described in [RFC2119][rfc2119]. ## 2. Attributes This section defines how CloudEvents attributes are mapped to JSON. This -specification does not explicitly map each attribute, but -provides a generic mapping model that applies to all current and future -CloudEvents attributes, including extensions. +specification does not explicitly map each attribute, but provides a generic +mapping model that applies to all current and future CloudEvents attributes, +including extensions. For clarity, extension attributes are serialized using the same rules as specification defined attributes. This includes their syntax and placement -within the JSON object. In particular, extensions are placed as top-level -JSON properties. Extensions themselves are free to have nested properties, -however the root of the extension MUST be serialized as a top-level JSON -property. There were many reason for this design decision and they are covered -in more detail in the [Primer](primer.md#json-extensions). +within the JSON object. In particular, extensions are placed as top-level JSON +properties. Extensions themselves are free to have nested properties, however +the root of the extension MUST be serialized as a top-level JSON property. There +were many reason for this design decision and they are covered in more detail in +the [Primer](primer.md#json-extensions). ### 2.1. Base Type System -The core [CloudEvents specification][CE] defines a minimal abstract type -system, which this mapping leans on. +The core [CloudEvents specification][ce] defines a minimal abstract type system, +which this mapping leans on. ### 2.2. Type System Mapping The CloudEvents type system MUST be mapped to JSON types as follows, with exceptions noted below. -| CloudEvents | JSON -|---------------|------------------------------------------------------------- -| String | [string][JSON-String] -| Integer | [number][JSON-Number], only the `int` component is permitted -| Binary | [string][JSON-String], [Base64-encoded][base64] binary -| URI-reference | [string][JSON-String] following [RFC 3986][RFC3986] -| Timestamp | [string][JSON-String] following [RFC 3339][RFC3339] (ISO 8601) -| Map | [JSON object][JSON-Object] -| Any | [JSON value][JSON-Value] +| CloudEvents | JSON | +| ------------- | -------------------------------------------------------------- | +| String | [string][json-string] | +| Integer | [number][json-number], only the `int` component is permitted | +| Binary | [string][json-string], [Base64-encoded][base64] binary | +| URI-reference | [string][json-string] following [RFC 3986][rfc3986] | +| Timestamp | [string][json-string] following [RFC 3339][rfc3339] (ISO 8601) | +| Map | [JSON object][json-object] | +| Any | [JSON value][json-value] | Extension specifications MAY define diverging mapping rules for the values of attributes they define. -For instance, the attribute value might be a data structure -defined in a standard outside of CloudEvents, with a formal JSON mapping, and -there might be risk of translation errors or information loss when the original -format is not preserved. +For instance, the attribute value might be a data structure defined in a +standard outside of CloudEvents, with a formal JSON mapping, and there might be +risk of translation errors or information loss when the original format is not +preserved. -An extension specification that defines a diverging mapping rule for JSON, -and any revision of such a specification, MUST also define explicit mapping -rules for all other event formats that are part of the CloudEvents core at -the time of the submission or revision. +An extension specification that defines a diverging mapping rule for JSON, and +any revision of such a specification, MUST also define explicit mapping rules +for all other event formats that are part of the CloudEvents core at the time of +the submission or revision. -If required, like when decoding Maps, the CloudEvents type can be determined -by inference using the rules from the mapping table, whereby the only potentially -ambiguous JSON data type is `string`. The value is compatible with the respective -CloudEvents type when the mapping rules are fulfilled. +If required, like when decoding Maps, the CloudEvents type can be determined by +inference using the rules from the mapping table, whereby the only potentially +ambiguous JSON data type is `string`. The value is compatible with the +respective CloudEvents type when the mapping rules are fulfilled. ### 2.3. Mapping Any-typed Attributes The CloudEvents `data` attribute is `Any`-typed, meaning that it holds a value of any valid type. `Map` entry values are also `Any` typed. -If an implementation determines that the actual type of an `Any` is a -`String`, the value MUST be represented as [JSON string][JSON-String] -expression; for `Binary`, the value MUST represented as [JSON -string][JSON-String] expression containing the [Base64][base64] encoded binary -value; for `Map`, the value MUST be represented as a [JSON object][JSON-Object] -expression, whereby the index fields become member names and the associated -values become the respective member's value. +If an implementation determines that the actual type of an `Any` is a `String`, +the value MUST be represented as [JSON string][json-string] expression; for +`Binary`, the value MUST represented as [JSON string][json-string] expression +containing the [Base64][base64] encoded binary value; for `Map`, the value MUST +be represented as a [JSON object][json-object] expression, whereby the index +fields become member names and the associated values become the respective +member's value. ### 2.4. Examples The following table shows exemplary mappings: -| CloudEvents | Type | Exemplary JSON Value -|--------------------|---------------|-------------------------- -| type | String | "com.example.someevent" -| specversion | String | "0.2" -| source | URI-reference | "/mycontext" -| id | String | "1234-1234-1234" -| time | Timestamp | "2018-04-05T17:31:00Z" -| datacontenttype | String | "application/json" -| data | String | "" -| data | Binary | "Q2xvdWRFdmVudHM=" -| data | Map | { "objA" : "vA", "objB", "vB" } +| CloudEvents | Type | Exemplary JSON Value | +| --------------- | ------------- | ------------------------------- | +| type | String | "com.example.someevent" | +| specversion | String | "0.2" | +| source | URI-reference | "/mycontext" | +| id | String | "1234-1234-1234" | +| time | Timestamp | "2018-04-05T17:31:00Z" | +| datacontenttype | String | "application/json" | +| data | String | "" | +| data | Binary | "Q2xvdWRFdmVudHM=" | +| data | Map | { "objA" : "vA", "objB", "vB" } | ### 2.5. JSONSchema Validation @@ -137,44 +136,42 @@ the [type system mapping](#22-type-system-mapping). ### 3.1. Special Handling of the "data" Attribute -The mapping of the `Any`-typed `data` attribute follows the rules laid out -in [Section 2.3.](#23-mapping-any-typed-attributes), with two additional -rules: +The mapping of the `Any`-typed `data` attribute follows the rules laid out in +[Section 2.3.](#23-mapping-any-typed-attributes), with two additional rules: First, if an implementation determines that the type of the `data` attribute is `Binary` or `String`, it MUST inspect the `datacontenttype` attribute to determine whether it is indicated that the data value contains JSON data. -If the `datacontenttype` value is either ["application/json"][RFC4627] or any -media type with a [structured +json suffix][RFC6839], the implementation MUST -translate the `data` attribute value into a [JSON value][JSON-Value], and set +If the `datacontenttype` value is either ["application/json"][rfc4627] or any +media type with a [structured +json suffix][rfc6839], the implementation MUST +translate the `data` attribute value into a [JSON value][json-value], and set the `data` attribute of the envelope JSON object to this JSON value. -If the `datacontenttype` value does not follow the -[structured +json suffix][RFC6839] but is known to use JSON encoding, the -implementation MUST translate the `data` attribute value into a -[JSON value][JSON-Value], and set the `data` attribute of the envelope -JSON object to this JSON value. Its typical examples are, but not limited to, -`text/json`, [`application/json-seq`][JSON-seq] and -[`application/geo+json-seq`][JSON-geoseq]. - -Unlike all other attributes, for which value types are restricted to strings -per the [type-system mapping](#22-type-system-mapping), the resulting `data` -member [JSON value][JSON-Value] is unrestricted, and MAY also contain numeric -and logical JSON types. - -Second, whether a Base64-encoded string in the data attribute is treated -as `Binary` or as a `String` is also determined by the `datacontenttype` value. -If the `datacontenttype` media type is known to contain text, the data -attribute value is not further interpreted and treated as a text string. -Otherwise, it is decoded and treated as a binary value. - +If the `datacontenttype` value does not follow the [structured +json +suffix][rfc6839] but is known to use JSON encoding, the implementation MUST +translate the `data` attribute value into a [JSON value][json-value], and set +the `data` attribute of the envelope JSON object to this JSON value. Its typical +examples are, but not limited to, `text/json`, +[`application/json-seq`][json-seq] and +[`application/geo+json-seq`][json-geoseq]. + +Unlike all other attributes, for which value types are restricted to strings per +the [type-system mapping](#22-type-system-mapping), the resulting `data` member +[JSON value][json-value] is unrestricted, and MAY also contain numeric and +logical JSON types. + +Second, whether a Base64-encoded string in the data attribute is treated as +`Binary` or as a `String` is also determined by the `datacontenttype` value. If +the `datacontenttype` media type is known to contain text, the data attribute +value is not further interpreted and treated as a text string. Otherwise, it is +decoded and treated as a binary value. ### 3.2. Examples Example event with `String`-valued `data`: -``` JSON +```JSON { "specversion" : "0.2", "type" : "com.example.someevent", @@ -192,7 +189,7 @@ Example event with `String`-valued `data`: Example event with `Binary`-valued data -``` JSON +```JSON { "specversion" : "0.2", "type" : "com.example.someevent", @@ -208,10 +205,10 @@ Example event with `Binary`-valued data } ``` -Example event with JSON data for the "data" member, either derived from -a `Map` or [JSON data](#31-special-handling-of-the-data-attribute) data: +Example event with JSON data for the "data" member, either derived from a `Map` +or [JSON data](#31-special-handling-of-the-data-attribute) data: -``` JSON +```JSON { "specversion" : "0.2", "type" : "com.example.someevent", @@ -233,22 +230,22 @@ a `Map` or [JSON data](#31-special-handling-of-the-data-attribute) data: ## 4. JSON Batch Format -In the *JSON Batch Format* several CloudEvents are batched into a single JSON -document. The document is a JSON array filled with CloudEvents in the -[JSON Event format][JSON-format]. +In the _JSON Batch Format_ several CloudEvents are batched into a single JSON +document. The document is a JSON array filled with CloudEvents in the [JSON +Event format][json-format]. -Although the *JSON Batch Format* builds ontop of the *JSON Format*, it is -considered as a separate format: a valid implementation of the *JSON Format* -doesn't need to support it. The *JSON Batch Format* MUST NOT be used when only -support for the *JSON Format* is indicated. +Although the _JSON Batch Format_ builds ontop of the _JSON Format_, it is +considered as a separate format: a valid implementation of the _JSON Format_ +doesn't need to support it. The _JSON Batch Format_ MUST NOT be used when only +support for the _JSON Format_ is indicated. ### 4.1. Mapping CloudEvents This section defines how a batch of CloudEvents is mapped to JSON. -The outermost JSON element is a [JSON Array][JSON-array], which contains -as elements CloudEvents rendered in accordance with the -[JSON event format][JSON-format] specification. +The outermost JSON element is a [JSON Array][json-array], which contains as +elements CloudEvents rendered in accordance with the [JSON event +format][json-format] specification. ### 4.2. Envelope @@ -260,7 +257,7 @@ A JSON Batch of CloudEvents MUST use the media type An example containing two CloudEvents: The first with `Binary`-valued data, the second with JSON data. -``` JSON +```JSON [ { "specversion" : "0.2", @@ -303,31 +300,33 @@ An example of an empty batch of CloudEvents (typically used in a response): ## 5. References -* [RFC2046][RFC2046] Multipurpose Internet Mail Extensions (MIME) Part Two: +- [RFC2046][rfc2046] Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types -* [RFC2119][RFC2119] Key words for use in RFCs to Indicate Requirement Levels -* [RFC4627][RFC4627] The application/json Media Type for JavaScript Object +- [RFC2119][rfc2119] Key words for use in RFCs to Indicate Requirement Levels +- [RFC4627][rfc4627] The application/json Media Type for JavaScript Object Notation (JSON) -* [RFC4648][RFC4648] The Base16, Base32, and Base64 Data Encodings -* [RFC6839][RFC6839] Additional Media Type Structured Syntax Suffixes -* [RFC8259][RFC8259] The JavaScript Object Notation (JSON) Data Interchange Format +- [RFC4648][rfc4648] The Base16, Base32, and Base64 Data Encodings +- [RFC6839][rfc6839] Additional Media Type Structured Syntax Suffixes +- [RFC8259][rfc8259] The JavaScript Object Notation (JSON) Data Interchange + Format [base64]: https://tools.ietf.org/html/rfc4648#section-4 -[CE]: ./spec.md -[Content-Type]: https://tools.ietf.org/html/rfc7231#section-3.1.1.5 -[JSON-format]: ./json-format.md -[JSON-geoseq]: https://www.iana.org/assignments/media-types/application/geo+json-seq -[JSON-Object]: https://tools.ietf.org/html/rfc7159#section-4 -[JSON-seq]: https://www.iana.org/assignments/media-types/application/json-seq -[JSON-Number]: https://tools.ietf.org/html/rfc7159#section-6 -[JSON-String]: https://tools.ietf.org/html/rfc7159#section-7 -[JSON-Value]: https://tools.ietf.org/html/rfc7159#section-3 -[JSON-Array]: https://tools.ietf.org/html/rfc7159#section-5 -[RFC2046]: https://tools.ietf.org/html/rfc2046 -[RFC2119]: https://tools.ietf.org/html/rfc2119 -[RFC3986]: https://tools.ietf.org/html/rfc3986 -[RFC4627]: https://tools.ietf.org/html/rfc4627 -[RFC4648]: https://tools.ietf.org/html/rfc4648 -[RFC6839]: https://tools.ietf.org/html/rfc6839#section-3.1 -[RFC8259]: https://tools.ietf.org/html/rfc8259 -[RFC3339]: https://www.ietf.org/rfc/rfc3339.txt +[ce]: ./spec.md +[content-type]: https://tools.ietf.org/html/rfc7231#section-3.1.1.5 +[json-format]: ./json-format.md +[json-geoseq]: + https://www.iana.org/assignments/media-types/application/geo+json-seq +[json-object]: https://tools.ietf.org/html/rfc7159#section-4 +[json-seq]: https://www.iana.org/assignments/media-types/application/json-seq +[json-number]: https://tools.ietf.org/html/rfc7159#section-6 +[json-string]: https://tools.ietf.org/html/rfc7159#section-7 +[json-value]: https://tools.ietf.org/html/rfc7159#section-3 +[json-array]: https://tools.ietf.org/html/rfc7159#section-5 +[rfc2046]: https://tools.ietf.org/html/rfc2046 +[rfc2119]: https://tools.ietf.org/html/rfc2119 +[rfc3986]: https://tools.ietf.org/html/rfc3986 +[rfc4627]: https://tools.ietf.org/html/rfc4627 +[rfc4648]: https://tools.ietf.org/html/rfc4648 +[rfc6839]: https://tools.ietf.org/html/rfc6839#section-3.1 +[rfc8259]: https://tools.ietf.org/html/rfc8259 +[rfc3339]: https://www.ietf.org/rfc/rfc3339.txt diff --git a/mqtt-transport-binding.md b/mqtt-transport-binding.md index b9c6bae59..570a30987 100644 --- a/mqtt-transport-binding.md +++ b/mqtt-transport-binding.md @@ -2,9 +2,9 @@ ## Abstract -The MQTT Transport Binding for CloudEvents defines how events are mapped to -MQTT 3.1.1 ([OASIS][OASIS-MQTT-3.1.1]; ISO/IEC 20922:2016) and MQTT 5.0 -([OASIS][OASIS-MQTT-5]) messages. +The MQTT Transport Binding for CloudEvents defines how events are mapped to MQTT +3.1.1 ([OASIS][oasis-mqtt-3.1.1]; ISO/IEC 20922:2016) and MQTT 5.0 +([OASIS][oasis-mqtt-5]) messages. ## Status of this document @@ -13,61 +13,67 @@ This document is a working draft. ## Table of Contents 1. [Introduction](#1-introduction) + - 1.1. [Conformance](#11-conformance) - 1.2. [Relation to MQTT](#12-relation-to-mqtt) - 1.3. [Content Modes](#13-content-modes) - 1.4. [Event Formats](#14-event-formats) - 1.5. [Security](#15-security) + 2. [Use of CloudEvents Attributes](#2-use-of-cloudevents-attributes) + - 2.1. [datacontenttype Attribute](#21-datacontenttype-attribute) - 2.2. [data Attribute](#22-data-attribute) + 3. [MQTT PUBLISH Message Mapping](#3-mqtt-publish-message-mapping) + - 3.2. [Binary Content Mode](#31-binary-content-mode) - 3.1. [Structured Content Mode](#32-structured-content-mode) + 4. [References](#4-references) ## 1. Introduction -[CloudEvents][CE] is a standardized and transport-neutral definition of the -structure and metadata description of events. This specification defines how -the elements defined in the CloudEvents specification are to be used in -MQTT PUBLISH ([3.1.1][3-publish], [5.0][5-publish]) messages. +[CloudEvents][ce] is a standardized and transport-neutral definition of the +structure and metadata description of events. This specification defines how the +elements defined in the CloudEvents specification are to be used in MQTT PUBLISH +([3.1.1][3-publish], [5.0][5-publish]) messages. ### 1.1. Conformance The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC2119][RFC2119]. +interpreted as described in [RFC2119][rfc2119]. ### 1.2. Relation to MQTT -This specification does not prescribe rules constraining transfer or -settlement of event messages with MQTT; it solely defines how CloudEvents -are expressed as MQTT PUBLISH messages ([3.1.1][3-publish], [5.0][5-publish]). +This specification does not prescribe rules constraining transfer or settlement +of event messages with MQTT; it solely defines how CloudEvents are expressed as +MQTT PUBLISH messages ([3.1.1][3-publish], [5.0][5-publish]). ### 1.3. Content Modes The specification defines two content modes for transferring events: -*structured* and *binary*. +_structured_ and _binary_. -The *binary* mode *only* applies to MQTT 5.0, because of MQTT 3.1.1's lack of +The _binary_ mode _only_ applies to MQTT 5.0, because of MQTT 3.1.1's lack of support for custom metadata. -In the *structured* content mode, event metadata attributes and event data are -placed into the MQTT PUBLISH message payload section -using an [event format](#14-event-formats). +In the _structured_ content mode, event metadata attributes and event data are +placed into the MQTT PUBLISH message payload section using an +[event format](#14-event-formats). -In the *binary* content mode, the value of the event `data` attribute is placed -into the MQTT PUBLISH message's payload section as-is, with -the `datacontenttype` attribute value declaring its media type; all other event -attributes are mapped to the MQTT PUBLISH message's -[properties section][5-publish-properties]. +In the _binary_ content mode, the value of the event `data` attribute is placed +into the MQTT PUBLISH message's payload section as-is, with the +`datacontenttype` attribute value declaring its media type; all other event +attributes are mapped to the MQTT PUBLISH message's [properties +section][5-publish-properties]. ### 1.4. Event Formats -Event formats, used with the *structured* content mode, define how an event is -expressed in a particular data format. All implementations of this -specification MUST support the [JSON event format][JSON-format]. +Event formats, used with the _structured_ content mode, define how an event is +expressed in a particular data format. All implementations of this specification +MUST support the [JSON event format][json-format]. MQTT 5.0 implementations MAY support any additional, including proprietary, formats. @@ -79,21 +85,21 @@ mandate specific existing features to be used. ## 2. Use of CloudEvents Attributes -This specification does not further define any of the [CloudEvents][CE] event +This specification does not further define any of the [CloudEvents][ce] event attributes. Two of the event attributes, `datacontenttype` and `data` are handled specially and mapped onto MQTT constructs, all other attributes are transferred as metadata without further interpretation. -This mapping is intentionally robust against changes, including the addition -and removal of event attributes, and also accommodates vendor extensions to the +This mapping is intentionally robust against changes, including the addition and +removal of event attributes, and also accommodates vendor extensions to the event metadata. Any mention of event attributes other than `datacontenttype` and `data` is exemplary. ### 2.1. datacontenttype Attribute -The `datacontenttype` attribute is assumed to contain a [RFC2046][RFC2046] +The `datacontenttype` attribute is assumed to contain a [RFC2046][rfc2046] compliant media-type expression. ### 2.2. data Attribute @@ -108,8 +114,7 @@ available as a sequence of bytes. For instance, if the declared `datacontenttype` is `application/json;charset=utf-8`, the expectation is that the `data` attribute -value is made available as [UTF-8][RFC3629] encoded JSON text for use in -MQTT. +value is made available as [UTF-8][rfc3629] encoded JSON text for use in MQTT. ## 3. MQTT PUBLISH Message Mapping @@ -120,28 +125,27 @@ content mode might be defined by an application, but are not defined here. The receiver of the event can distinguish between the two content modes by inspecting the`Content Type` property of the MQTT PUBLISH message. If the value of the `Content Type` property is prefixed with the CloudEvents media type -`application/cloudevents`, indicating the use of a known [event -format](#14-event-formats), the receiver uses *structured* mode, otherwise it -defaults to *binary* mode. +`application/cloudevents`, indicating the use of a known +[event format](#14-event-formats), the receiver uses _structured_ mode, +otherwise it defaults to _binary_ mode. If a receiver finds a CloudEvents media type as per the above rule, but with an -event format that it cannot handle, for instance -`application/cloudevents+avro`, it MAY still treat the event as binary and -forward it to another party as-is. +event format that it cannot handle, for instance `application/cloudevents+avro`, +it MAY still treat the event as binary and forward it to another party as-is. -With MQTT 3.1.1, the content mode is always *structured* and the message -payload MUST use the [JSON event format][JSON-format]. +With MQTT 3.1.1, the content mode is always _structured_ and the message payload +MUST use the [JSON event format][json-format]. ### 3.1. Binary Content Mode -The *binary* content mode accommodates any shape of event data, and allows for +The _binary_ content mode accommodates any shape of event data, and allows for efficient transfer and without transcoding effort. #### 3.1.1. MQTT PUBLISH Content Type -For the *binary* mode, the MQTT PUBLISH message's [`Content -Type`][5-content-type] property MUST be mapped directly to the CloudEvents -`datacontenttype` attribute. +For the _binary_ mode, the MQTT PUBLISH message's +[`Content Type`][5-content-type] property MUST be mapped directly to the +CloudEvents `datacontenttype` attribute. #### 3.1.2. Event Data Encoding @@ -150,19 +154,19 @@ payload of the MQTT PUBLISH message. #### 3.1.3. Metadata Headers -All [CloudEvents][CE] attributes with exception of `datacontenttype` and `data` +All [CloudEvents][ce] attributes with exception of `datacontenttype` and `data` MUST be individually mapped to and from the User Property fields in the MQTT PUBLISH message, with exceptions noted below. -CloudEvents extensions that define their own attributes MAY define a -diverging mapping to MQTT user properties or features for those attributes, -especially if specific attributes need to align with MQTT features, or with -other specifications that have explicit MQTT header bindings. +CloudEvents extensions that define their own attributes MAY define a diverging +mapping to MQTT user properties or features for those attributes, especially if +specific attributes need to align with MQTT features, or with other +specifications that have explicit MQTT header bindings. -An extension specification that defines a diverging mapping rule for MQTT, -and any revision of such a specification, MUST also define explicit mapping -rules for all other transport bindings that are part of the CloudEvents core at -the time of the submission or revision. +An extension specification that defines a diverging mapping rule for MQTT, and +any revision of such a specification, MUST also define explicit mapping rules +for all other transport bindings that are part of the CloudEvents core at the +time of the submission or revision. ##### 3.1.3.1 User Property Names @@ -173,21 +177,20 @@ in the MQTT PUBLISH message. The value for each MQTT PUBLISH User Property MUST be constructed from the respective CloudEvents attribute's JSON type representation, compliant with the -[JSON event format][JSON-format] specification. +[JSON event format][json-format] specification. #### 3.1.4 Examples -This example shows the *binary* mode mapping of an event into the -MQTT 5.0 PUBLISH message. The CloudEvents `datacontenttype` attribute -is mapped to the MQTT PUBLISH `Content Type` field; all other -CloudEvents attributes are mapped to MQTT PUBLISH User Property -fields. The `Topic name` is chosen by the MQTT client and not derived -from the CloudEvents event data. +This example shows the _binary_ mode mapping of an event into the MQTT 5.0 +PUBLISH message. The CloudEvents `datacontenttype` attribute is mapped to the +MQTT PUBLISH `Content Type` field; all other CloudEvents attributes are mapped +to MQTT PUBLISH User Property fields. The `Topic name` is chosen by the MQTT +client and not derived from the CloudEvents event data. -Mind that `Content Type` here does refer to the event `data` -content carried in the payload. +Mind that `Content Type` here does refer to the event `data` content carried in +the payload. -``` text +```text ------------------ PUBLISH ------------------- Topic Name: mytopic @@ -213,21 +216,21 @@ source: "/mycontext/subcontext" ### 3.2. Structured Content Mode -The *structured* content mode keeps event metadata and data together in the +The _structured_ content mode keeps event metadata and data together in the payload, allowing simple forwarding of the same event across multiple routing -hops, and across multiple transports. This is the only supported mode for -MQTT 3.1.1 +hops, and across multiple transports. This is the only supported mode for MQTT +3.1.1 #### 3.2.1. MQTT Content Type For MQTT 5.0, the [MQTT PUBLISH message's `Content Type`][5-content-type] -property MUST be set to the media type of an [event format](#14-event-formats). For -MQTT 3.1.1, the media type of the [JSON event format][JSON-format] is always +property MUST be set to the media type of an [event format](#14-event-formats). +For MQTT 3.1.1, the media type of the [JSON event format][json-format] is always implied: -Example for the [JSON format][JSON-format]: +Example for the [JSON format][json-format]: -``` text +```text content-type: application/cloudevents+json; charset=utf-8 ``` @@ -248,7 +251,7 @@ as defined for the [binary mode](#313-metadata-headers). The first example shows a JSON event format encoded event with MQTT 5.0 -``` text +```text ------------------ PUBLISH ------------------- Topic Name: mytopic @@ -270,11 +273,11 @@ Content Type: application/cloudevents+json; charset=utf-8 ----------------------------------------------- ``` -For MQTT 3.1.1, the example looks nearly identical, but `Content Type` -is absent because not yet supported in that version of the MQTT specification -and therefore `application/cloudevents+json` is implied: +For MQTT 3.1.1, the example looks nearly identical, but `Content Type` is absent +because not yet supported in that version of the MQTT specification and +therefore `application/cloudevents+json` is implied: -``` text +```text ------------------ PUBLISH ------------------- Topic Name: mytopic @@ -297,23 +300,25 @@ Topic Name: mytopic ## 4. References -- [MQTT 3.1.1][OASIS-MQTT-3.1.1] MQTT Version 3.1.1 -- [MQTT 5.0][OASIS-MQTT-5] MQTT Version 5.0 -- [RFC2046][RFC2046] Multipurpose Internet Mail Extensions (MIME) Part Two: +- [MQTT 3.1.1][oasis-mqtt-3.1.1] MQTT Version 3.1.1 +- [MQTT 5.0][oasis-mqtt-5] MQTT Version 5.0 +- [RFC2046][rfc2046] Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types -- [RFC2119][RFC2119] Key words for use in RFCs to Indicate Requirement Levels -- [RFC3629][RFC3629] UTF-8, a transformation format of ISO 10646 -- [RFC4627][RFC4627] The application/json Media Type for JavaScript Object +- [RFC2119][rfc2119] Key words for use in RFCs to Indicate Requirement Levels +- [RFC3629][rfc3629] UTF-8, a transformation format of ISO 10646 +- [RFC4627][rfc4627] The application/json Media Type for JavaScript Object Notation (JSON) -- [RFC7159][RFC7159] The JavaScript Object Notation (JSON) Data Interchange Format - -[CE]: ./spec.md -[JSON-format]: ./json-format.md -[OASIS-MQTT-3.1.1]: http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html -[OASIS-MQTT-5]: http://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html -[5-content-type]: http://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html#_Toc502667341 -[JSON-Value]: https://tools.ietf.org/html/rfc7159#section-3 -[RFC2046]: https://tools.ietf.org/html/rfc2046 -[RFC2119]: https://tools.ietf.org/html/rfc2119 -[RFC3629]: https://tools.ietf.org/html/rfc3629 -[RFC4627]: https://tools.ietf.org/html/rfc4627 +- [RFC7159][rfc7159] The JavaScript Object Notation (JSON) Data Interchange + Format + +[ce]: ./spec.md +[json-format]: ./json-format.md +[oasis-mqtt-3.1.1]: http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html +[oasis-mqtt-5]: http://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html +[5-content-type]: + http://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html#_Toc502667341 +[json-value]: https://tools.ietf.org/html/rfc7159#section-3 +[rfc2046]: https://tools.ietf.org/html/rfc2046 +[rfc2119]: https://tools.ietf.org/html/rfc2119 +[rfc3629]: https://tools.ietf.org/html/rfc3629 +[rfc4627]: https://tools.ietf.org/html/rfc4627 diff --git a/nats-transport-binding.md b/nats-transport-binding.md index 2329f8004..387537275 100644 --- a/nats-transport-binding.md +++ b/nats-transport-binding.md @@ -2,7 +2,8 @@ ## Abstract -The [NATS][NATS] Transport Binding for CloudEvents defines how events are mapped to [NATS messages][NATS-MSG-PROTO]. +The [NATS][nats] Transport Binding for CloudEvents defines how events are mapped +to [NATS messages][nats-msg-proto]. ## Status of this document @@ -11,57 +12,62 @@ This document is a working draft. ## Table of Contents 1. [Introduction](#1-introduction) + - 1.1. [Conformance](#11-conformance) - 1.2. [Relation to NATS](#12-relation-to-nats) - 1.3. [Content Modes](#13-content-modes) - 1.4. [Event Formats](#14-event-formats) - 1.5. [Security](#15-security) + 2. [Use of CloudEvents Attributes](#2-use-of-cloudevents-attributes) + - 2.1. [datacontenttype Attribute](#21-datacontenttype-attribute) - 2.2. [data Attribute](#22-data-attribute) + 3. [NATS Message Mapping](#3-nats-message-mapping) + - 3.1. [Event Data Encoding](#31-event-data-encoding) - 3.2. [Example](#32-example) + 4. [References](#4-references) ## 1. Introduction -[CloudEvents][CE] is a standardized and transport-neutral definition of the -structure and metadata description of events. This specification defines how -the elements defined in the CloudEvents specification are to be used in the -NATS protocol as client [produced][NATS-PUB-PROTO] and [consumed][NATS-MSG-PROTO] +[CloudEvents][ce] is a standardized and transport-neutral definition of the +structure and metadata description of events. This specification defines how the +elements defined in the CloudEvents specification are to be used in the NATS +protocol as client [produced][nats-pub-proto] and [consumed][nats-msg-proto] messages. ### 1.1. Conformance The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC2119][RFC2119]. +interpreted as described in [RFC2119][rfc2119]. ### 1.2. Relation to NATS This specification does not prescribe rules constraining transfer or settlement -of event messages with NATS; it solely defines how CloudEvents are expressed -in the NATS protocol as client messages that are [produced][NATS-PUB-PROTO] -and [consumed][NATS-MSG-PROTO]. +of event messages with NATS; it solely defines how CloudEvents are expressed in +the NATS protocol as client messages that are [produced][nats-pub-proto] and +[consumed][nats-msg-proto]. ### 1.3. Content Modes The specification defines two content modes for transferring events: -*structured* and *binary*. +_structured_ and _binary_. -NATS will only support *structured* data mode at this time. Today, the -NATS protocol does not support custom message headers, necessary for -*binary* mode. +NATS will only support _structured_ data mode at this time. Today, the NATS +protocol does not support custom message headers, necessary for _binary_ mode. Event metadata attributes and event data are placed into the NATS message payload using an [event format](#14-event-formats). ### 1.4. Event Formats -Event formats, used with the *stuctured* content mode, define how an event is -expressed in a particular data format. All implementations of this -specification MUST support the [JSON event format][JSON-format]. +Event formats, used with the _stuctured_ content mode, define how an event is +expressed in a particular data format. All implementations of this specification +MUST support the [JSON event format][json-format]. ### 1.5. Security @@ -70,13 +76,13 @@ mandate specific existing features to be used. ## 2. Use of CloudEvents Attributes -This specification does not further define any of the [CloudEvents][CE] event +This specification does not further define any of the [CloudEvents][ce] event attributes. ### 2.1. datacontenttype Attribute The `datacontenttype` attribute is assumed to contain a media-type expression -compliant with [RFC2046][RFC2046]. +compliant with [RFC2046][rfc2046]. ### 2.2. data Attribute @@ -89,17 +95,17 @@ specification, core NATS provides data available as a sequence of bytes. For instance, if the declared `datacontenttype` is `application/json;charset=utf-8`, the expectation is that the `data` attribute -value is made available as [UTF-8][RFC3629] encoded JSON text. +value is made available as [UTF-8][rfc3629] encoded JSON text. ## 3. NATS Message Mapping -With NATS, the content mode is always *structured* and the NATS message -payload MUST be the [JSON event format][JSON-format] serialized as -specified by the [UTF-8][RFC3629] encoded JSON text for use in NATS. +With NATS, the content mode is always _structured_ and the NATS message payload +MUST be the [JSON event format][json-format] serialized as specified by the +[UTF-8][rfc3629] encoded JSON text for use in NATS. -The *structured* content mode keeps event metadata and data together, -allowing simple forwarding of the same event across multiple routing -hops, and across multiple transports. +The _structured_ content mode keeps event metadata and data together, allowing +simple forwarding of the same event across multiple routing hops, and across +multiple transports. ### 3.1 Event Data Encoding @@ -111,10 +117,10 @@ format specification and the resulting data becomes the payload. ### 3.2 Example -This example shows a JSON event format encoded event in client -messages that are [produced][NATS-PUB-PROTO] and [consumed][NATS-MSG-PROTO]. +This example shows a JSON event format encoded event in client messages that are +[produced][nats-pub-proto] and [consumed][nats-msg-proto]. -``` text +```text ------------------ Message ------------------- Subject: mySubject @@ -137,22 +143,25 @@ Subject: mySubject ## 4. References -- [NATS][NATS] The NATS Messaging System -- [NATS-PUB-PROTO][NATS-PUB-PROTO] The NATS protocol for messages published by a client -- [NATS-MSG-PROTO][NATS-MSG-PROTO] The NATS protocol for messages received by a client -- [RFC2046][RFC2046] Multipurpose Internet Mail Extensions (MIME) Part Two: +- [NATS][nats] The NATS Messaging System +- [NATS-PUB-PROTO][nats-pub-proto] The NATS protocol for messages published by a + client +- [NATS-MSG-PROTO][nats-msg-proto] The NATS protocol for messages received by a + client +- [RFC2046][rfc2046] Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types -- [RFC2119][RFC2119] Key words for use in RFCs to Indicate Requirement Levels -- [RFC3629][RFC3629] UTF-8, a transformation format of ISO 10646 -- [RFC7159][RFC7159] The JavaScript Object Notation (JSON) Data Interchange Format - -[CE]: ./spec.md -[JSON-format]: ./json-format.md -[NATS]: https://nats.io -[NATS-PUB-PROTO]: https://nats.io/documentation/internals/nats-protocol/#PUB -[NATS-MSG-PROTO]: https://nats.io/documentation/internals/nats-protocol/#MSG -[JSON-Value]: https://tools.ietf.org/html/rfc7159#section-3 -[RFC2046]: https://tools.ietf.org/html/rfc2046 -[RFC2119]: https://tools.ietf.org/html/rfc2119 -[RFC3629]: https://tools.ietf.org/html/rfc3629 -[RFC7159]: https://tools.ietf.org/html/rfc7159 +- [RFC2119][rfc2119] Key words for use in RFCs to Indicate Requirement Levels +- [RFC3629][rfc3629] UTF-8, a transformation format of ISO 10646 +- [RFC7159][rfc7159] The JavaScript Object Notation (JSON) Data Interchange + Format + +[ce]: ./spec.md +[json-format]: ./json-format.md +[nats]: https://nats.io +[nats-pub-proto]: https://nats.io/documentation/internals/nats-protocol/#PUB +[nats-msg-proto]: https://nats.io/documentation/internals/nats-protocol/#MSG +[json-value]: https://tools.ietf.org/html/rfc7159#section-3 +[rfc2046]: https://tools.ietf.org/html/rfc2046 +[rfc2119]: https://tools.ietf.org/html/rfc2119 +[rfc3629]: https://tools.ietf.org/html/rfc3629 +[rfc7159]: https://tools.ietf.org/html/rfc7159 diff --git a/primer.md b/primer.md index 96bc8ed78..cc20cf1d7 100644 --- a/primer.md +++ b/primer.md @@ -3,11 +3,10 @@ ## Abstract This non-normative document provides an overview of the CloudEvents -specification. It is meant to compliment the CloudEvent specification -to provide additional background and insight into the history and -design decisions made during the development of the specification. This -allows the specification itself to focus on the normative technical -details. +specification. It is meant to compliment the CloudEvent specification to provide +additional background and insight into the history and design decisions made +during the development of the specification. This allows the specification +itself to focus on the normative technical details. ## Status of this document @@ -29,15 +28,14 @@ This document is a working draft. ## History -The [CNCF Serverless Working group](https://github.com/cncf/wg-serverless) -was originally created by the CNCF's +The [CNCF Serverless Working group](https://github.com/cncf/wg-serverless) was +originally created by the CNCF's [Technical Oversight Committee](https://github.com/cncf/toc) to investigate -Serverless Technology and to recommend some possible next steps for some -CNCF related activities in this space. One of the recommendations was to -investigate the creation of a common event format to aid in the -portability of functions between Cloud providers and the interoperability of -processing of event streams. As a result, the CloudEvents specification -was created. +Serverless Technology and to recommend some possible next steps for some CNCF +related activities in this space. One of the recommendations was to investigate +the creation of a common event format to aid in the portability of functions +between Cloud providers and the interoperability of processing of event streams. +As a result, the CloudEvents specification was created. While initially the work on CloudEvents was done as part of the Serverless Working group, once the specification reached its v0.1 milestone, the TOC @@ -46,10 +44,10 @@ approved the CloudEvents work as a new stand-alone CNCF sandbox project. ## CloudEvents Concepts An [event](spec.md#event) includes context and data about an -[occurrence](spec.md#occurrence). Each *occurrence* is uniquely -identified by the data of the *event*. +[occurrence](spec.md#occurrence). Each _occurrence_ is uniquely identified by +the data of the _event_. -*Events* represent facts and therefore do not include a destination, whereas +_Events_ represent facts and therefore do not include a destination, whereas messages convey intent, transporting data from a source to a given destination. ### Eventing @@ -71,27 +69,27 @@ The source generates a message where the event is encapsulated in a protocol. The event arrives to a destination, triggering an action which is provided with the event data. -A *source* is a specific instance of a source-type which -allows for staging and test instances. Open source software of a specific -*source-type* may be deployed by multiple companies or providers. +A _source_ is a specific instance of a source-type which allows for staging and +test instances. Open source software of a specific _source-type_ may be deployed +by multiple companies or providers. Events can be delivered through various industry standard protocols (e.g. HTTP, AMQP, MQTT, SMTP), open-source protocols (e.g. Kafka, NATS), or platform/vendor specific protocols (AWS Kinesis, Azure Event Grid). -An action processes an event defining a behavior or effect which was -triggered by a specific *occurrence* from a specific *source*. While outside -of the scope of the specification, the purpose of generating an *event* is -typcially to allow other systems to easily react to changes in a source that -they do not control. The *source* and action are typically built by different -developers. Often the *source* is a managed service and the *action* is custom -code in a serverless Function (such as AWS Lambda or Google Cloud Functions). +An action processes an event defining a behavior or effect which was triggered +by a specific _occurrence_ from a specific _source_. While outside of the scope +of the specification, the purpose of generating an _event_ is typcially to allow +other systems to easily react to changes in a source that they do not control. +The _source_ and action are typically built by different developers. Often the +_source_ is a managed service and the _action_ is custom code in a serverless +Function (such as AWS Lambda or Google Cloud Functions). ## Design Goals CloudEvents are typically used in a distributed system to allow for services to -be loosely coupled during development, deployed independently, and later -can be connected to create new applications. +be loosely coupled during development, deployed independently, and later can be +connected to create new applications. The goal of the CloudEvents specification is to define interoperability of event systems that allow services to produce or consume events, where the producer and @@ -99,155 +97,151 @@ consumer can be developed and deployed independently. A producer can generate events before a consumer is listening, and a consumer can express an interest in an event or class of events that is not yet being produced. Note that the specifications produced by this effort are focused on interoperability of the -event format and how it appears while being sent on various transports, -such as HTTP. The specifications will not focus on the processing model of -either the event producer or event consumer. +event format and how it appears while being sent on various transports, such as +HTTP. The specifications will not focus on the processing model of either the +event producer or event consumer. CloudEvents, at its core, defines a set of metadata, called attributes, about the event being transferred between systems, and how those pieces of metadata -should appear in that message. This metadata is meant to be the minimal -set of information needed to route the request to the proper component -and to facilitate proper processing of the event by that component. -So, while this might mean that some of the application -data of the event itself might be duplicated as part of the CloudEvent's set -of attributes, this is to be done solely for the purpose of proper delivery, -and processing, of the message. Data that is not intended for that purpose -should instead be placed within the event (the `data` attribute) itself. - -Along with the definition of these attributes, there will also be -specifications of how to serialize the event in different formats (e.g. JSON) -and transports (e.g. HTTP, AMQP, Kafka). +should appear in that message. This metadata is meant to be the minimal set of +information needed to route the request to the proper component and to +facilitate proper processing of the event by that component. So, while this +might mean that some of the application data of the event itself might be +duplicated as part of the CloudEvent's set of attributes, this is to be done +solely for the purpose of proper delivery, and processing, of the message. Data +that is not intended for that purpose should instead be placed within the event +(the `data` attribute) itself. + +Along with the definition of these attributes, there will also be specifications +of how to serialize the event in different formats (e.g. JSON) and transports +(e.g. HTTP, AMQP, Kafka). Batching of multiple events into a single API call is natively supported by some transports. To aid interoperability, it is left up to the transports if and how -batching is implemented. Details may be found in the transport binding or in -the transport specification. +batching is implemented. Details may be found in the transport binding or in the +transport specification. ### Non-Goals + The following will not be part of the specification: -* Function build and invocation process -* Language-specific runtime APIs -* Selecting a single identity/access control system + +- Function build and invocation process +- Language-specific runtime APIs +- Selecting a single identity/access control system ## Versioning of Attributes For certain CloudEvents attributes, the entity or data model referenced by its -value might change over time. For example, `schemaurl` might be a reference -one particular version of a schema document. Often these attribute values -will then distinguish each variant by including some version-specific -string as part of its value. For example, a version number (`v1`, `v2`), or a -date (`2018-01-01`) might be used. - -The CloudEvents specification does not mandate any particular pattern to -be used, or even the use of version strings at all. This decision is up to -each event producer. However, when a version-specific string is included, -care should be taken whenever its value changes as event consumers might -be reliant on the existing value and thus a change could be interpretted -as a "breaking change". Some form of communication between producers and -consumers should be established to ensure the event consumers know what -possible values might be used. In general, this is true for all CloudEvents -attributes as well. +value might change over time. For example, `schemaurl` might be a reference one +particular version of a schema document. Often these attribute values will then +distinguish each variant by including some version-specific string as part of +its value. For example, a version number (`v1`, `v2`), or a date (`2018-01-01`) +might be used. + +The CloudEvents specification does not mandate any particular pattern to be +used, or even the use of version strings at all. This decision is up to each +event producer. However, when a version-specific string is included, care should +be taken whenever its value changes as event consumers might be reliant on the +existing value and thus a change could be interpretted as a "breaking change". +Some form of communication between producers and consumers should be established +to ensure the event consumers know what possible values might be used. In +general, this is true for all CloudEvents attributes as well. ## CloudEvent Attribute Extensions In order to achieve the stated goals, the specification authors will attempt to -constrain the number of metadata attributes they define in CloudEvents. To -that end, attributes defined by this project will fall into three -categories: +constrain the number of metadata attributes they define in CloudEvents. To that +end, attributes defined by this project will fall into three categories: + - required - optional - extensions -As the category names imply, "required" attributes will be the ones that -the group considers vital to all events in all use cases, while -"optional" ones will be used in a majority of the cases. Both of the attributes -in these cases will be defined within the specfication itself. - -When the group determines that 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 they will be placed -into the "extensions" category and put into -[documented extensions](documented-extensions.md). -The specification defines how these extension attributes will -appear within a CloudEvent. - -In determining which category a proposed attribute belongs, or even if it -will be included at all, the group uses use-cases and -user-stories to explain the rationale and need for them. This supporting -information will be added to the [Prior Art](#prior-art) section of this -document. - -Extension attributes to the CloudEvent specification are meant to -be additional metadata that needs to be included to help ensure proper -routing and processing of the CloudEvent. Additional metadata for other -purposes, that is related to the event itself and not needed in the -transportation or processing of the CloudEvent, should instead be placed -within the proper extensibility points of the event (the `data` attribute) -itself. +As the category names imply, "required" attributes will be the ones that the +group considers vital to all events in all use cases, while "optional" ones will +be used in a majority of the cases. Both of the attributes in these cases will +be defined within the specfication itself. + +When the group determines that 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 they will be placed into the +"extensions" category and put into +[documented extensions](documented-extensions.md). The specification defines how +these extension attributes will appear within a CloudEvent. + +In determining which category a proposed attribute belongs, or even if it will +be included at all, the group uses use-cases and user-stories to explain the +rationale and need for them. This supporting information will be added to the +[Prior Art](#prior-art) section of this document. + +Extension attributes to the CloudEvent specification are meant to be additional +metadata that needs to be included to help ensure proper routing and processing +of the CloudEvent. Additional metadata for other purposes, that is related to +the event itself and not needed in the transportation or processing of the +CloudEvent, should instead be placed within the proper extensibility points of +the event (the `data` attribute) itself. Extension attributes should be kept minimal to ensure the CloudEvent can be -properly serialized and transported. For example, the -Event producers should consider the technical limitations that might be -encountered when adding extensions to a CloudEvent. For example, the +properly serialized and transported. For example, the Event producers should +consider the technical limitations that might be encountered when adding +extensions to a CloudEvent. For example, the [HTTP Binary Mode](http-transport-binding.md#31-binary-content-mode) uses HTTP headers to transport metadata; most HTTP servers will reject requests with excessive HTTP header data, with limits as low as 8kb. Therefore, the aggregate size and number of extension attributes should be kept minimal. The specification places no restrictions on the type of the extension -attributes. Meaning, they may be simple types (e.g. strings, integers), -complex (e.g. structured) or undefined collection of attributes. +attributes. Meaning, they may be simple types (e.g. strings, integers), complex +(e.g. structured) or undefined collection of attributes. -If an extension becomes popular then the specification authors might -consider moving it into the specification as a core attribute. This means -that the extension mechanism/process can be used as a way to vet new -attributes prior to formally adding them to the specification. +If an extension becomes popular then the specification authors might consider +moving it into the specification as a core attribute. This means that the +extension mechanism/process can be used as a way to vet new attributes prior to +formally adding them to the specification. ### JSON Extensions As mentioned in the [Attributes](json-format.md#2-attributes) section of the -[JSON Event Format for CloudEvents](json-format.md) specificatinon, -CloudEvent extension attributes are serialized as siblings to the specification -defined attributes - meaning, at the top-level of the JSON object. The -authors of the specification spent a long time considering all options -and decided that this was the best choice. Some of the rationale follows. - -Since the specifications follow [semver](https://semver.org/), this -means that new properties can be defined by future versions of the -core specification without requiring a major version number change - as -long as these properties are optional. In those cases, consider what an -existing consumer would do with a new (unknown) top-level property. While -it would be free to ignore it, since it is optional, in most cases it is -believed that these properties would still want to be exposed to the -application receiving those events. This would allow those applications to -support these properties even if the infrastructure doesn't. This means -that unknown top-level properties (regardless of who defined them - future -versions of the spec or the event producer) are probably not going to be -ignored. So, while some other specifications define a specific property +[JSON Event Format for CloudEvents](json-format.md) specificatinon, CloudEvent +extension attributes are serialized as siblings to the specification defined +attributes - meaning, at the top-level of the JSON object. The authors of the +specification spent a long time considering all options and decided that this +was the best choice. Some of the rationale follows. + +Since the specifications follow [semver](https://semver.org/), this means that +new properties can be defined by future versions of the core specification +without requiring a major version number change - as long as these properties +are optional. In those cases, consider what an existing consumer would do with a +new (unknown) top-level property. While it would be free to ignore it, since it +is optional, in most cases it is believed that these properties would still want +to be exposed to the application receiving those events. This would allow those +applications to support these properties even if the infrastructure doesn't. +This means that unknown top-level properties (regardless of who defined them - +future versions of the spec or the event producer) are probably not going to be +ignored. So, while some other specifications define a specific property underwhich extensions are placed (e.g. a top-level `extensions` property), the -authors decided that having two different locations within an -incoming event for unknown properties could lead to interoperability issues -and confusion for developers. - -Often extensions are used to test new potential properties of -specifications prior to them being formally adopted. If there were an -`extensions` type of property, in which this new property was serialized, -then if that property were to ever be adopted by the core specification it -would be promoted (from a serialization perspective) from the `extensions` -property to be a top-level property. If we assume that this new property -will be optional, then as it is adopted by the core specification it will -be just a minor version increment, and all existing consumers should still -continue to work. However, consumers will not know where this property -will appear - in the `extensions` property or as a top-level property. -This means they might need to look in both places. What if the property -appears in both place but with different values? Will producers need to place -it in both places since they could have old and new consumers? While -it might be possible to define clear rules for how to solve each of the -potential problems that arise, the authors decided that it would be better -to simply avoid all of them in the first place by only having one location -in the serialization for unkown, or even new, properties. It was also -noted that the HTTP specification is now following a similar pattern by -no longer suggesting that extension HTTP headers be prefixed with `X-`. +authors decided that having two different locations within an incoming event for +unknown properties could lead to interoperability issues and confusion for +developers. + +Often extensions are used to test new potential properties of specifications +prior to them being formally adopted. If there were an `extensions` type of +property, in which this new property was serialized, then if that property were +to ever be adopted by the core specification it would be promoted (from a +serialization perspective) from the `extensions` property to be a top-level +property. If we assume that this new property will be optional, then as it is +adopted by the core specification it will be just a minor version increment, and +all existing consumers should still continue to work. However, consumers will +not know where this property will appear - in the `extensions` property or as a +top-level property. This means they might need to look in both places. What if +the property appears in both place but with different values? Will producers +need to place it in both places since they could have old and new consumers? +While it might be possible to define clear rules for how to solve each of the +potential problems that arise, the authors decided that it would be better to +simply avoid all of them in the first place by only having one location in the +serialization for unkown, or even new, properties. It was also noted that the +HTTP specification is now following a similar pattern by no longer suggesting +that extension HTTP headers be prefixed with `X-`. ## Qualifying Protocols and Encodings @@ -262,15 +256,15 @@ projections of its data format onto commonly used protocols and with commonly used encodings. While each software or service product and project can obviously make its own -choices about which form of communication it prefers, its unquestionable that -a proprietary protocol that is private to such a product or project does not +choices about which form of communication it prefers, its unquestionable that a +proprietary protocol that is private to such a product or project does not further the goal of broad interoperability across producers and consumers of events. Especially in the area of messaging and eventing, the industry has made significant progress in the last decade in developing a robust and broadly -supported protocol foundation, like HTTP 1.1 and HTTP/2 as well as WebSockets -or events on the web, or MQTT and AMQP for connection-oriented messaging and +supported protocol foundation, like HTTP 1.1 and HTTP/2 as well as WebSockets or +events on the web, or MQTT and AMQP for connection-oriented messaging and telemetry transfers. Some widely used protocols have become de-facto standards emerging out of strong @@ -279,8 +273,8 @@ the strong ecosystems of projects released by a single company, and in either case largely in parallel to the evolution of the previously mentioned standards stacks. -The CloudEvents effort shall not become a vehicle to even implicitly endorse -or promote project- or product-proprietary protocols, because that would be +The CloudEvents effort shall not become a vehicle to even implicitly endorse or +promote project- or product-proprietary protocols, because that would be counterproductive towards CloudEvents' original goals. For a protocol or encoding to qualify for a core CloudEvents event format or @@ -289,19 +283,19 @@ protocol binding, it must belong to either one of the following categories: - The protocol has a formal status as a standard with a widely-recognized multi-vendor protocol standardization body (e.g. W3C, IETF, OASIS, ISO) - The protocol has a "de-facto standard" status for its ecosystem category, - which means it is used so widely that it is considered a standard for a - given application. Practically, we would like to see at least one open - source implementation under the umbrella of a vendor-neutral open-source - organization (e.g. Apache, Eclipse, CNCF, .NET Foundation) and at least - a dozen independent vendors using it in their products/services. + which means it is used so widely that it is considered a standard for a given + application. Practically, we would like to see at least one open source + implementation under the umbrella of a vendor-neutral open-source organization + (e.g. Apache, Eclipse, CNCF, .NET Foundation) and at least a dozen independent + vendors using it in their products/services. Aside from formal status, a key criterion for whether a protocol or encoding shall qualify for a core CloudEvents event format or transport binding is -whether the group agrees that the specification will be of sustained -practical benefit for any party that is unrelated to the product or project -from which the protocol or encoding emerged. A base requirement for this is -that the protocol or encoding is defined in a fashion that allows alternate -implementations independent of the product or project's code. +whether the group agrees that the specification will be of sustained practical +benefit for any party that is unrelated to the product or project from which the +protocol or encoding emerged. A base requirement for this is that the protocol +or encoding is defined in a fashion that allows alternate implementations +independent of the product or project's code. All other protocol and encoding formats for CloudEvents are welcome to be included in a list pointing to the CloudEvents binding information in the @@ -315,35 +309,35 @@ maintainers are not responsible for creating, maintaining, or notifying maintainers of proprietary specs of drift from the CloudEvents spec. Proprietary specs will be hosted in their own repository or documentation site, -and collected in the [proprietary-specs](proprietary-specs.md) file. -Proprietary specs should follow -the same format as the other specs for core protocols and encodings. +and collected in the [proprietary-specs](proprietary-specs.md) file. Proprietary +specs should follow the same format as the other specs for core protocols and +encodings. Proprietary specs will receive less scrutiny than a core spec, and as the -CloudEvents spec evolves, it is the the responsibility of the maintainers of -the respective protocols and encodings to keep specs in sync with the -CloudEvents spec. If a proprietary spec falls too far out of date, CloudEvents -may mark the link to that spec as deprecated or remove it. +CloudEvents spec evolves, it is the the responsibility of the maintainers of the +respective protocols and encodings to keep specs in sync with the CloudEvents +spec. If a proprietary spec falls too far out of date, CloudEvents may mark the +link to that spec as deprecated or remove it. -In the case that multiple, incompatible specs are created for the same -protocol, the repository maintainers will be agnostic about which spec is -correct and list links to all specs. +In the case that multiple, incompatible specs are created for the same protocol, +the repository maintainers will be agnostic about which spec is correct and list +links to all specs. ## Prior Art -This section describes some of the input material used by the group -during the development of the CloudEvent specification. +This section describes some of the input material used by the group during the +development of the CloudEvent specification. ### Roles -The list below enumerates the various participants, and scenarios, that might -be involved in the producing, managing or consuming of events. +The list below enumerates the various participants, and scenarios, that might be +involved in the producing, managing or consuming of events. -In these the roles of event producer and event consumer are kept -distinct. A single application context can always take on multiple roles -concurrently, including being both a producer and a consumer of events. +In these the roles of event producer and event consumer are kept 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 +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. @@ -355,129 +349,120 @@ concurrently, including being both a producer and a consumer of events. 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 + 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 CloudEvents 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, + 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 + CloudEvents 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. + 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. + + - 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. + + - 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 CloudEvents, while preserving the - identity and semantic integrity of the event. + - Transformation that changes the event's structure, like mapping from a + proprietary format to CloudEvents, 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. + - 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. + + - 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. + - 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. ### Value Proposition -This section describes some of the use-cases that explain the value -of CloudEvents. +This section describes some of the use-cases that explain the value of +CloudEvents. #### Normalizing Events Across Services & Platforms -Major event publishers (e.g. AWS, Microsoft, Google, etc.) all publish events -in different formats on their respective platforms. There are even a few cases +Major event publishers (e.g. AWS, Microsoft, Google, etc.) all publish events in +different formats on their respective platforms. There are even a few cases where services on the same provider publish events in different formats (e.g. AWS). This forces event consumers to implement custom logic to read or munge event data across platforms and occasionally across services on a single @@ -492,8 +477,7 @@ Event data being transported across environments is increasingly common. However, without a common way of describing events, delivery of events across environments is hindered. There is no single way of determining where an event came from and where it might be going. This prevents tooling to facilitate -successful event delivery and consumers from knowing what to do with event -data. +successful event delivery and consumers from knowing what to do with event data. CloudEvents offers useful metadata which middleware and consumers can rely upon to facilitate event routing, logging, delivery and receipt. @@ -501,11 +485,11 @@ to facilitate event routing, logging, delivery and receipt. #### Increasing Portability of Functions-as-a-Service Functions-as-a-Service (also known as serverless computing) is one of the -fastest growing trends in IT and it is largely event-driven. However, a -primary concern of FaaS is vendor lock-in. This lock-in is partially caused -by differences in function APIs and signatures across providers, but the -lock-in is also caused by differences in the format of event data received -within functions. +fastest growing trends in IT and it is largely event-driven. However, a primary +concern of FaaS is vendor lock-in. This lock-in is partially caused by +differences in function APIs and signatures across providers, but the lock-in is +also caused by differences in the format of event data received within +functions. CloudEvents' common way of describing event data increases the portability of Functions-as-a-Service. @@ -517,14 +501,14 @@ event-driven and serverless architectures. There is no easy way to mock events accurately for development and testing purposes, and help emulate event-driven workflows in a development environment. -CloudEvents can enable better developer tools for building, testing and -handling the end-to-end lifecycle of event-driven and serverless architectures. +CloudEvents can enable better developer tools for building, testing and handling +the end-to-end lifecycle of event-driven and serverless architectures. #### Event Data Evolution Most platforms and services version the data model of their events differently -(if they do this at all). This creates an inconsistent experience for -publishing and consuming the data model of events as those data models evolve. +(if they do this at all). This creates an inconsistent experience for publishing +and consuming the data model of events as those data models evolve. CloudEvents can offer a common way to version and evolve event data. This will help event publishers safely version their data models based on best practices, @@ -551,11 +535,10 @@ transited and allow for better introspection of the data. #### Event Tracing -An event sent from a source may result in a sequence of additional events -sent from various middleware devices such as event brokers and gateways. -CloudEvents includes metadata in events to associate these events as being -part of an event sequence for the purpose of event tracing and -troubleshooting. +An event sent from a source may result in a sequence of additional events sent +from various middleware devices such as event brokers and gateways. CloudEvents +includes metadata in events to associate these events as being part of an event +sequence for the purpose of event tracing and troubleshooting. #### Cloudbursting @@ -563,15 +546,14 @@ TBD #### IoT -IoT devices send and receive events related to their functionality. -For example, a connected thermostat will send telemetry on the current -temperature and could receive events to change temperatures. -These devices typically have a constrained operating environment -(cpu, memory) requiring a well defined event message format. -In a lot of cases these messages are binary encoded instead of textual. -Whether directly from the device or transformed via a gateway, CloudEvents -would allow for a better description of the origin of the message and the -format of the data contained within the message. +IoT devices send and receive events related to their functionality. For example, +a connected thermostat will send telemetry on the current temperature and could +receive events to change temperatures. These devices typically have a +constrained operating environment (cpu, memory) requiring a well defined event +message format. In a lot of cases these messages are binary encoded instead of +textual. Whether directly from the device or transformed via a gateway, +CloudEvents would allow for a better description of the origin of the message +and the format of the data contained within the message. #### Event Correlation @@ -591,12 +573,12 @@ instance to the correct application/workflow instance. ### Existing Event Formats -As with the previous section, the examination (and understanding) of the -current state of the world was very important to the group. To that -end, a sampling of existing current event formats that are used in practice -today was gathered. +As with the previous section, the examination (and understanding) of the current +state of the world was very important to the group. To that end, a sampling of +existing current event formats that are used in practice today was gathered. #### Microsoft - Event Grid + ``` { "topic":"/subscriptions/{subscription-id}", @@ -618,9 +600,11 @@ today was gathered. } } ``` + [Documentation](https://docs.microsoft.com/en-us/azure/event-grid/event-schema) #### Google - Cloud Functions (potential future) + ``` { "data": { @@ -645,6 +629,7 @@ today was gathered. ``` #### AWS - SNS + ``` { "Records": [ @@ -678,9 +663,11 @@ today was gathered. ] } ``` + [Documentation](http://docs.aws.amazon.com/lambda/latest/dg/eventsources.html) #### AWS - Kinesis + ``` { "Records": [ @@ -704,6 +691,7 @@ today was gathered. ``` #### IBM - OpenWhisk - Web Action Event + ``` { "__ow_method": "post", @@ -721,6 +709,7 @@ today was gathered. ``` #### OpenStack - Audit Middleware - Event + ``` { "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", @@ -756,9 +745,11 @@ today was gathered. "requestPath": "/v2/ae63ddf2076d4342a56eb049e37a7621/servers/b1b475fc-ef0a-4899-87f3-674ac0d56855" } ``` + [Documentation](https://github.com/openstack/pycadf/blob/master/doc/source/event_concept.rst) #### Adobe - I/O Events + ``` { "event_id": "639fd17a-d0bb-40ca-83a4-e78612bce5dc", @@ -790,4 +781,5 @@ today was gathered. } } ``` + [Documentation](https://www.adobe.io/apis/cloudplatform/events/documentation.html) diff --git a/proprietary-specs.md b/proprietary-specs.md index 30f2a96ff..2ce65ad39 100644 --- a/proprietary-specs.md +++ b/proprietary-specs.md @@ -1,8 +1,7 @@ ### CloudEvent Specs for Proprietary Protocols and Encodings -Disclaimer: CloudEvents does not endorse these protocols or -specs, and does not ensure that they are up to date with the -current version of CloudEvents. That is the responsibility of -the respective project maintainers. +Disclaimer: CloudEvents does not endorse these protocols or specs, and does not +ensure that they are up to date with the current version of CloudEvents. That is +the responsibility of the respective project maintainers. -* [placeholder](/) +- [placeholder](/) diff --git a/protobuf-format.md b/protobuf-format.md index 46261fd63..7077d3988 100644 --- a/protobuf-format.md +++ b/protobuf-format.md @@ -1,9 +1,9 @@ -# Protocol Buffers Event Format for CloudEvents - Version 0.2 +# Protocol Buffers Event Format for CloudEvents - Version 0.2 ## Abstract -The Protocol Buffers Format for CloudEvents (CE) defines the encoding -of CloudEvents in the Protocol Buffers binary format. +The Protocol Buffers Format for CloudEvents (CE) defines the encoding of +CloudEvents in the Protocol Buffers binary format. ## Status of this document @@ -11,48 +11,41 @@ This document is a working draft. ## 1. Introduction -This specification defines how the [Context -Attributes](spec.md#context-attributes) defined in the CloudEvents -specification MUST be encoded in the protocol buffer binary -format. Transcoding to and from other formats (e.g. JSON) is out of -the scope of this document. - -Protocol Buffers are a language-neutral, platform-neutral extensible -mechanism for serializing structured data. The [Google reference -implementation of Protocol -Buffers](https://github.com/protocolbuffers/protobuf) includes support -for an interface descriptor language (IDL), and this document makes -use of language level 3 IDL from Protocol Buffers v3.5.0. CloudEvents -systems using Protocol Buffers are not mandated to use the IDL or any -particular implementation of Protocol Buffers as long as they produce -messages which match the binary encoding defined by the IDL. +This specification defines how the +[Context Attributes](spec.md#context-attributes) defined in the CloudEvents +specification MUST be encoded in the protocol buffer binary format. Transcoding +to and from other formats (e.g. JSON) is out of the scope of this document. +Protocol Buffers are a language-neutral, platform-neutral extensible mechanism +for serializing structured data. The +[Google reference implementation of Protocol Buffers](https://github.com/protocolbuffers/protobuf) +includes support for an interface descriptor language (IDL), and this document +makes use of language level 3 IDL from Protocol Buffers v3.5.0. CloudEvents +systems using Protocol Buffers are not mandated to use the IDL or any particular +implementation of Protocol Buffers as long as they produce messages which match +the binary encoding defined by the IDL. ### 1.1. Conformance -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", -"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this -document are to be interpreted as described in -[RFC2119](https://tools.ietf.org/html/rfc2119). + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [RFC2119](https://tools.ietf.org/html/rfc2119). ## 2. Protocol Buffers format Protocol Buffers provide a binary data serialization format which is -substantially more compact and efficient to parse when compared to XML -or JSON, along with a variety of language-specific libraries to -perform automatic serialization and deserialization. The [Protocol -Buffers specification defines a well-known encoding -format](https://developers.google.com/protocol-buffers/docs/encoding) -which is the basis of this specification. This specification is -described using the Protocol Buffers project IDL for readability, but -the ultimate basis of this specification is the Protocol Buffers -binary encoding. - +substantially more compact and efficient to parse when compared to XML or JSON, +along with a variety of language-specific libraries to perform automatic +serialization and deserialization. The +[Protocol Buffers specification defines a well-known encoding format](https://developers.google.com/protocol-buffers/docs/encoding) +which is the basis of this specification. This specification is described using +the Protocol Buffers project IDL for readability, but the ultimate basis of this +specification is the Protocol Buffers binary encoding. ### 2.1 Definition -Users of Protocol Buffers MUST use a message whose binary encoding is -identical to the one described by the [CloudEventMap -message](./cloudevent.proto): +Users of Protocol Buffers MUST use a message whose binary encoding is identical +to the one described by the [CloudEventMap message](./cloudevent.proto): ```proto syntax = "proto3"; @@ -74,26 +67,26 @@ message CloudEventAny { } ``` -The CloudEvents type system MUST be mapped into the fields of -`CloudEventAny` as follows: - +The CloudEvents type system MUST be mapped into the fields of `CloudEventAny` as +follows: -| CloudEvents | CloudEventAny field -|---------------|------------------------------------------------------------- -| String | string_value -| Binary | binary_value -| URI-reference | string_value (string expression conforming to URI-reference as defined in [RFC 3986 §4.1](https://tools.ietf.org/html/rfc3986#section-4.1)) -| Timestamp | string_value (string expression as defined in [RFC 3339](https://tools.ietf.org/html/rfc3339)) -| Map | map_value -| Integer | int_value -| Any | Not applicable. Any is the enclosing CloudEventAny message itself +| CloudEvents | CloudEventAny field | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| String | string_value | +| Binary | binary_value | +| URI-reference | string_value (string expression conforming to URI-reference as defined in [RFC 3986 §4.1](https://tools.ietf.org/html/rfc3986#section-4.1)) | +| Timestamp | string_value (string expression as defined in [RFC 3339](https://tools.ietf.org/html/rfc3339)) | +| Map | map_value | +| Integer | int_value | +| Any | Not applicable. Any is the enclosing CloudEventAny message itself | -Protocol Buffer representations of CloudEvents MUST use the media type `application/cloudevents+proto`. +Protocol Buffer representations of CloudEvents MUST use the media type +`application/cloudevents+proto`. ## 3. Examples -Below is an example of how to create a CloudEvent Protocol Buffer -message using the Java Google Protocol Buffers library: +Below is an example of how to create a CloudEvent Protocol Buffer message using +the Java Google Protocol Buffers library: ```java import com.google.common.base.Charsets; diff --git a/roadmap.md b/roadmap.md index 74dfa4f88..2e220189f 100644 --- a/roadmap.md +++ b/roadmap.md @@ -5,22 +5,22 @@ The CloudEvents Roadmap. _Note: The ordered lists for each milestone provide a way to reference each item; they don't imply an order for implementation._ -*Setup* - Completed - 2018/02/26 +_Setup_ - Completed - 2018/02/26 1. Establish governance, contributing guidelines and initial stakeholders. 1. Define design goals for CloudEvents V.1. 1. Describe the scope of the specification. 1. Draft educational materials that provide context for reading the spec. -*0.1* - Completed - 2018/04/20 +_0.1_ - Completed - 2018/04/20 -1. Draft specification that project members agree *could* provide +1. Draft specification that project members agree _could_ provide interoperability. 1. Include an initial set of use-cases for CloudEvents. 1. Define a type system for CloudEvents values. 1. Document at least 3 sample events that conform to the specification. -1. Github repo is organized to be approachable to a engineers who might want - to implement the spec. +1. Github repo is organized to be approachable to a engineers who might want to + implement the spec. 1. Finalize logo. 1. Create and deploy a website that features a simple overview, email list and directs visitors to Github. @@ -36,13 +36,13 @@ item; they don't imply an order for implementation._ 1. Publicize at conferences ([CloudNativeCon Europe](https://events.linuxfoundation.org/events/kubecon-cloudnativecon-north-america-2018/)). 1. Interoperability demo. - 1. At least one open source implementation of sending and receiving - events, see - [community open source](https://github.com/cloudevents/spec/blob/master/community/open-source.md). - 1. Events are sent by code written by Developer1 and received by code - written by Developer2, where Developer1 has no knowledge of Developer2. + 1. At least one open source implementation of sending and receiving events, + see + [community open source](https://github.com/cloudevents/spec/blob/master/community/open-source.md). + 1. Events are sent by code written by Developer1 and received by code written + by Developer2, where Developer1 has no knowledge of Developer2. -*0.2* - Completed - 2018/12/06 +_0.2_ - Completed - 2018/12/06 1. Incorporate learnings and feedback from interop demo to support wider adoption. @@ -50,31 +50,29 @@ item; they don't imply an order for implementation._ 1. Resolve all known large design issues (excluding security issues) 1. Resolve all known "proposed required attributes" issues 1. Interoperability demo 2 - 1. Details to be determined - 1. Showcase demo at conferences - perhaps KubeCon NA 2018 -1. Define the set of protocol and serialization mappings we're going to - produce for 0.4 milestone + 1. Details to be determined + 1. Showcase demo at conferences - perhaps KubeCon NA 2018 +1. Define the set of protocol and serialization mappings we're going to produce + for 0.4 milestone -*0.3* +_0.3_ 1. Resolve all known "proposed optional attributes" issues 1. Resolve all known "security related" issues 1. Review spec for practical-use issues: - 1. Consider context size limits - 1. Consider restricting character sets of `String` properties or key names - 1. Consider defining uniqueness constraints of event `id` - 1. Consider which fields will be immutable (prevents annotation or - redaction) - 1. Consider validating transport bindings with load tests + 1. Consider context size limits + 1. Consider restricting character sets of `String` properties or key names + 1. Consider defining uniqueness constraints of event `id` + 1. Consider which fields will be immutable (prevents annotation or redaction) + 1. Consider validating transport bindings with load tests -*0.4* +_0.4_ 1. Complete the proposed set of protocol and serialization mappings 1. Resolve "Process" related issues -*0.5* +_0.5_ 1. Resolve outstanding clarifications and non-semantic issues 1. Define and prioritize libraries and supporting tools that will accelerate adoption of CloudEvents - diff --git a/share/README.md b/share/README.md index a5bda5f8c..b72057f58 100644 --- a/share/README.md +++ b/share/README.md @@ -1,9 +1,8 @@ -Directory to hold material that project members wish to share with each other - -e.g. presentations from meetings or from conferences. -These documents have no official standing within the group. -References from this README to the documents can point to files stored -in this repository or can be external. -To add new files, or references, create a PR to this repository. +Directory to hold material that project members wish to share with each other - +e.g. presentations from meetings or from conferences. These documents have no +official standing within the group. References from this README to the documents +can point to files stored in this repository or can be external. To add new +files, or references, create a PR to this repository. For new uploaded files, please follow the naming pattern: `yyyy-mm-dd-Presentation-Name` @@ -12,23 +11,21 @@ For example: `2018-02-27-MyCoolIdea.pdf` --- -* 2018-02-22 Clemens Vasters: +- 2018-02-22 Clemens Vasters: [CloudEvents-Routing](2018-02-22-CloudEvents-Routing.pptx) -* 2018-02-22 Yaron Haviv: - [CloudEvents](2018-02-22-CloudEvents.pdf) +- 2018-02-22 Yaron Haviv: [CloudEvents](2018-02-22-CloudEvents.pdf) -* 2018-03-01 Cathy Hong: +- 2018-03-01 Cathy Hong: [What is Source?](https://docs.google.com/document/d/1jc4X-aUT4Foqrz2dMqSNtrW1ZezgL4qdCBpgAvd9UmM/edit) -* 2018-03-01 Sarah Allen: +- 2018-03-01 Sarah Allen: [Cloud Event-Concepts](https://docs.google.com/presentation/d/1xippFyX9fXqlTWUh3waZcanVMHF12z0AbZ8EK3fk3ys/edit#slide=id.g32172c993c_0_5) -* 2018-03-22 Clemens Vasters: - Topics and Subjects +- 2018-03-22 Clemens Vasters: Topics and Subjects [Video](https://1drv.ms/v/s!AgcBsXoqzTwSrc4xtiQ25VGGln6zWw) & [ppt](2018-03-22-TopicsAndSubjects.pptx) -* 2018-11-14 KubeCon/CloudNativeCon China Nov 2018: +- 2018-11-14 KubeCon/CloudNativeCon China Nov 2018: [CloudEvent/Serverless Intro and Deep-Dive sessions](https://docs.google.com/presentation/d/1-Nq_HrJPFvFz_etbKGCo4_RZnhA3OuzwLl0EMFnafxw/edit) & [pdf](2018-11-14-KubeCon-Intro-DeepDive.pdf) diff --git a/spec.json b/spec.json index 954dd3f64..8759b8a46 100644 --- a/spec.json +++ b/spec.json @@ -9,10 +9,7 @@ "type": "string" }, "data": { - "type": [ - "object", - "string" - ] + "type": ["object", "string"] }, "event": { "properties": { @@ -44,12 +41,7 @@ "$ref": "#/definitions/source" } }, - "required": [ - "specversion", - "id", - "type", - "source" - ], + "required": ["specversion", "id", "type", "source"], "type": "object" }, "id": { diff --git a/spec.md b/spec.md index 950fab6c6..23e3ef132 100644 --- a/spec.md +++ b/spec.md @@ -2,14 +2,15 @@ ## Abstract -CloudEvents is a vendor-neutral specification for defining the format -of event data. +CloudEvents is a vendor-neutral specification for defining the format of event +data. ## Status of this document This document is a working draft. ## Table of Contents + - [Overview](#overview) - [Notations and Terminology](#notations-and-terminology) - [Type System](#type-system) @@ -19,55 +20,56 @@ This document is a working draft. - [Example](#example) ## Overview + Events are everywhere. However, event producers tend to describe events differently. The lack of a common way of describing events means developers are constantly re-learning how to consume events. This also limits the potential for libraries, tooling and infrastructure to aide the delivery of event data across -environments, like SDKs, event routers or tracing systems. The portability -and productivity that can be achieved from event data is hindered overall. +environments, like SDKs, event routers or tracing systems. The portability and +productivity that can be achieved from event data is hindered overall. -CloudEvents is a specification for describing event data in common formats -to provide interoperability across services, platforms and systems. +CloudEvents is a specification for describing event data in common formats to +provide interoperability across services, platforms and systems. Event Formats specify how to serialize a CloudEvent with certain encoding -formats. Compliant CloudEvents implementations that support those encodings -MUST adhere to the encoding rules specified in the respective event format. -All implementations MUST support the [JSON format](json-format.md). +formats. Compliant CloudEvents implementations that support those encodings MUST +adhere to the encoding rules specified in the respective event format. All +implementations MUST support the [JSON format](json-format.md). -For more information on the history, development and design rationale -behind the specification, see the [CloudEvents Primer](primer.md) document. +For more information on the history, development and design rationale behind the +specification, see the [CloudEvents Primer](primer.md) document. ## Notations and Terminology ### Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to -be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). For clarity, when a feature is marked as "OPTIONAL" this means that it is OPTIONAL for both the sender and receiver of a message to support that feature. -In other words, a sender can choose to include that feature in a -message if it wants, and a receiver can choose to support that feature -if it wants. A receiver that does not support that feature will then silently -ignore that part of the message. The sender needs to be prepared for the -situation where a receiver ignores that feature. +In other words, a sender can choose to include that feature in a message if it +wants, and a receiver can choose to support that feature if it wants. A receiver +that does not support that feature will then silently ignore that part of the +message. The sender needs to be prepared for the situation where a receiver +ignores that feature. ### Attribute Naming Convention The CloudEvents specifications define mappings to various protocols and encodings, and the accompanying CloudEvents SDK targets various runtimes and languages. Some of these treat metadata elements as case-sensitive while others -do not, and a single CloudEvent might be routed via multiple hops that involve -a mix of protocols, encodings, and runtimes. Therefore, this specification -limits the available character set of all attributes such that -case-sensitivity issues or clashes with the permissible character set for -identifiers in common languages are prevented. - -CloudEvents attribute names MUST consist of lower-case letters ('a' to 'z') -or digits ('0' to '9') from the ASCII character set, and MUST begin with a +do not, and a single CloudEvent might be routed via multiple hops that involve a +mix of protocols, encodings, and runtimes. Therefore, this specification limits +the available character set of all attributes such that case-sensitivity issues +or clashes with the permissible character set for identifiers in common +languages are prevented. + +CloudEvents attribute names MUST consist of lower-case letters ('a' to 'z') or +digits ('0' to '9') from the ASCII character set, and MUST begin with a lower-case letter. Attribute names SHOULD be descriptive and terse, and SHOULD NOT exceed 20 characters in length. @@ -76,58 +78,62 @@ NOT exceed 20 characters in length. This specification defines the following terms: #### Occurrence -An "occurrence" is the capture of a statement of fact during the operation of -a software system. This might occur because of a signal raised by the system or -a signal being observed by the system, because of a state change, because of -a timer elapsing, or any other noteworthy activity. For example, a device might -go into an alert state because the battery is low, or a virtual machine is -about to perform a scheduled reboot. + +An "occurrence" is the capture of a statement of fact during the operation of a +software system. This might occur because of a signal raised by the system or a +signal being observed by the system, because of a state change, because of a +timer elapsing, or any other noteworthy activity. For example, a device might go +into an alert state because the battery is low, or a virtual machine is about to +perform a scheduled reboot. #### Event -An "event" is a data record expressing an occurrence and its context. Events -are routed from an event producer (the source) to interested event consumers. -The routing can be performed based on information contained in the event, but -an event will not identify a specific routing destination. Events will contain -two types of information: the [Data](#data) representing the Occurrence and + +An "event" is a data record expressing an occurrence and its context. Events are +routed from an event producer (the source) to interested event consumers. The +routing can be performed based on information contained in the event, but an +event will not identify a specific routing destination. Events will contain two +types of information: the [Data](#data) representing the Occurrence and [Context](#context) metadata providing contextual information about the Occurrence. #### Context -Context metadata will -be encapsulated in the [Context Attributes](#context-attributes). -Tools and application code can use this information to identify the -relationship of Events to aspects of the system or to other Events. + +Context metadata will be encapsulated in the +[Context Attributes](#context-attributes). Tools and application code can use +this information to identify the relationship of Events to aspects of the system +or to other Events. #### Data -Domain-specific information about the occurrence (i.e. the payload). This -might include information about the occurrence, details about the data -that was changed, or more. See the [Data Attribute](#data-attribute) section -for more information. + +Domain-specific information about the occurrence (i.e. the payload). This might +include information about the occurrence, details about the data that was +changed, or more. See the [Data Attribute](#data-attribute) section for more +information. #### Message + Events are transported from a source to a destination via messages. #### Protocol + Messages can be delivered through various industry standard protocol (e.g. HTTP, -AMQP, MQTT, SMTP), open-source protocols (e.g. Kafka, NATS), or -platform/vendor specific protocols (AWS Kinesis, Azure Event Grid). +AMQP, MQTT, SMTP), open-source protocols (e.g. Kafka, NATS), or platform/vendor +specific protocols (AWS Kinesis, Azure Event Grid). ## Type System The following abstract data types are available for use in attributes. -- `Integer` - A whole number in the range -2,147,483,648 to - +2,147,483,647 inclusive. This is the range of a signed, 32-bit, - twos-complement encoding. Event formats do not have to use - this encoding, but they MUST only use `Integer` values in this - range. +- `Integer` - A whole number in the range -2,147,483,648 to +2,147,483,647 + inclusive. This is the range of a signed, 32-bit, twos-complement encoding. + Event formats do not have to use this encoding, but they MUST only use + `Integer` values in this range. - `String` - Sequence of printable Unicode characters. - `Binary` - Sequence of bytes. - `Map` - `String`-indexed dictionary of `Any`-typed values. - `Any` - Either a `Binary`, `Integer`, `Map` or `String`. -- `URI-reference` - String expression conforming to `URI-reference` - as defined in - [RFC 3986 §4.1](https://tools.ietf.org/html/rfc3986#section-4.1). +- `URI-reference` - String expression conforming to `URI-reference` as defined + in [RFC 3986 §4.1](https://tools.ietf.org/html/rfc3986#section-4.1). - `Timestamp` - String expression as defined in [RFC 3339](https://tools.ietf.org/html/rfc3339). @@ -136,6 +142,7 @@ The `Any` type is a variant type that can take the shape of either a `Binary`, therefore it is left to implementations how to represent the variant type. ## Context Attributes + Every CloudEvent conforming to this specification MUST include context attributes designated as REQUIRED and MAY include one or more OPTIONAL context attributes. @@ -144,113 +151,121 @@ These attributes, while descriptive of the event, are designed such that they can be serialized independent of the event data. This allows for them to be inspected at the destination without having to deserialize the event data. -The choice of serialization mechanism will determine how the context -attributes and the event data will be materialized. For example, in the case -of a JSON serialization, the context attributes and the event data might -both appear within the same JSON object. +The choice of serialization mechanism will determine how the context attributes +and the event data will be materialized. For example, in the case of a JSON +serialization, the context attributes and the event data might both appear +within the same JSON object. ### type -* Type: `String` -* Description: Type of occurrence which has happened. Often this - attribute is used for routing, observability, policy enforcement, etc. - The format of this is producer defined and might include information such - as the version of the `type` - see + +- Type: `String` +- Description: Type of occurrence which has happened. Often this attribute is + used for routing, observability, policy enforcement, etc. The format of this + is producer defined and might include information such as the version of the + `type` - see [Versioning of Attributes in the Primer](primer.md#versioning-of-attributes) for more information. -* Constraints: - * REQUIRED - * MUST be a non-empty string - * SHOULD be prefixed with a reverse-DNS name. The prefixed domain dictates - the organization which defines the semantics of this event type. -* Examples - * com.github.pull.create - * com.example.object.delete.v2 +- Constraints: + - REQUIRED + - MUST be a non-empty string + - SHOULD be prefixed with a reverse-DNS name. The prefixed domain dictates the + organization which defines the semantics of this event type. +- Examples + - com.github.pull.create + - com.example.object.delete.v2 ### specversion -* Type: `String` -* Description: The version of the CloudEvents specification which the event - uses. This enables the interpretation of the context. Compliant event - producers MUST use a value of `0.2` when referring to this version of - the specification. -* Constraints: - * REQUIRED - * MUST be a non-empty string + +- Type: `String` +- Description: The version of the CloudEvents specification which the event + uses. This enables the interpretation of the context. Compliant event + producers MUST use a value of `0.2` when referring to this version of the + specification. +- Constraints: + - REQUIRED + - 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/123 + - /cloudevents/spec/pull/123 + - urn:event:from:myapi/resourse/123 + - mailto:cncf-wg-serverless@lists.cncf.io ### id -* Type: `String` -* Description: ID of the event. The semantics of this string are explicitly + +- Type: `String` +- Description: ID of the event. The semantics of this string are explicitly undefined to ease the implementation of producers. Enables deduplication. -* Examples: - * A database commit ID -* Constraints: - * REQUIRED - * MUST be a non-empty string - * MUST be unique within the scope of the producer +- Examples: + - A database commit ID +- Constraints: + - REQUIRED + - MUST be a non-empty string + - MUST be unique within the scope of the producer ### time -* Type: `Timestamp` -* Description: Timestamp of when the event happened. -* Constraints: - * OPTIONAL - * If present, MUST adhere to the format specified in + +- Type: `Timestamp` +- Description: Timestamp of when the event happened. +- Constraints: + - OPTIONAL + - If present, MUST adhere to the format specified in [RFC 3339](https://tools.ietf.org/html/rfc3339) ### schemaurl -* Type: `URI-reference` -* Description: A link to the schema that the `data` attribute adheres to. - Incompatible changes to the schema SHOULD be reflected by a different URL. - See + +- Type: `URI-reference` +- Description: A link to the schema that the `data` attribute adheres to. + Incompatible changes to the schema SHOULD be reflected by a different URL. See [Versioning of Attributes in the Primer](primer.md#versioning-of-attributes) for more information. -* Constraints: - * OPTIONAL +- Constraints: + - OPTIONAL ### datacontenttype -* Type: `String` per [RFC 2046](https://tools.ietf.org/html/rfc2046) -* Description: Content type of the `data` attribute value. This attribute - enables the `data` attribute to carry any type of content, whereby format - and encoding might differ from that of the chosen event format. For example, - an event rendered using the [JSON envelope](./json-format.md#3-envelope) - format might carry an XML payload in its `data` attribute, and the - consumer is informed by this attribute being set to "application/xml". The - rules for how the `data` attribute content is rendered for different - `datacontenttype` values are defined in the event format specifications; for - example, the JSON event format defines the relationship in + +- Type: `String` per [RFC 2046](https://tools.ietf.org/html/rfc2046) +- Description: Content type of the `data` attribute value. This attribute + enables the `data` attribute to carry any type of content, whereby format and + encoding might differ from that of the chosen event format. For example, an + event rendered using the [JSON envelope](./json-format.md#3-envelope) format + might carry an XML payload in its `data` attribute, and the consumer is + informed by this attribute being set to "application/xml". The rules for how + the `data` attribute content is rendered for different `datacontenttype` + values are defined in the event format specifications; for example, the JSON + event format defines the relationship in [section 3.1](./json-format.md#31-special-handling-of-the-data-attribute). - When this attribute is omitted, the `data` attribute simply follows the - event format's encoding rules. For the JSON event format, the `data` - attribute value can therefore be a JSON object, array, or value. + When this attribute is omitted, the `data` attribute simply follows the event + format's encoding rules. For the JSON event format, the `data` attribute value + can therefore be a JSON object, array, or value. - For the binary mode of some of the CloudEvents transport bindings, - where the `data` content is immediately mapped into the payload of the - transport frame, this field is directly mapped to the respective transport - or application protocol's content-type metadata property. Normative rules - for the binary mode and the content-type metadata mapping can be found - in the respective transport mapping specifications. + For the binary mode of some of the CloudEvents transport bindings, where the + `data` content is immediately mapped into the payload of the transport frame, + this field is directly mapped to the respective transport or application + protocol's content-type metadata property. Normative rules for the binary mode + and the content-type metadata mapping can be found in the respective transport + mapping specifications. -* Constraints: - * OPTIONAL - * If present, MUST adhere to the format specified in +- Constraints: + - OPTIONAL + - If present, MUST adhere to the format specified in [RFC 2046](https://tools.ietf.org/html/rfc2046) -* For Media Type examples see [IANA Media Types](http://www.iana.org/assignments/media-types/media-types.xhtml) +- For Media Type examples see + [IANA Media Types](http://www.iana.org/assignments/media-types/media-types.xhtml) ### Extension Context Attributes + CloudEvents producers MAY include additional context attributes in the event that might be used in ancillary actions related to the processing of the event. See @@ -258,30 +273,29 @@ See for additional information concerning the use and definition of extensions. This specification places no restriction on the type or semantics of the -extension attributes. Each definition of an extensions SHOULD fully -define all aspects of the attribute - e.g. its name, semantic meaning -and possible values or even to indicate that it places no restrictions on -its values. New extension definitions SHOULD use a name that is -descriptive enough to reduce the chances of name collisions with other -extensions. In particular, extension authors SHOULD check the -[documented extensions](documented-extensions.md) document for the -set of known extensions - not just for possible name conflicts but -for extensions that might be of interest. - -Each specification that defines how to serialize a CloudEvent will -define how extension attributes will appear. - -Here is an example that illustrates the need for additional attributes. -In many IoT and enterprise use cases, an event could be used in -a serverless application that performs actions across multiple types of events. -To support such use cases, the event producer will need to add additional -identity attributes to the "context attributes" which the event consumers can -use to correlate this event with the other events. If such identity attributes -happen to be part of the event "data", the event producer SHOULD also add -the identity attributes to the "context attributes" so that -event consumers can easily access this information without needing to decode -and examine the event data. Such identity attributes can also be used to -help intermediate gateways determine how to route the events. +extension attributes. Each definition of an extensions SHOULD fully define all +aspects of the attribute - e.g. its name, semantic meaning and possible values +or even to indicate that it places no restrictions on its values. New extension +definitions SHOULD use a name that is descriptive enough to reduce the chances +of name collisions with other extensions. In particular, extension authors +SHOULD check the [documented extensions](documented-extensions.md) document for +the set of known extensions - not just for possible name conflicts but for +extensions that might be of interest. + +Each specification that defines how to serialize a CloudEvent will define how +extension attributes will appear. + +Here is an example that illustrates the need for additional attributes. In many +IoT and enterprise use cases, an event could be used in a serverless application +that performs actions across multiple types of events. To support such use +cases, the event producer will need to add additional identity attributes to the +"context attributes" which the event consumers can use to correlate this event +with the other events. If such identity attributes happen to be part of the +event "data", the event producer SHOULD also add the identity attributes to the +"context attributes" so that event consumers can easily access this information +without needing to decode and examine the event data. Such identity attributes +can also be used to help intermediate gateways determine how to route the +events. ## Data Attribute @@ -290,44 +304,48 @@ information about the occurrence. When present, this information will be encapsulated within the `data` attribute. ### data -* Type: `Any` -* Description: The event payload. The payload depends on the `type` and - the `schemaurl`. It is encoded into a media format - which is specified by the `datacontenttype` attribute (e.g. application/json). -* Constraints: - * OPTIONAL + +- Type: `Any` +- Description: The event payload. The payload depends on the `type` and the + `schemaurl`. It is encoded into a media format which is specified by the + `datacontenttype` attribute (e.g. application/json). +- Constraints: + - OPTIONAL # Privacy and Security + Interoperability is the primary driver behind this specification, enabling such -behavior requires some information to be made available *in the clear* resulting +behavior requires some information to be made available _in the clear_ resulting in the potential for information leakage. -Consider the following to prevent inadvertent leakage especially when leveraging +Consider the following to prevent inadvertent leakage especially when leveraging 3rd party platforms and communication networks: -* Context Attributes +- Context Attributes - Sensitive information SHOULD NOT be carried or represented in context attributes. - - CloudEvent producers, consumers, and intermediaries MAY introspect and log context + Sensitive information SHOULD NOT be carried or represented in context attributes. - -* Data + + CloudEvent producers, consumers, and intermediaries MAY introspect and log + context attributes. + +- Data Domain specific [data](#data) SHOULD be encrypted to restrict visibility to - trusted parties. The mechanism employed for such encryption is an agreement between - producers and consumers and thus outside the scope of this specification. - -* Transport Bindings + trusted parties. The mechanism employed for such encryption is an agreement + between producers and consumers and thus outside the scope of this + specification. + +- Transport Bindings - Transport level security SHOULD be employed to ensure the trusted and - secure exchange of CloudEvents. + Transport level security SHOULD be employed to ensure the trusted and secure + exchange of CloudEvents. # Example The following example shows a CloudEvent serialized as JSON: -``` JSON +```JSON { "specversion" : "0.2", "type" : "com.github.pull.create",