Solid Notifications Protocol

Editor’s Draft,

More details about this document
This version
https://solid.github.io/notifications/protocol
Latest version
https://solid.github.io/notifications/protocol
Latest published version
https://solidproject.org/TR/notifications-protocol
Editors
Sarven Capadisli
Authors
Aaron Coburn
Sarven Capadisli
elf Pavlik
Rahul Gupta
Created
Published
Modified
Repository
GitHub
Issues
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

This specification defines a Linked Data-based protocol for sending notification to client application upon updates to resources in the Solid ecosystem while respecting resource-based access controls and privacy.

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.

The Solid Notification Protocol defines an extensible, HTTP-based framework by which client applications can receive notifications for HTTP resource changes.

A goal of the protocol defined by this specification is to enable interaction patterns both for cases where an HTTP client maintains an open connection to receive notifications as well as for cases where an HTTP client makes a request for notifications and then disconnects.

This specification is for:

  • Server developers that want to enable clients to listen for updates to particular resources.
  • Application developers who want to implement a client to listen for updates to particular resources.

In addition to this specification, readers might find the Use Cases and Requirements for Notifications Protocol [NOTIFICATIONS-UCR] document useful.

Overview

This section is non-normative.

The Solid Notification protocol defines a mechanism for client applications to discover notification services available for any given resource.

The following diagram shows the high-level interactions involved in discovering notification channels and subscription resources. A subscription resource allow Subscription Clients to request a customised notification channels.

Solid Notifications Flow Discovery and Subscription

A notification channel allows a Notification Sender to send notifications to a Notifications Receiver. A notification channel builds upon one of many established web protocols to exchange data, determining its type.

The following diagram illustrates the flow of data for those notification channel types in which a client establishes a subscription and then maintains a persistent connection to a notifications source are illustrated by the following diagram.

Solid Notifications Flow Receive From, where the receiver establishes connection to sender.

The following diagram illustrates the flow of data for those Notification channel types in which a client establishes a subscription and does not maintain a persistent connection to a notifications source:

Solid Notifications Flow Send To, where the sender delivers notifications to receiver.

Namespaces

Prefixes and Namespaces
Prefix Namespace Description
notify http://www.w3.org/ns/solid/notifications# Solid Notifications

Conformance

This section describes the conformance model of the Solid Notifications Protocol.

Normative and Informative Content

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”, “MUST NOT”, “SHOULD”, and “MAY” are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

The key words “strongly encouraged”, “strongly discouraged”, “encouraged", “discouraged", “can", “cannot”, “could”, “could not”, “might”, and “might not” are used for non-normative content.

Specification Category

The Solid Notifications Protocol identifies the following Specification Category to distinguish the types of conformance: API, notation/syntax, set of events, protocol.

Classes of Products

The Solid Notifications Protocol identifies the following Classes of Products for conforming implementations. These products are referenced throughout this specification.

Subscription Client
A Subscription Client that builds on HTTP client [RFC7230], [RFC7231], and [FETCH] by defining behaviour in terms of fetching across the platform.
Subscription Server
A Subscription Server that builds on HTTP server [RFC7230] and [RFC7231].
Notification Sender
A Notification Sender is the sender of a notification acting in conformance to the product class of a notification channel type.
Notification Receiver
A Notification Receiver is the recipient of a notification acting in conformance to the product class of a notification channel type.
Resource Server
A resource server that builds on HTTP server [RFC7230] and [RFC7231] by defining media types, HTTP header fields, and the behaviour of resources, as identified by link relations.

Interoperability

Interoperability occurs between Subscription Client—Resource Server, Subscription Client—Subscription Server, or Notification Sender—Notification Receiver, as defined by the Solid Notifications Protocol.

