Editor’s Draft, 2022-12-27

More details about this document
This version
Latest version
Aaron Coburn
MIT License
Document Status
Editor’s Draft
In Reply To
Solid Origin
Solid Notifications Protocol
Notifications Panel Charter
Unique Identifier
W3C Solid Community Group


The Solid Notifications Protocol defines a set of interaction patterns for agents to establish subscriptions to resources.

This specification defines a subscription type that applies these patterns to the WebSocket Web API.

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.


This section is non-normative.

The Solid Notifications Protocol describes a general pattern by which agents can be notified when a Solid Resource changes. In the context of a Web Browser, the WebSocket API provides a convenient mechanism for a Solid Storage to alert a subscribing client of these changes.

This document describes a Solid Notifications subscription type that makes use of the WebSocket Web API.

This specification is for:


This section is non-normative.

This document uses terminology from the Solid Notification Protocol, including subscription API, gateway API. This document also uses terms from The OAuth 2.0 Authorization Framework specification, including resource server, authorization server, access token, and client, as well as terms from the WebSub specification, including topic.


This section is non-normative.

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

Solid WebSocketChannel2023 Flow


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.

WebSocketChannel2023 Type

This specification defines the WebSocketChannel2023 type for use with Solid Notifications Protocol's subscriptions that use the WebSocket Web API. The URI of the subscription type is http://www.w3.org/ns/solid/notification#WebSocketChannel2023.

An WebSocketChannel2023 API MUST conform to the Solid Notifications Protocol. [SOLID-NOTIFICATIONS]

A client establishes a subscription using the WebSocketChannel2023 type by sending an authorized subscription request to the subscription resource based on Solid Notifications Protocol discovery.

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

Subscription Example

This section is non-normative.

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

Example: Requesting an WebSocket subscription URL from the subscription resource.

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

  "@context": ["https://www.w3.org/ns/solid/notification/v1"],
  "type": "WebSocketChannel2023",
  "topic": "https://storage.example/resource",
  "state": "opaque-state",
  "endAt": "2022-12-27T12:37:15Z",
  "rate": "PT10s"
POST request including type and topic targeting the subscription resource.

A successful response will contain a URL to the subscription API (receiveFrom) that can be used directly with a JavaScript client.

Example: Response from the subscription resource including the WebSocket subscription URL.

Content-Type: application/ld+json

  "@context": "https://www.w3.org/ns/solid/notification/v1",
  "type": "WebSocketChannel2023",
  "topic": "https://storage.example/data/resource",
  "receiveFrom": "wss://websocket.example/?auth=Ys3KiUq"
Response to the POST request including type and receiveFrom.

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

Example: Establishing a new WebSocket connection.

const ws = new WebSocket("wss://websocket.example/?auth=Ys3KiUq", "http://www.w3.org/ns/solid/notifications#WebSocketChannel2023");
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 is established.

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

Authentication and Authorization

As described by the Solid Notifications Protocol section on Authorization, the WebSocket subscription API requires authorization and follows the guidance of the Solid Protocol sections on Authentication and Authorization [SOLID-PROTOCOL].


Normative References

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
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
Solid Notifications. Aaron Coburn; Sarven Capadisli. W3C Solid Community Group. Version 0.1.0. URL: https://solidproject.org/TR/notifications-protocol
SOLID-OIDC. Aaron Coburn; elf Pavlik; Dmitri Zagidulin. W3C Solid Community Group. Version 0.1.0. URL: https://solidproject.org/TR/oidc
Solid Protocol. Sarven Capadisli; Tim Berners-Lee; Ruben Verborgh; Kjetil Kjernsmo. W3C Solid Community Group. Version 0.9.0. URL: https://solidproject.org/TR/protocol