Solid Notifications Protocol

Editor’s Draft, 2021-10-26

This version
https://solid.github.io/notifications/protocol
Latest version
https://solid.github.io/notifications/protocol
Created
Published
Modified
Repository
GitHub
Issues
Derived From
Language
English
License
MIT License
Document Status
Editor’s Draft
In Reply To
Solid Origin
Notifications Panel Charter
Policy
Rule
Offer
Unique Identifier
https://solid.github.io/notifications/protocol#document-policy-offer
Target
https://solid.github.io/notifications/protocol
Permission
Assigner
W3C Solid Community Group
Action

Abstract

Solid Notifications Protocol.

Status of This Document

This section describes the status of this document at the time of its publication.

This document was published by the Solid Community Group as an Editor’s Draft. The sections that have been incorporated have been reviewed following the Solid process. However, the information in this document is still subject to change. You are invited to contribute any feedback, comments, or questions you might have.

Publication as an Editor’s Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

Introduction

This section is non-normative.

Much of the Solid Protocol is built on a RESTful API. This allows Solid to make use of well-understood interactions with resources on the Web, and this satisfies many use cases for client applications in the Solid ecosystem. However, for interactive client applications with multiple participants, chat-apps being just one such example, a RESTful API is too limited, as clients need to rely on polling in order to discover changes in the underlying data.

A notification API for Solid would complement the core RESTful API so that clients can listen for updates to particular resources. In addition, a notification-based mechanism may reduce latency and load on a Pod server.

One challenge with (near) real-time notifications on the Web involves the diversity of technologies available. WebSockets and EventSource APIs are two options that are widely supported by browsers; ReadableStreams are becoming more widely supported. Furthermore, there are other, more asynchronous models that are relevant in certain cases: WebHooks, WebSub and Linked Data Notifications are three examples. A major goal of the model described in this document is to make it possible for client applications to navigate the diversity of these technologies while also being open to new notification mechanisms as they emerge.

Finally, a critically important part of this model is security. Any notification-based API not only needs the same level of security that is found in the RESTful API but also the authorization mechanism needs to be consistent across these endpoints.

This specification is for:

Use Cases

This section is non-normative.

Immediate notification of data changes
For many clients, it is important to know when a resource state changes. This includes collaborative editing apps, chat apps or any client that expects the underlying data to change frequently based on updates made by others.
Change frequency
Sometimes a client doesn't need to be alerted for every change. If a client only needs infrequent updates, for example, every 5 minutes, it should be possible to avoid floods of data that might otherwise place a higher burden on the client application. Ideally, a client should be able to define what that aggregation window would be: for some clients, 10 seconds might be appropriate; for others, several minutes might be more appropriate.
Filtered notifications
Certain categories of notifications may be more or less interesting to clients. For example, a client may not care about UPDATE operations or may only care about notifications for resources of certain types.
Time-bound subscriptions
Occasionally, a client only needs a subscription to be in effect for a limited period of time. While a client may easily close a WebSocket itself, subscriptions for other, more asynchronous forms of notifications, such as LDN alerts or WebHook operations, may be more difficult to terminate.
Avoid missing updates
For WebSockets and protocols that rely on an active, live connection to a notification server, the notification protocol needs to make sure that clients do not miss notifications in the event of a dropped connection.
Protocol negotiation
a given Solid Notification server may support certain technologies (e.g. WebSockets and LDN) but not others (e.g. EventSource and WebSub). Likewise, a client may not support the same set of protocols that are implemented by a server. As such, there needs to be a mechanism for clients and servers to agree on a mutually supported protocol. In addition to simply determining the set of protocols that work for client and server, there may be particular features (e.g. notification aggregation, notification filtering) that are required for the client. This could be used to further filter the protocol selection.
Security
A client should not be able to subscribe to resources to which it does not have read access.

Terminology

This section is non-normative.