Subscription Client—Resource Server interoperability
Interoperability of implementations for Subscription Clients and Resource Servers is tested by evaluating an implementation’s ability to request and respond to HTTP messages that conform to the Solid Notifications Protocol.
Subscription Client—Subscription Server interoperability
Interoperability of implementations for Subscription Clients and Subscription Servers is tested by evaluating an implementation’s ability to request and respond to HTTP messages that conform to the Solid Notifications Protocol.
Notification Sender—Notification Receiver interoperability
Interoperability of implementations for Notification Sender and Notification Receiver is tested by evaluating an implementation’s ability to produce and consume content that adheres to the notification message data model and conforms to a particular notification channel type.

Protocol

The Solid Notifications Protocol specifies a mechanism for discovery of notification capabilities on resources, customisation of notification channels through subscriptions, capabilities of notification channels, and methods for establishing a connection to a notification channel.

A Resource Server may provide notifications over a notification channel that might be of one of many notification channel types that build upon existing web protocols. Individual notification channel types may augment the discovery and subscription requirements of the notification protocol.

This specification uses JSON-LD [JSON-LD11] as the preferred data format, and https://www.w3.org/ns/solid/notification/v1 as a URI for the JSON-LD context and as a value of the profile parameter used for content negotiation.

This specification does not require a specific authentication and authorization mechanism to be used with the Solid Notification Protocol. Implementations are encouraged to use existing approaches, such as those described in the Solid Protocol sections on Authentication and Authorization [SOLID-PROTOCOL].

Discovery

The starting point for discovery is the resource which the notification is about, hereafter referred as the topic resource. Choosing the most appropriate topic resource from which to begin discovery is at the discretion of the Subscription Client, since notifications may be available for any resource for authorized access subjects.

Resource Servers enable Subscription Clients to discover description resources that are associated with a topic resource.

A description resource is an RDF document [RDF11-CONCEPTS] that includes information about the capabilities and features of a subscription resource or notification channel.

Resource Servers can advertise subscription resources that can be used to create notification channels:

  • for protected resource, which relies on capability URL to protect the channel;
  • with specific features required by the subscribing client.

Resource Servers can advertise existing notification channels to provide notifications:

  • for protected resource, which does not rely on capability URL to protect the channel;
  • for public read resource.

Description resources can be discovered as follows:

Resource Servers MUST accept requests targeting the description resource when the value of the Accept header indicates a preferred representation in application/ld+json [JSON-LD11].

Example: Discovery of description resource.

HEAD https://example.org/guinan/profile

HTTP/1.1 200 OK
Link: <https://example.org/guinan/profile.description>; rel="describedby"

GET https://example.org/guinan/profile.description
Accept: application/ld+json

HTTP/1.1 200 OK
Content-Type: application/ld+json
Discovering description resource with a JSON-LD serialization.

Subscription

The subscriptions mechanism enables Subscription Clients to request notifications for changes on a particular resources using a customised notification channel.

A subscription resource is an RDF document [RDF11-CONCEPTS] described with the Subscription Resource Data Model that can be used by Subscription Clients to discover available features and customize the details of a subscription request.

A subscription request is an HTTP request that targets a subscription resource by a Subscription Client requesting to receive notifications about one or more topic resources. The payload of the subscription request describes the desired notification channel.

A subscription response is an HTTP response to a subscription request by a Subscription Server. The payload of the subscription response describes the created notification channel.

Subscription Clients MUST use the Notification Channel Data Model, and in addition conform to a particular notification channel type in the subscription request payload.

Subscription Servers MUST support the GET, HEAD, OPTIONS, and POST methods [RFC7231] methods on the subscription resource.

Subscription Servers MUST accept requests on the subscription resource when the value of the Accept header indicates a preferred representation in application/ld+json [JSON-LD11].

Subscription Servers MUST accept requests on the subscription resource when the value of the Content-Type header indicates the payload's media type in application/ld+json [JSON-LD11].

Subscription Servers MUST respond with a 415 status code for HTTP requests with unsupported values in the profile parameter.

Subscription Servers MUST respond with a 422 status code [RFC4918] when unable to process the contained instructions, including unrecognised JSON-LD context in representation data.

Subscription Servers MUST use Notification Channel Data Model, and in addition conform to a particular notification channel type in the subscription response payload.

Example: Subscription request and response.

