LinkedDataNotificationsSubscription2021

The Solid Notifications Protocol defines a set of interaction patterns for agents to establish subscriptions to resources in a Solid Storage. This specification defines a subscription type to enable the delivery of change notifications about a resource to an Linked Data Notifications inbox.

This section describes the status of this document at the time of its publication.

This document was published by the Solid Community Group as an Editor’s Draft. The sections that have been incorporated have been reviewed following the Solid process. However, the information in this document is still subject to change. You are invited to contribute any feedback, comments, or questions you might have.

Publication as an Editor’s Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

This section is non-normative.

The Solid Notifications Protocol describes a general pattern by which agents can be notified when a Solid Resource changes. This specification defines a subscription type to enable the delivery of change notifications about a resource to Linked Data Notifications inbox.

This specification is for:

• Resource server developers who wish to enable clients to listen for updates to particular resources.
• Application developers who wish to implement a client to listen for updates to particular resources.

Overview

This section is non-normative.

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

This specification defines the LinkedDataNotificationsSubscription2021 type for use with Solid Notifications subscriptions. The URI of the subscription type is http://www.w3.org/ns/solid/notification#LinkedDataNotificationsSubscription2021.

The URI and definition of the subscription type is pending the approval of JSON-LD Context and the Notification vocabulary: https://github.com/solid/vocab/pull/62/.

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

An LinkedDataNotificationsSubscription2021 API SHOULD support the Solid Notifications Features.

The LinkedDataNotificationsSubscription2021 type defines the following properties:

inbox

The inbox property is used in the body of the subscription request. The value of this property MUST be a URI, using the https scheme. The inbox URI MUST conform to the receiver portion of the Linked Data Notifications [LDN] specification.

webid

The webid property is used in the body of the subscription response. The value of this property MUST be an HTTPS URI conforming to WebID 1.0 [WEBID]. All LDN notifications will be sent to the defined inbox using the agent identity specified by this WebID. A resource owner should ensure that the agent identified in this property is permitted to send authenticated HTTP requests to the defined inbox.

A client establishes a subscription using the LinkedDataNotificationsSubscription2021 type by sending an authenticated subscription request to the hypermedia API retrieved via Solid Notifications Discovery.

For LinkedDataNotificationsSubscription2021 interactions, the client sends a JSON-LD payload to the appropriate hypermedia API via POST. The only required fields in this interaction are type, topic and inbox. The type field MUST contain the type of subscription being requested. The topic field MUST contain the URL of the resource a client wishes to subscribe to changes. The topic field MUST contain the URL of an inbox that notifications can be sent to.

When responding to the subscription request, the server MUST respond with a JSON-LD payload. The only required fields are type and webid. The type field MUST contain the type of subscription being provided. The webid field MUST contain the URI of the agent that will send notifications to the inbox.

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

{
  "@context": "https://www.w3.org/ns/solid/notification/v1",
  "type": "LinkedDataNotificationsSubscription2021",
  "topic": "https://storage.example.org/resource",
  "inbox": "https://receiver.example.net/inbox/",
  "state": "opaque-state",
  "expiration": "2022-12-29T15:00:00Z",
  "rate": "PT10s"
}

HTTP/2
Content-Type: application/ld+json

{
  "@context": "https://www.w3.org/ns/solid/notification/v1",
  "type": "LinkedDataNotificationsSubscription2021",
  "webid": "https://agent.example/profile#i"
}

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

It is beyond the scope of this document to describe how a client fetches an access token. Solid-OIDC is one example of an authentication mechanism that could be used with Solid Notifications [SOLID-OIDC].