Skip to content
New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Cloud Events Message Format #330

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Cloud Events Message Format #330

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5a11928
cloud events payload - initial draft
mlagally Nov 30, 2022
7223c01
Update index.html
mlagally Feb 16, 2023
b198791
Merge branch 'main' into webook-payload-cloudevents
mlagally Feb 16, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
160 changes: 148 additions & 12 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2917,18 +2917,6 @@ <h2>Identifier</h2>
</section>
</section>

<section id="sec-http-webhook-profile-message-format">
<h3>Message Format</h3>
<p><span class="rfc2119-assertion" id="http-webhook-profile-message-format-1">
Event notification messages MUST comply with the following data schema.</span>
</p>

<p class="ednote">
<!-- TODO -->
TODO: Describe data and dataResponse schemas.
</p>
</section>

<section id="http-webhook-profile-protocol-binding">
<h2>Protocol Binding</h2>
<p>
Expand Down Expand Up @@ -3251,6 +3239,154 @@ <h4>Event Connections</h4>
</section>
</section>



<section id="sec-http-webhook-profile-message-format" class="informative">
<h3>Cloud Events Message Format</h3>
<p>
This section defines a JSON object format for events, which provides interoperability with cloud systems
that use the <a href="https://cloudevents.io/">cloud events specification</a> with the
<a href="#sec-http-webhook-profile">HTTP Webhook profile</a>
<p>
This message format is one way of using the WebHook profile in a well defined way
that is supported by several cloud systems.
</p>
<p>
Using other message formats is not prohibited by this section - They should be used for deployments,
where consumers use a different event payload.
</p>

<section id="http-webhook-profile-identifier">
<h2>Identifier</h2>
<p><span class="rfc2119-assertion" id="http-webhook-profile-1">
In order to denote that a given
<a href="https://www.w3.org/TR/wot-architecture/#dfn-thing">Web Thing</a>
conforms to the HTTP Webhook Profile and uses Cloud Events,
its Thing Description MUST have a
<a href="https://w3c.github.io/wot-thing-description/#thing">
<code>profile</code></a> member containing both profile identifiers:
<code>https://www.w3.org/2022/wot/profile/http-webhook/v1</code>
and <code>https://www.w3.org/2022/wot/profile/http-cloudevent/v1</code>
.</span>
</p>
<section class="note">
<p>Note that the <code>profile</code> member is an array that may contain multiple
profile entries, which indicates that a Web Thing conforms to all of the profiles in that array.</p>
</section>
</section>



<p class="rfc2119-assertion" id="http-webhook-profile-message-format-1">
If the consumer is providing an endpoint for cloud events,
event notification messages SHOULD comply with the following data schema.
</p>

<p>
The format is aligned with the <a href="https://cloudevents.io/">cloud events specification</a>
to ensure interoperability with cloud systems that adopt that specification.
</p>
<p>
An event message contains a set of metadata properties and an optional data payload.
The metadata fields allow to determine the type and source of the event as well as
a timestamp indicating when the event occured and an optional data payload.
</p>
<p>
<span class="rfc2119-assertion" id="profile-json-event-payload">
The following constraints MUST be
applied to the event payload:
</span>
</p>
<table class="def">
<thead>
<tr>
<th>keyword</th>
<th>type</th>
<th>type constraints</th>
<th>value constraints</th>
</tr>
</thead>
<tbody>
<tr>
<td>specversion</td>
<td>string</td>
<td>mandatory, non-empty</td>
<td>The <code>specversion</code> MUST have the value "1.0"</td>
</tr>
<tr>
<td>id</td>
<td>string</td>
<td>mandatory, non-empty</td>
<td>For each distinct event the combination of <code>source</code> + <code>id</code> MUST be unique.
A WebThing MAY resend the same event with the same <code>id</code>.
If an event is resent with the same <code>id</code>, a consumer SHOULD treat it as
duplicate.</td>
</tr>
<tr>
<td>source</td>
<td>uri</td>
<td>mandatory, non-empty</td>
<td>The combination of <code>source</code> + <code>id</code> MUST be unique for each distinct event.
The source MUST be set to the <code>baseURI</code> of the WebThing.</td>
</tr>
<tr>
<td>subject</td>
<td>string</td>
<td>optional</td>
<td>When this field is used, it MUST be set to the <code>title</code> of the event or property
affordance.</td>
</tr>
<tr>
<td>type</td>
<td>string</td>
<td>mandatory, non-empty</td>
<td>For event affordances the source MUST be set to the string "/events/<code>eventName</code>" of the
event affordance.</br>
For property affordances the source MUST be set to the string "/properties/<code>propertyName</code>" of
the property affordance.
</td>
</tr>
<tr>
<td>time</td>
<td>string</td>
<td>optional, compliant with [[RFC3339]]</td>
<td>time when the event occurred. If the WebThing does not have a clock, it MUST use the same
algorithm on all event affordances to determine the value of this field.
</tr>
<tr>
<td>datacontenttype</td>
<td>string</td>
<td>optional, [[RFC2046]] compliant MIME type, when set the value MUST be "<code>application/json</code>"
</td>
<td>If a WebThing contains a <code>data member</code>, this field MUST be present.</td>
</tr>
<tr>
<td>data</td>
<td>string</td>
<td>optional</td>
<td>JSON encoded <code>data</code> object of the event affordance.</td>
</tr>
</tbody>
</table>
<span class="rfc2119-assertion" id="profile-event-payload-size">
The size of an event object MUST NOT exceed 64KB, to ensure interoperability with all kinds of consumers.
</span>
<p class="rfc2119-assertion" id="http-webhook-profile-message-format-2">
For each notification message, the Web Thing MUST set the <code>event</code> field to the
name of the <code>EventAffordance</code>.</span>
</p>
<p><span class="rfc2119-assertion" id="http-webhook-profile-protocol-message-format-3">
The event <code>data</code> MUST follow the data schema specified in the
<code>EventAffordance</code> and MUST be serialized in JSON.</span>
</p>
<p><span class="rfc2119-assertion" id="http-webhook-profile-protocol-binding-message-format-4">
The <code>id</code> field MUST be set to a unique identifier for
the event.</span>
</p>
</section>



<section id="privacy-considerations">
<h4>Privacy Considerations</h4>
<p><span class="rfc2119-assertion" id="privacy-considerations-1">
Expand Down