GET https://websocket.example/subscription
Accept: application/ld+json

HTTP/1.1 200 OK
Content-Type: application/ld+json

POST https://websocket.example/subscription
Accept: application/ld+json
Content-Type: application/ld+json

HTTP/1.1 200 OK
Content-Type: application/ld+json
Requesting a subscription and response with a JSON-LD serialization.

Notification Channel

A notification channel is a resource whose properties describe the immediately available notification interface with a specific notification channel type and established features following the Notification Channel Data Model.

Notification Sender MUST be able to produce message payloads using the Notification Message Data Model, in addition to conforming to a particular notification channel type.

Notification Receiver MUST be able to process message payloads using the Notification Message Data Model, in addition to conforming to a particular notification channel type.

Notification Channel Types

A notification channel type is a specific communication protocol that governs how classes of products can establish a connection to send and receive messages. A notification channel type is identified by a IRI used to both discover and establish the notification channels. A notification channel type can also require additional data formats or extend the core data models.

Note: Notification Channel Type Registry

Notification channel types are defined and published independently of this document. In order to help with the discovery of notification channel types that can be used with this specification, it is encouraged to register them in the Solid Technical Reports [SOLID-TECHNICAL-REPORTS] for maximum global interoperability. New notification channel types, along with changes to existing entries, can be requested by following the registry definition in Solid Technical Reports.

When defining IRIs for use with a notification channel type, it is considered best practice to publish the vocabulary and the JSON-LD context as publicly accessible documents.

Extensions incorporate additional features beyond what is defined in this specification. Extensions are strongly encouraged to not contradict nor cause the non-conformance of functionality defined in this specification.

Features

Features describe custom properties of a notification channel. Description Resources may advertise a list of features that the Subscription Server can modify. Subscription Clients can modify these features to customise the details of a requested notification channel. Subscription clients can discover available features in a subscription resource.

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

startAt
The proposed or actual starting date and time of a notification channel with value represented in the xsd:dateTime datatype.
endAt
The proposed or actual ending date and time of a notification channel with value represented in the xsd:dateTime datatype.
state
The last known state of a topic resource with value represented in the xsd:string datatype.
rate
The minimum amount of time to elapse between notifications sent to receiver with value represented in the xsd:duration datatype.
accept
The media types that are acceptable by the recipient of a notification with value corresponding to the HTTP Accept header value [RFC7231].

Notification Message

A Notification Sender is triggered by a process to deliver notifications about one or more topic resources to a Notification Receiver.

Notification Senders can augment the JSON-LD Context definition and extend the content of notifications. See for example using multiple vocabularies.

Notification Receivers are encouraged to be aware that anything can be included in the notification message (depending on restrictions in place by the receiver, which are not defined by this specification but may be by a notification channel type), so when it comes to making use of notification data, receivers may want to take precautions when ascertaining the veracity of the contents.

Data Model

This section specifies the data models fordescription resource, subscription resource, notification channel, and notification message.

Description Resource

The description resource has the following properties:

  • One id property to identify the description resource.
  • Zero, one, or many subscription properties to identify the available subscription resources.
  • Zero, one, or many channel properties to identify the available notification channels.

Example: Representation of a description resource.

{
  "@context": [
    "https://www.w3.org/ns/solid/notification/v1"
  ],
  "id": "https://example.org/guinan/profile",
  "subscription": [{
    "id": "https://websocket.example/subscription",
    "channelType": "WebSocketChannel2023",
    "feature": ["endAt", "rate", "state"]
  }],
  "channel": [{
    "id": "https://channel.example/guinan/profile",
    "type": "WebSocketChannel2023",
    "topic": "https://example.org/guinan/profile",
    "receiveFrom": "wss://websocket.example/guinan/profile",
    "rate": "PT1M"
  }]
}
JSON-LD serialization of a description resource.

Subscription Resource

The subscription resource has the following properties:

  • One id property to identify the subscription resource.
  • One channelType property to state the notification channel type.
  • Zero, one, or many feature properties to state the supported features.

