Solid Notifications Protocol

Editor’s Draft, 2022-08-30

More details about this document
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

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 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 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 (e.g. WebSockets) as well as for cases where a client establishes a subscription and then disconnects.

This specification is for:

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 diagrams show the high-level interactions involved in source and target flows. How a client retrieves an access token for step 3 is outside the scope of this document.

Solid Notifications Flow (source)
Solid Notifications Flow (target)

Terminology

This section is non-normative.

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

notification channel
A notification channel is an abstract thing which is identified by a URI and whose properties describe the available communication interface and features.
notification channel resource
An RDF document [RDF11-CONCEPTS] that includes information about the capabilities of a notification channel.
subscription resource
A subscription resource is an RDF document [RDF11-CONCEPTS] that can hold any information, typically used by clients to discover available features and capabilities (see Notification Features).
subscription request
A subscription request is an HTTP request that targets a subscription resource made by a subscriber indicating interest to receive updates about a particular resource.
subscription response
A subscription response is an HTTP response to a subscription request. The payload of the subscription response are specialised by subscription types.

In addition to the terminology above, this specification also uses terminology from the [SOLID-PROTOCOL] specification. When SOLID-PROTOCOL terminology is used it is linked directly to that specification.

Namespaces

Prefixes and Namespaces
Prefix Namespace Description
rdf http://www.w3.org/1999/02/22-rdf-syntax-ns# [rdf-schema]
solid http://www.w3.org/ns/solid/terms# Solid Terms
notify http://www.w3.org/ns/solid/notifications# Solid Notifications

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 includes both the Discovery of the capabilities of a subscription resource as well as the mechanism for establishing a Subscription.

Individual subscription types may augment the discovery and subscription requirements of the notification protocol.

Issue: Solid Notification Vocabulary and Context

The Solid Notification vocabulary and JSON-LD context is under development: pull/62.

Discovery

Notification Channel Discovery

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

The following properties are used for the discovery of a notification channel and its capabilities:

feature
feature predicate denotes a particular feature of a notification channel (Notification Features).
notificationChannel
notificationChannel predicate denotes that a resource has a notification channel.
subscription
subscription predicate denotes a subscription resource associated with a notification channel (Subscription).
type
type predicate (rdf:type) denotes the notification channel type (Notification Channel).

Servers MUST include the @context field as an array containing the value https://www.w3.org/ns/solid/notification/v1 in the JSON-LD representation of a Notification Channel Resource.

Notification Channel Conformance

A Notification Channel has the following properties:

  • At least one notify:notificationChannel property whose object describes a notification channel.
  • At least one rdf:type property whose object is notify:NotificationChannel.
  • Zero or more notify:feature property values (Notification Features).
  • Zero or one notify:subscription property value (Subscription).

Sample representations of the Notification Channel Resource might include the following:

Example: Representation of a Notification Channel Resource.

Content-Type: text/turtle

@prefix notify: <http://www.w3.org/ns/solid/notifications#> .

<>
  notify:notificationChannel <#websocketNotification> .

<#websocketNotification>
  a notify:WebSocketSubscription2021 ;
  notify:subscription <https://websocket.example/subscription> ;
  notify:feature notify:state, notify:rate, notify:expiration .
Turtle serialization of a resource including notification channel information.

Example: Representation of a Notification Channel Resource.

Content-Type: application/ld+json

{
  "@context": [
    "https://www.w3.org/ns/solid/notification/v1"
  ],
  "notificationChannel": [{
    "id": "websocketNotification",
    "type": ["WebSocketSubscription2021"],
    "subscription": "https://websocket.example/subscription",
    "feature": ["state", "rate", "expiration"]
  }]
}
JSON-LD serialization of resource including notification channel information.

Subscription

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

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].

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].

Clients MUST include statements about the subscription, in addition to other fields described by specific subscription types, as part of the request payload.

Subscription request statements include the properties:

@context
An array containing at least the value https://www.w3.org/ns/solid/notification/v1 in a JSON-LD payload.
type
A class whose URI indicating the subscription type to be created.
topic
The IRI(s) of the resources about which the client would like to receive notifications.

Servers MUST respond with a 422 status code [RFC4918] if a subscription request does not satisfy the payload constraints.

Servers MUST include the @context and type fields, in addition to other fields described by specific subscription types, in the payload of a JSON-LD response when responding to a successful subscription.

Authentication and Authorization

This section is non-normative.

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

Subscription Types

Subscription types define particular interaction patterns for agents to establish and make use of subscription to resources.

Note: Subscription Types Index

An index of subscription types that are work in progress can be found at the repository hosting this document. The index of subscription types that are published as a Solid Technical Report can be found at Notification Subscription Types.

Guidelines for defining new subscription types are included in the Subscription Types Extension section.

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"
  ],
  "object": {
    "id":"https://example.org/<user>/inbox/",
     "type": [
      "http://www.w3.org/ns/ldp#BasicContainer"
    ]
  },
  "state": "1234-5678-90ab-cdef-12345678",
  "published":"2021-08-05T01:01:49.550044Z"
}

Implementations can augment the JSON-LD context definition and extend the content of the notifications.

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.

New subscription types may be defined and published independently of this document. This section describes some guidelines and recommendations for publishing new subscription types.

Each new subscription type will declare a unique IRI for use with both discovery and with the establishment of new subscription connections.

When defining IRIs for use with a subscription type, it is considered best practice to publish vocabulary and JSON-LD context documents that are publicly accessible.

An example subscription request with a custom @context is below:

Example: Establishing a subscription with a custom type.

{
  "@context": [
    "https://www.w3.org/ns/solid/notification/v1",
    "https://notification.example/subscription/v1"
  ],
  "type": "ExampleSubscription2021",
  "topic": "https://storage.example/resource",
  "custom-property": "custom-value"
}
Subscription request with a custom subscription type.

To help with the discovery of subscription types that can be used with this specification, it is encouraged to register them by following the procedure given in Notification Subscription Types [NOTIFICATION-SUBSCRIPTION-TYPES].

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?
..
How does your feature handle non-"fully active" documents?
..

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-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/
[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/
[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
[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
[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. 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

[NOTIFICATION-SUBSCRIPTION-TYPES]
Notification Subscription Types. Sarven Capadisli. W3C. 5 May 2022. Living Document. URL: https://solidproject.org/TR/notification-subscription-types
[NOTIFICATIONS-UCR]
Solid Notifications Use Cases and Requirements. Sarven Capadisli. W3C. 20 January 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/
[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/