Solid Notifications Protocol

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 services. A subscription service allow Subscription Clients to request a customised notification channels.

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.

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:

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

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 service or notification channel.

Resource Servers can advertise subscription services 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 that want to enable Subscription Clients to discover subscription services and notification channels available for a given resource MUST advertise the associated resources describing the subscription services 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].

Resource Servers that want to enable Subscription Clients to discover subscription services and notification channels available to a storage in which a given resource is in MUST advertise the associated resources describing the subscription services and notification channels by responding to an HTTP request including a Link header with the rel value of http://www.w3.org/ns/solid/terms#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].

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

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

A subscription service is an RDF document [RDF11-CONCEPTS] described with the Subscription Service 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 service 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 service.

Subscription Servers MUST accept requests on the subscription service 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 service 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.

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

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.

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.

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 services.
• Zero, one, or many channel properties to identify the available notification channels.

{
  "@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"
  }]
}

The subscription service has the following properties:

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

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

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:

• Zero or one sender property to identify the Notification Sender

{
  "@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"
}

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.

{
  "@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"
}

{
  "@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"
}

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 services, including localhost or any other loopback IP address, in order to avoid making arbitrary requests.

This section is non-normative.

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

• 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, and profile use.
• Deprecate concepts: subscription types, subscription types index, expiration.
• Add descriptions: notification channel, notification channel types, notification channel type registry.
• Change reference from notify:features to notify:feature.
• Update descriptions: features, startAt, endAt, state, rate, accept.
• Add definitions: topic resource, description resource, subscription service, 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, unrecognised profile 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 service, notification channel, notification message.
• Add Security Considerations, Security and Privacy Review.