Example: Representation of a subscription resource.

{
  "@context": [
    "https://www.w3.org/ns/solid/notification/v1"
  ],
  "id": "https://websocket.example/subscription",
  "channelType": "WebSocketChannel2023",
  "feature": ["endAt", "rate", "state"]
}
JSON-LD serialization of a subscription resource.

Notification Channel

The notification channel has the following properties:

  • One id property to identify the notification channel.
  • One type property to state the notification channel type.
  • At least one topic property to identify the resource that the notifications are about.
  • Zero, one, or many properties stating a particular feature.

Where a Notification Receiver establishes the connection, the notification channel has the following additional property:

  • One receiveFrom property to identify the resource on the Notification Sender that can be used to establish a connection to receive notifications.

Where a Notification Sender pushes notifications, the notification channel in the subscription request has the following additional property:

  • Zero or one sendTo property to identify the resource where the Notification Receiver can accept notifications.

Where a Notification Sender pushes notifications, the notification channel in the subscription response has the following additional properties:

Example: Representation of a notification channel.

{
  "@context": [
    "https://www.w3.org/ns/solid/notification/v1"
  ],
  "id": "https://channel.example/ac748712",
  "type": "WebSocketChannel2023",
  "topic": "https://example.org/guinan/profile",
  "receiveFrom": "wss://websocket.example/d4cf3f19",
  "startAt": "2023-01-01T07:00:00.000Z",
  "endAt": "2023-01-01T09:00:00.000Z",
  "rate": "PT5M",
  "state": "e75-TFJH"
}
JSON-LD serialization of a notification channel.

Notification Message

The core notification data is expressed with the Activity Streams [ACTIVITYSTREAMS-VOCABULARY] and Solid Notifications vocabularies.

A notification has the following properties:

  • One id property to identify the notification.
  • At least one type property indicating a specific type of activity (Activity Types).
  • One object property to identify the (topic) resource that the notification is about.
  • One published property to indicate the date and time of the notification.
  • Zero, one, or many target properties to identify the resource to which the activity is directed.
  • Zero or one state property to indicate the last known state of the resource.

Example: An update activity

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://www.w3.org/ns/solid/notification/v1"
  ],
  "id": "urn:uuid:fc8b5af4-bd7e-4fd1-a649-afcbd0e1c083",
  "type": "Update",
  "object": "https://example.org/guinan/profile",
  "state": "128f-MtYev",
  "published": "2021-08-05T01:01:49.550Z"
}
An activity indicating that an object (profile) was updated.

Example: An add activity

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://www.w3.org/ns/solid/notification/v1"
  ],
  "id": "urn:uuid:a4da6738-6be0-11ed-90bd-1be4ba6b6b33",
  "type": "Add",
  "object": "https://example.org/guinan/photos/image",
  "target": "https://example.org/guinan/photos/",
  "published": "2022-11-24T11:55:31.483Z"
}
An activity indicating that an object (image) was added to the target (photos).

Considerations

This section details security and privacy considerations.

Some of the normative references within 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.

Subscription Servers and Notification Senders are strongly discouraged from exposing information beyond the minimum amount necessary to enable a feature. Subscription Clients are strongly discouraged from exposing information beyond the minimum amount necessary to subscribe to updates about particular resources.

Subscription Clients are discouraged from sending subscription requests to untrusted subscription resources, including localhost or any other loopback IP address, in order to avoid making arbitrary requests.

