Solid Notifications Protocol

Version 0.1.0, 2022-05-09

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.1.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.1.0 does not imply endorsement by the W3C Membership. This 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.

This specification is for:

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

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.

Notification Subscription API: An HTTP URI at which a client can initiate a subscription to notification events for a particular set of resources [RFC7231].
Notification Subscription Metadata Resource: An RDF document [RDF11-CONCEPTS] that includes metadata about the capabilities of a Notification Subscription API.

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.

Discovery

Issue: Notification Subscription Metadata Discovery

The specific mechanism defining the discovery of the Notification Subscription Metadata Resource is under consideration: issues/58.

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

Turtle Serialization

When serializing the Notification Subscription Metadata Resource as Turtle, every notify:notificationChannel definition MUST materialize an rdf:type triple, indicating the channel type.

A sample representation of this resource might include the following:

Example: Representation of a Notification Subscription Metadata 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:features notify:state, notify:rate, notify:expiration .

TURTLE serialization of a Notification Subscription Metadata Resource

The Notifications Panel will need to define a notification vocabulary to support this feature.

JSON-LD Serialization

When serializing the Notification Subscription Metadata Resource as JSON-LD, the @contextfield MUST be an array containing the value https://www.w3.org/ns/solid/notification/v1. In addition, for every notificationChannel definition, the Subscription Metadata Resource MUST materialize a type field, indicating the channel type.

Example: Representation of a Notification Subscription Metadata 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",
    "features": ["state", "rate", "expiration"]
  }]
}

JSON-LD serialization of a Notification Subscription Metadata Resource

The Notifications Panel will need to define a JSON-LD context resource to support this feature.

Subscription

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

Servers MUST accept GET, HEAD and OPTIONS requests targeting the subscription resource.

Servers MUST accept authorized POST requests targeting the subscription resource with a well-formed payload serialized as JSON-LD.

The JSON-LD payload received by a server in a POST request MUST contain at least three fields: @context, type and topic. All other data requirements are defined by the individual subscription types. Some common feature properties are described in the Features section of this document.

@context: The @context property is MUST be an array containing the value https://www.w3.org/ns/solid/notification/v1. Other values MAY also be present.
type: The type property MUST indicate the subscription type to be created.
topic: The topic property MUST indicate the IRI(s) of the resources about which the client would like to receive notifications.

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 makes it possible to define new subscription types. A list of known subscription types is available in the Solid Notifications source repository.

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

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.

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.

While not necessary, we encourage authors to register subscription types with the Solid project, allowing them to be discovered by the Solid community. The process for registration shall be available at the Solid Notifications repository.

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?: ..

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

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