This document uses terminology from the Solid Protocol specification, including data pod. This document also uses terms from The OAuth 2.0 Authorization Framework specification, including resource server, authorization server and client, as well as terms from the WebSub specification, including topic.

This specification defines the following terms. These terms are referenced throughout this specification.

Solid Server Metadata Resource
An RDF document [RDF11-CONCEPTS] that includes metadata about the Solid server.
Notification Gateway API
An HTTP endpoint at which a client can negotiate an acceptable notification subscription location [RFC7231].
Notification Subscription API
An HTTP endpoint at which a client can initiate a subscription to notification events for a particular set of resources [RFC7231].

Overview

The following diagram shows the high level interactions involved in this high-level flow. How a client retrieves an access token for step 5 is outside the scope of this document.

Solid Notifications Flow

Conformance

All assertions, diagrams, examples, and notes are non-normative, as are all sections explicitly marked non-normative. Everything else is normative.

The key words “MUST” and “MUST NOT” are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Protocol

The notification protocol involves the Discovery of the Notification Gateway service to negotiate subscription channels and the Notification Subscription endpoint to listen to updates from particular resources.

A server MUST support JSON-LD in these interactions.

Discovery

For any resource in a data pod, a client can discover the associated notification gateway API by fetching the Solid Server Metadata Resource. This resource can be retrieved by appending /.well-known/solid to the base URL of the data pod.

Example: Retrieve Solid Server Metadata Resource.

GET /.well-known/solid
HTTP GET request targeting .well-known/solid

The use of a well-known resource is based on suggestions to avoid too many HTTP Link headers, but that is not a settled issue.

The server MUST be capable of serializing the Solid Server Metadata Resource as Turtle or JSON-LD [TURTLE] [JSON-LD11].

A sample representation of this resource might include the following:

Example: Representation of Solid Server Metadata Resource.

Content-Type: application/ld+json

{
  "@context": ["https://www.w3.org/ns/solid/notification/v1"],
  "notification_endpoint": "https://gateway.example",
  ...
}
JSON-LD serialization of a Solid Server Metadata Resource

The Notifications Panel should define a particular JSON-LD @context for use with JSON-LD serializations.

Notification Gateway

Once the location of a notification gateway is discovered, an application will negotiate for a particular notification channel, based on acceptable features and protocols.

The type array advertises which subscription channels a client is able to understand. The features array advertises which notification features are required by the client. The server selects one of the proposed subscription types and responds with a JSON-LD document that includes the selected protocol, the endpoint for negotiating a subscription and the supported features offered by that protocol.

Authentication is not required at this endpoint.

A sample interaction is described below. The type and feature names are included as examples.

Example: Requesting subscription types and features from the Notification Gateway.

POST /gateway
Content-Type: application/ld+json

{
  "@context": ["https://www.w3.org/ns/solid/notification/v1"],
  "type": ["WebSocketSubscription2021", "WebHookSubscription2021"],
  "features": ["state", "rate"]
}
POST request including type and features targeting the Notifications Gateway.

Example: Response from the Notification Gateway including a type of subscription endpoint with available features.

HTTP/2
Content-Type: application/ld+json

{
  "@context": ["https://www.w3.org/ns/solid/notification/v1"],
  "type": "WebSocketSubscription2021",
  "endpoint": "https://websocket.example/subscription",
  "features": ["state", "rate", "expiration", "feature1", "feature2"]
}
Response to the POST request including type, endpoint and features.

Note: Features Negotiation May Not Be Needed

The features array may not be needed as part of this negotiation.

Notification Subscription

The details of subscribing to a particular endpoint depend on the technology used, but all will follow a similar pattern. For WebSockets, this involves sending an authenticated subscription request to the endpoint retrieved from the gateway service.

The client sends a JSON-LD payload to this endpoint via POST. The only required fields in this interaction are type and topic. The type field MUST contain the type of subscription being requested. The topic field MUST contain the URL of the resource a client wishes to subscribe to changes.