Privacy 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?
There are no known security impacts of the features in this specification.
Do features in your specification expose the minimum amount of information necessary to enable their intended uses?
Yes.
How do the features in your specification deal with personal information, personally-identifiable information (PII), or information derived from them?
Access to subscription resource and notification message are only granted to authorized access subjects. The subscription request, subscription response, and notification message payloads can contain any data (including that which identifies or refers to agents that control the Subscription Client and Notification Sender.) Meaningful consent to any personal data that Subscription Clients include about agents associated with themselves or topic resources of interest are extended to the Notification Receiver. Subscription Clients, Subscription Server, and Notification Senders are discouraged from exposing information beyond the amount necessary to enable or use a feature.
How do the features in your specification deal with sensitive information?
The features do not require sensitive information to obtained or exposed.
Do the features in your specification introduce new state for an origin that persists across browsing sessions?
No.
Do the features in your specification expose information about the underlying platform to origins?
No.
Does this specification allow an origin to send data to the underlying platform?
No. Description resources and subscription resources are described within the framework of HTTP as RDF documents represented with the JSON-LD syntax. Subscription Servers and Notification Receivers might be able to redirect to other resources, (e.g., the https: URLs to file:, data:, or blob: URLs), but no such behaviour is defined by this specification.
Do features in this specification allow an origin access to sensors on a user’s device
No.
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.
No detail about another origin’s state is exposed. As the association between a resource and its description resource is at the discretion of the resource server, they can be on different origins [RFC6454]. Similarly, the origins of subscription resource and the notification channel might also be different. When subscription servers, servers hosting the notification channel, and servers allowing connections to receive notifications participate in the CORS protocol [FETCH], HTTP requests from different origins may be allowed. This feature does not add any new attack surface above and beyond normal CORS requests, so no extra mitigation is deemed necessary.
Do features in this specification enable new script execution/loading mechanisms?
No.
Do features in this specification allow an origin to access other devices?
No.
Do features in this specification allow an origin some measure of control over a user agent’s native UI?
No.
What temporary identifiers do the features in this specification create or expose to the web?
The subscription response payload can contain a capability URL to protect the notification channel which is only exposed to authorized Subscription Clients.
How does this specification distinguish between behaviour in first-party and third-party contexts?
Not Applicable.
How do the features in this specification work in the context of a browser’s Private Browsing or Incognito mode?
No different than in the browser’s 'normal' state.
Does this specification have both "Security Considerations" and "Privacy Considerations" sections?
Yes, in Security Considerations and Privacy Considerations.
Do features in your specification enable origins to downgrade default security protections?
No.
How does your feature handle non-"fully active" documents?
Not Applicable.

Change Log

This section is non-normative.

The summary of editorial and substantive changes in this section are based on W3C Process Document Classes of Changes [W3C-PROCESS].

EDnotifications-protocol-20220509

Changes from notifications-protocol-20220509 to this version

References

Normative References

[ACTIVITYSTREAMS-VOCABULARY]
Activity Streams. James Snell; Evan Prodromou. W3C. 23 May 2017. W3C Recommendation. URL: https://www.w3.org/TR/activitystreams-vocabulary/
[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/
[POWDER-DR]
Protocol for Web Description Resources (POWDER): Description Resources. Phil Archer; Kevin Smith; Andrea Perego. W3C. 1 September 2009. W3C Recommendation. URL: https://www.w3.org/TR/powder-dr/
[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
[RFC4918]
HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV). L. Dusseault, Ed. IETF. June 2007. Proposed Standard. URL: https://datatracker.ietf.org/doc/html/rfc4918
[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-PROTOCOL]
Solid Protocol. Sarven Capadisli; Tim Berners-Lee; Ruben Verborgh; Kjetil Kjernsmo. W3C Solid Community Group. Version 0.10.0. URL: https://solidproject.org/TR/protocol
[XMLSCHEMA11-2]
W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes. David Peterson; Sandy Gao; Ashok Malhotra; Michael Sperberg-McQueen; Henry Thompson; Paul V. Biron et al. W3C. 5 April 2012. W3C Recommendation. URL: https://www.w3.org/TR/xmlschema11-2/

Informative References

[SOLID-TECHNICAL-REPORTS]
Solid Technical Reports. Sarven Capadisli. W3C Solid Community Group. 5 January 2023. Living Document. URL: https://solidproject.org/TR/
[NOTIFICATIONS-UCR]
Solid Notifications Use Cases and Requirements. Sarven Capadisli. W3C Solid Community Group. 28 November 2022. W3C Editor’s Draft. URL: https://solid.github.io/notifications-panel/notifications-ucr
[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/