Solid Notifications Protocol
+Version 0.2.0, 2022-12-31
+ +More details about this document
+ +-
+
- This version +
- https://solidproject.org/TR/2022/notifications-protocol-20221231 +
-
+
- Latest published version +
- https://solidproject.org/TR/notifications-protocol +
-
+
- Previous version +
- https://solidproject.org/TR/2022/notifications-protocol-20220509 +
-
+
- Editor’s draft +
- https://solid.github.io/notifications/protocol +
-
+
- Editors +
- Sarven Capadisli +
-
+
- Created + +
-
+
- Published + +
-
+
- Modified + +
-
+
- Repository +
- GitHub +
- Issues +
-
+
- Language +
- English +
-
+
- License +
- MIT License +
-
+
- Document Status +
- Published +
-
+
- Resource State +
- Memento +
-
+
- In Reply To +
- Solid Origin +
- Notifications Panel Charter +
-
+
- Policy +
-
+
-
+
- Rule +
- Offer +
- Unique Identifier +
- https://solidproject.org/TR/notifications-protocol#document-policy-offer +
- Target +
- https://solidproject.org/TR/notifications-protocol +
- Permission +
-
+
-
+
- Assigner +
- W3C Solid Community Group +
- Action +
-
+
-
+
- Aggregate +
- Archive +
- Concurrent Use +
- Derivative Works +
- Derive +
- Digitize +
- Display +
- Distribution +
- Index +
- Inform +
- Install +
- Notice +
- Present +
- Read +
- Reproduce +
- Reproduction +
- Stream +
- Synchronize +
- Text-to-speech +
- Transform +
- Translate +
+
+
+
MIT License. Copyright © 2022 W3C Solid Community Group.
+ +Abstract
+This specification defines a Linked Data-based protocol for subscribing to resources in the Solid ecosystem. This protocol includes a mechanism for both discovering and establishing subscriptions to resources while also considering 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 Version 0.2.0. 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 Version 0.2.0 does not imply endorsement by the W3C Membership. This document 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 establish and manage subscriptions to 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 a subscription as well as for cases where a client establishes a subscription 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 following diagram shows the high-level interactions involved discovering notification channels and subscription resources to towards receiving notifications.
+ + + +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.
+ + + +Notification channel types in which a client establishes a subscription and does not maintain a persistent connection to a notifications source are illustrated by the following diagram.
+ + +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
+This section specifies the discovery mechanism, capabilities of subscriptions and notification channels, and establishing a connection to a notification channel.
+ +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 in content negotiation.
Discovery
+The starting point for discovery is the resource which the notification is about: 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 of interest.
+ +A description resource is an RDF document [RDF11-CONCEPTS] that includes information about the capabilities and features of a subscription resource or notification channel.
+ +Advertising subscription resources 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. +
Advertising existing notification channels can be used to provide notification channels:
+ +-
+
- 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:
+ +When a resource server wants to enable Subscription Clients to discover subscription resources and notification channels available to a given resource, the Resource Server MUST advertise the associated resources describing the subscription resources and notification channels by responding to an HTTP request including a Link
header with the rel
value of describedby
[POWDER-DR] and the Description Resource as link target [RFC8288].
When a resource server wants to enable Subscription Clients to discover subscription resources and notification channels available to a storage in which a given resource is in, the Resource Server MUST advertise the associated resources describing the subscription resources and notification channels by responding to an HTTP request including a Link
header with the rel
value of http://www.w3.org/ns/solid#storageDescription
[SOLID-PROTOCOL] and the Description Resource as link target [RFC8288].
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].
Subscription
+The subscriptions mechanism enables Subscription Clients to request updates about particular resources using a customised notification channel.
+ +A subscription resource is an RDF document [RDF11-CONCEPTS] 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, in addition to conforming 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, in addition to conforming to a particular notification channel type, in the subscription response payload.
+ + +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 also specifies the data model and format of the messages that are exchanged between products. A notification channel type is identified by a IRI for use with both discovery and the establishment of notification channels.
+ +Note: Notification Channel Types Index
+Notification channel types are defined and published independently of this document. To help with the discovery of notification channel types that can be used with this specification, it is encouraged to register them by following the procedure given in Notification Channel Types [NOTIFICATION-CHANNEL-TYPES].
+ +When defining IRIs for use with a notification channel type, it is considered best practice to publish vocabulary and JSON-LD context documents that are publicly accessible.
+ +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
+Notification channels may have features describing custom properties of the channel. Features can be used by Subscription Clients 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 resource 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 description resource, subscription resources, notification channel, and notification message data models.
+ +Description Resource
+The description resource has the following properties:
+ +-
+
- One
id
property to identify the resource described by the description resource.
+ - Zero, one or many
subscription
property to identify the available subscription resources.
+ - Zero, one or many
channel
property to identify the available notification channels.
+
Subscription Resource
+The subscription resource has the following properties:
+ +-
+
- One
id
property to identify subscription resource.
+ - One
channelType
property to state the notification channel type.
+ - Zero, one or many
feature
property value(s) to state the supported features.
+
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 resources that the notifications are about.
+ - Zero, one or many property values stating a particular feature. +
Notification channel where a Notification Receiver connects has the following property:
+ +-
+
- One
receiveFrom
property to identify the resource that can be used to establish a connection to receive notifications.
+
Notification channel where a Notification Sender delivers notifications has the following properties:
+ +-
+
- Zero or one
sendTo
property to identify the resource that can accept notifications.
+ - Zero or one
sender
property to identify the party that sends notifications.
+
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 resource that the notification is about (topic-resource).
+ - 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.
+
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.
+ +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, 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 tofile:
,data:
, orblob:
URLs), but no 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 can be different. When subscription servers, servers hosting the notification channel, and servers allowing connections to receive notifications participates 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? +
- Inapplicable. + +
- How do the features in this specification work in the context of a browser’s Private Browsing or Incognito mode? +
- No different than
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? +
- Inapplicable. +
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].
+ +notifications-protocol-20221231 ← notifications-protocol-20220509
+ +Changes from notifications-protocol-20220509 to this version
+-
+
- Amend language, document details, and markup. +
- Add Change Log. +
- Update References. +
- Clarify authentication and authorization as non-normative and encouragement. +
- Clarify the use of JSON-LD as data format,
@context
, andprofile
use.
+ - Deprecate concepts: subscription types, subscription types index, expiration. +
- Add descriptions: notification channel, notification channel types, notification channel types index. +
- Change reference from
notify:features
tonotify:feature
.
+ - Update descriptions: features,
startAt
,endAt
,state
,rate
,accept
.
+ - Add definitions: topic-resource, description resource, subscription resource, subscription request, subscription response, notification channel, +
- Add discovery requirements with
Link
headers:describedby
,http://www.w3.org/ns/solid/terms#storageDescription
.
+ - Update subscription client requirements: subscription request. +
- Update subscription server requirements: request methods,
Accept
header,Content-Type
header, unrecognisedprofile
values, unprocessable entity, request response.
+ - Add notification sender requirement: producing notification messages using the notification message data model. +
- Add notification receiver requirement: processing notification messages using the notification message data model. +
- Update Conformance to add Normative and Information Content, Class of Products, Specification Category, Interoperability. +
- Add data models: description resource, subscription resource, notification channel, notification message. +
- Add Security Considerations, Security and Privacy Review. +
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
+-
+
- [NOTIFICATION-CHANNEL-TYPES] +
- Notification Channel Types. Sarven Capadisli. W3C Solid Community Group. 31 December 2022. Living Document. URL: https://solidproject.org/TR/notification-channel-types +
- [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/ +