All other fields are defined by the particular subscription type. Some common features are described in the Features section of this document.

An example POST request using a DPoP bound access token is below:

Example: Requesting a WebSocket subscription endpoint from the Notification Subscription.

POST /subscription
Authorization: DPoP <token>
DPoP: <proof>
Content-Type: application/ld+json

{
  "@context": ["https://www.w3.org/ns/solid/notification/v1"],
  "type": "WebSocketSubscription2021",
  "topic": "https://pod.example/resource",
  "state": "opaque-state",
  "expiration": "2021-09-21T12:37:15Z",
  "rate": "PT10s"
}
POST request including type and topic targeting the Notification Subscription.

A successful response will contain a URL to the subscription endpoint that can be used directly with a JavaScript client.

Example: Response from the Notification Subscription including the WebSocket subscription endpoint.

HTTP/2
Content-Type: application/ld+json

{
  "@context": "https://www.w3.org/ns/solid/notification/v1",
  "type": "WebSocketSubscription2021",
  "endpoint": "wss://websocket.example/?auth=Ys3KiUq"
}
Response to the POST request including type and endpoint.

In JavaScript, a client can use the data in the response to establish a connection to the WebSocket endpoint.

Example: Establishing a new WebSocket connection to a subscription endpoint.

const ws = new WebSocket(endpoint, type)
JavaScript code to establish a new WebSocket connection

A client will define how to handle events, especially the onclose and onmessage events.

Example: Handling WebSocket events after the connection.

ws.onclose(evt => reconnect(evt));
ws.onmessage(evt => console.log("Message received: ", evt))
JavaScript code to handle onclose and onmessage events

Authentication and Authorization

The Subscription API requires authorization. This document does not define the specific technology used to authorize requests; rather, it defers to the Solid Protocol sections on Authentication and Authorization [SOLID-PROTOCOL]. It is out of scope for this document to describe how a client fetches an authorization token. Solid-OIDC is one example of an authentication mechanism that could be used with Solid Notifications [SOLID-OIDC].

Resource-based Access controls MUST be enforced for every subscription. A client MUST be permitted to read the resource to which it subscribes.

Subscription Types

This document defines four initial subscription types:

Note: Subscription Type Naming Convention

The naming convention used here follows a pattern used by the Verifiable Credentials community, making it possible to distinguish between different versions of these subscription types. Other naming conventions can achieve the same end.

The requirements for new subscription types is explained in the Subscription Types Extension section.

WebSocketSubscription2021

The WebSocketSubscription2021 type defines the following properties:

endpoint
The endpoint property is used in the body of the subscription response. The value of this property MUST be a URI, using the wss scheme. A JavaScript client would use the entire value as input to the WebSocket constructor.

EventSourceSubscription2021

The EventSourceSubscription2021 type defines the following properties:

endpoint
The endpoint property is used in the body of the subscription response. The value of this property MUST be a URI, using the https scheme. A JavaScript client would use the entire value as input to the EventSource constructor.

linkeddatanotificationsSubscription2021

The linkeddatanotificationsSubscription2021 type defines the following properties:

endpoint
The endpoint property is used in the body of the subscription request. The value of this property MUST be a URI, using the https scheme. The inbox URI MUST conform to the receiver portion of the Linked Data Notifications specification.
webid
The webid property is used in the body of the subscription response. The value of this property MUST be an HTTPS URI conforming to the WebID draft specification. All LDN notifications will be sent to the defined inbox using the agent identity specified by this WebID. A resource owner should ensure that the agent identified in this property is permitted to send authenticated HTTP requests to the defined inbox.

WebHookSubscription2021

The WebHookSubscription2021 type defines the following properties:

target
The target property is used in the body of the subscription request. The value of this property MUST be a URI, using the https scheme.

Notification Features

