diff --git a/directory.td.json b/directory.td.json
index cbb30b21..657a02d1 100644
--- a/directory.td.json
+++ b/directory.td.json
@@ -393,19 +393,16 @@
"description": "TD registration events",
"uriVariables": {
"type": {
- "title": "Event type",
+ "title": "Event type(s)",
+ "description": "Multiple types passed as type={type} pairs for SSE",
"type": "string",
"enum": [
- "created_td",
- "updated_td",
- "deleted_td"
+ "create",
+ "update",
+ "delete"
]
},
- "td_id": {
- "title": "Identifier of TD in directory",
- "type": "string"
- },
- "include_changes": {
+ "full": {
"title": "Include TD changes inside event data",
"type": "boolean"
}
@@ -413,60 +410,18 @@
"forms": [
{
"op": "subscribeevent",
- "href": "/events{?type,td_id,include_changes}",
+ "href": "/events{?type,full}",
"subprotocol": "sse",
"contentType": "text/event-stream",
"htv:headers": [
{
- "description": "ID of the last event for reconnection",
- "htv:fieldName": "Last-Event-ID",
- "htv:fieldValue": ""
+ "description": "ID of the last event provided by reconnecting clients",
+ "htv:fieldName": "Last-Event-ID"
}
],
"data": {
- "oneOf": [
- {
- "type": "object",
- "description": "The schema of event data",
- "properties": {
- "td_id": {
- "type": "string",
- "format": "iri-reference",
- "description": "Identifier of TD in directory"
- }
- }
- },
- {
- "type": "object",
- "description": "The schema of create event data including the created TD",
- "properties": {
- "td_id": {
- "type": "string",
- "format": "iri-reference",
- "description": "Identifier of TD in directory"
- },
- "td": {
- "type": "object",
- "description": "The created TD in a create event"
- }
- }
- },
- {
- "type": "object",
- "description": "The schema of the update event data including the updates to TD",
- "properties": {
- "td_id": {
- "type": "string",
- "format": "iri-reference",
- "description": "Identifier of TD in directory"
- },
- "td_updates": {
- "type": "object",
- "description": "The partial TD composed of modified TD parts in an update event"
- }
- }
- }
- ]
+ "description": "Partial or complete TD",
+ "type": "object"
},
"scopes": "notifications"
}
diff --git a/index.html b/index.html
index d6e5aa34..6a6da6b2 100644
--- a/index.html
+++ b/index.html
@@ -1291,11 +1291,7 @@
Management
Notification
-
- The query and payload specification are subject to change for
- simplification and consistency with other API features
- (e.g. Anonymous TD, partial TD format [[RFC7396]]).
-
+
The Notification API is to notify clients about the changes
to Thing Descriptions maintained within the directory.
@@ -1312,17 +1308,19 @@
Notification
Event Types
- The server MUST produce events for creation, update, and deletion of
- Thing Descriptions represented by `created_td`, `updated_td`, `deleted_td`
- keywords respectively.
+ The server MUST produce events attributed to the lifecycle of
+ the Thing Descriptions within the directory using
+ `create`, `update`, and `delete` event types.
Event Filtering
- The API supports server-side filtering of events to reduce resource consumption
+ The API enables server-side filtering of events to reduce resource consumption
by delivering only the events required by clients.
- The filtering is based on query parameters passed to the server at
+ Client libraries may offer additional filtering capabilities on
+ the client-side.
+ The server-side filtering is based on query parameters passed to the server at
connection time. The filtering behavior is described below:
@@ -1330,29 +1328,31 @@
Notification
The server MUST support event filtering based on the
event types passed as one or more `type` query parameters.
- For example, in response to query `?type=created_td&type=deleted_td`,
- the server must only deliver events of types `created_td` and `deleted_td`.
- At the absence of any `type` query parameter, the server must deliver all
+ For example, in response to query `?type=create&type=delete`,
+ the server will only deliver events of types `create` and `delete`.
+ At the absence of any `type` query parameter, the server will deliver all
types of events.
-
-
- The server MUST support event filtering based on the
- Thing Description identifier passed as one or more `td_id` query parameters.
-
- For example, the query `?type=updated_td&td_id=urn:example:1234` must
- result in `updated_td` events for the TD identified with `urn:example:1234`.
-
The server MAY support event filtering based on the
search expressions passed as one of `jsonpath`, `xpath`,
or `sparql` query parameters.
+ This is to detect changes on particular TDs or attributes and does not not affect
+ the event's data object.
+
+ For example, the JSONPath expression `$.properties`
+ will reduce the number of events to TDs that change their `properties` attributes.
+ The resulting events may be for created or deleted TDs with the `properties` attribute
+ or updates to `properties` attribute of existing TDs.
+
If the server does not support a given search query parameter, it
MUST reject the request with 501 (Not Implemented) status.
+ This is to inform the clients about the missing feature at the connection
+ time and prevent unexpected network traffic and events.
@@ -1361,34 +1361,100 @@
Notification
The event data MUST contain the JSON serialization of the event object.
- The event data object is defined by the following rules:
+ The event data object is a Partial TD or the whole TD object
+ depending on the request:
The event data object MUST at least include the identifier of the
- TD created, updated, or deleted at that event as value of `td_id` field.
+ TD created, updated, or deleted at that event in Partial TD form.
+
+
+
+
+
+ When `full` query parameter is set to `true` and the event has `create` type,
+ the server MAY return the whole TD object as event data.
+
+
+
-
- When `include_changes` query parameter is set to `true`, the create
- event data object MAY include the created TD as the value of `created_td`
- field.
+
+ When `full` query parameter is set to `true` and the event has `update` type,
+ the server MAY inform the client about the updated parts following the
+ JSON Merge Patch [[RFC7396]] format.
+
+
+ An `update` event data that is based on JSON Merge Patch [[RFC7396]]
+ MUST always include the identifier of the TD regardless of whether it
+ is changed.
+
+
+ The following example shows the event triggered on update of the TD from [[[#example-create-event-full]]]:
+
+
-
- When `include_changes` query parameter is set to `true`, the update
- event data object MAY include the updated parts of the TD in
- Partial TD form as the value of `td_updates` field.
+
+ The `full` query parameter MUST be ignored for `delete` events.
+ In other words, when the `full` query parameter is set to `true` and
+ the event has `delete` type, the server must only provide the identifier
+ in event data.
- When a server which does not support the inclusion of changes inside event
- data object is requested with a `include_changes` query parameter, it MUST
+ When a server which does not support the `full` query parameter
+ is requested with such query parameter, it MUST
reject the request with 501 (Not Implemented) status.
+ This is to inform the clients about the lack of such functionality at the
+ connection time to avoid runtime exceptions caused by missing
+ event data attributes.