Features allow clients to customize the details of a subscription. Some features are specific to particular subscription types while others may be used across all types. These shared features are listed as an initial baseline, though not all subscription types are required to implement these. Individual subscription types may define type-specific features. The list of common, shared features is not intended to be exhaustive.

The requirements for new notification features is explained in the Notification Features Extension section.

expiration
An ISO 8601 datetime value indicating a proposed expiration point for a subscription. A server may choose another value.
state
An opaque value representing the last known state of a resource. If the resource state is known to have changed when the client establishes a subscription, an initial notification must be sent to the client. This value should correspond to a resource's ETag header value.
rate
An ISO 8601 duration value indicating the minimum amount of time to elapse between notifications sent to the client
accept
A MIME-Type value that indicates the desired serialization of the notification. For instance, text/turtle may be acceptable.

Notification Data Model

The content of a Solid Notification is defined in terms of a Activity Streams 2.0 [ACTIVITYSTREAMS-CORE]. As such, JSON-LD 1.0 is a required baseline serialization format, though other formats are not prohibited [JSON-LD]. JSON-LD version 1.1 is recommended when using JSON-LD serializations [JSON-LD11].

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://www.w3.org/ns/solid/notification/v1"
  ],
  "id":"urn:uuid:<uuid>",
  "type": [
    "Update"
  ],
  "actor": [
    "<WebID>"
  ],
  "object": {
    "id":"https://example.org/<user>/some-container/",
     "type": [
      "http://www.w3.org/ns/ldp#BasicContainer",
      "http://www.w3.org/ns/ldp#Resource",
      "http://example.com/SomeType"
    ]
  },
  "state": "1234-5678-90ab-cdef-12345678",
  "published":"2021-08-05T01:01:49.550044Z"
}

Note: Solid Notification JSON-LD Context

The Solid JSON-LD context resource does not currently exist. An implementation may choose to augment the context definition.

The content of these serialized notifications may be extended, but the example here provides a minimal baseline that clients can expect.

Extensions

Extensions incorporate additional features beyond what is defined in this specification. Extensions MUST NOT contradict nor cause the non-conformance of functionality defined in this specification.

Subscription Types Extension

This section is non-normative.

Notification Features Extension

This section is non-normative.

Considerations

This section details security, privacy, accessibility and internationalization considerations.

Some of the normative references with this specification point to documents with a Living Standard or Draft status, meaning their contents can still change over time. It is advised to monitor these documents, as such changes might have implications.

Security Considerations

This section is non-normative.

Privacy Considerations

This section is non-normative.

Accessibility Considerations

This section is non-normative.

Internationalization Considerations

This section is non-normative.

Security and Privacy Review

This section is non-normative.

These questions provide an overview of security and privacy considerations for this specification as guided by [SECURITY-PRIVACY-QUESTIONNAIRE].

What information might this feature expose to Web sites or other parties, and for what purposes is that exposure necessary?
..
Do features in your specification expose the minimum amount of information necessary to enable their intended uses?
..
How do the features in your specification deal with personal information, personally-identifiable information (PII), or information derived from them?
..
How do the features in your specification deal with sensitive information?
..
Do the features in your specification introduce new state for an origin that persists across browsing sessions?
..
Do the features in your specification expose information about the underlying platform to origins?
..
Does this specification allow an origin to send data to the underlying platform?
..
Do features in this specification allow an origin access to sensors on a user’s device
..
What data do the features in this specification expose to an origin? Please also document what data is identical to data exposed by other features, in the same or different contexts.
..
Do features in this specification enable new script execution/loading mechanisms?
..
Do features in this specification allow an origin to access other devices?
..
Do features in this specification allow an origin some measure of control over a user agent’s native UI?
..
What temporary identifiers do the features in this specification create or expose to the web?
..
How does this specification distinguish between behaviour in first-party and third-party contexts?
..
How do the features in this specification work in the context of a browser’s Private Browsing or Incognito mode?
..
Does this specification have both "Security Considerations" and "Privacy Considerations" sections?
..
Do features in your specification enable origins to downgrade default security protections?
..

References

Normative References

[ACTIVITYSTREAMS-CORE]
Activity Streams 2.0. James Snell; Evan Prodromou. W3C. 23 May 2017. W3C Recommendation. URL: https://www.w3.org/TR/activitystreams-core/
[JSON-LD]
JSON-LD 1.0. Manu Sporny; Gregg Kellogg; Markus Lanthaler. W3C. 3 November 2020. W3C Recommendation. URL: https://www.w3.org/TR/json-ld/
[JSON-LD11]
JSON-LD 1.1. Gregg Kellogg; Pierre-Antoine Champin; Dave Longley. W3C. 16 July 2020. W3C Recommendation. URL: https://www.w3.org/TR/json-ld11/
[LDN]
Linked Data Notifications. Sarven Capadisli; Amy Guy. W3C. 2 May 2017. W3C Recommendation. URL: https://www.w3.org/TR/ldn/
[OAUTH-POP-KEY-DISTRIBUTION]
OAuth 2.0 Proof-of-Possession: Authorization Server to Client Key Distribution. J. Bradley; P. Hunt; M. Jones; H. Tschofenig. IETF. 5 March 2015. Internet Draft (work in progress). URL: https://datatracker.ietf.org/doc/draft-ietf-oauth-pop-key-distribution/
[RDF-SCHEMA]
RDF Schema 1.1. Dan Brickley; Ramanathan Guha. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/rdf-schema/
[RDF11-CONCEPTS]
RDF 1.1 Concepts and Abstract Syntax. Richard Cyganiak; David Wood; Markus Lanthaler. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/rdf11-concepts/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://datatracker.ietf.org/doc/html/rfc3986
[RFC6454]
The Web Origin Concept. A. Barth. IETF. December 2011. Proposed Standard. URL: https://datatracker.ietf.org/doc/html/rfc6454
[RFC6749]
The OAuth 2.0 Authorization Framework. D. Hardt, Ed.. IETF. October 2012. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6749
[RFC7231]
Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7231.html
[RFC8274]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc8174
[RFC8288]
Web Linking. M. Nottingham. IETF. October 2017. Proposed Standard. URL: https://httpwg.org/specs/rfc8288.html
[SOLID-OIDC]
SOLID-OIDC. Aaron Coburn; elf Pavlik; Dmitri Zagidulin. W3C Solid Community Group. W3C Editor's Draft. URL: https://solid.github.io/solid-oidc/
[SOLID-PROTOCOL]
Solid Protocol. Sarven Capadisli; Tim Berners-Lee; Ruben Verborgh; Kjetil Kjernsmo; Justin Bingham; Dmitri Zagidulin. W3C Solid Community Group. W3C Editor’s Draft. URL: https://solidproject.org/TR/protocol
[TURTLE]
RDF 1.1 Turtle. Eric Prud'hommeaux; Gavin Carothers. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/turtle/
[WEBSOCKETS]
The WebSocket API. Ian Hickson. W3C. 28 January 2021. W3C Note. URL: https://www.w3.org/TR/websockets/
[WEBSUB]
WebSub. Julien Genestoux; Aaron Parecki. W3C. 23 January 2018. W3C Recommendation. URL: https://www.w3.org/TR/websub/

Informative References

[SECURITY-PRIVACY-QUESTIONNAIRE]
Self-Review Questionnaire: Security and Privacy. Theresa O'Connor; Peter Snyder. W3C. 23 March 2021. W3C Note. URL: https://www.w3.org/TR/security-privacy-questionnaire/
[WEBARCH]
Architecture of the World Wide Web, Volume One. Ian Jacobs; Norman Walsh. W3C. 15 December 2004. W3C Recommendation. URL: https://www.w3.org/TR/webarch/