LDNChannel2023

Version 1.0.0 Editor’s Draft, 2023-02-03

Abstract

The Solid Notifications Protocol describes how notification receivers can have messages pushed to them by notification senders, as well as how applications can choose from available notification channels in which notification receivers get messages. This specification defines the LDNChannel2023 notification channel type to enable Subscription Clients to request subscriptions to Subscription Servers, and for Notification Senders to deliver messages to Notification Receivers based on the Linked Data Notifications protocol.

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

In order to enable users to be notified about activities pertaining topic resources of interest at any point in time, their applications need to make subscription requests indicating where they can be notified.

LDN supports sharing and reuse of notifications across applications, regardless of how they were generated. This allows for more modular systems, which decouple data storage from the applications which display or otherwise make use of the data. Instead of treating notifications as ephemeral or non-persistent entities, this specification works with the notion of a notification as an individual entity with its own URI. As such, notifications can be retrieved and reused.

This specification is for:

Server developers that want to enable clients to receive activities about resources.
Application developers who want to implement a client to receive activities about resources.

Terminology

This section is non-normative.

This specification uses the terms from the [SOLID-NOTIFICATIONS-PROTOCOL] specification. When Solid Notifications Protocol terminology is used it is linked directly to that specification.

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 Protocol identifies the following Specification Category to distinguish the types of conformance: API, notation/syntax, set of events, protocol.

Classes of Products

The LDNChannel2023 notification channel type identifies the following Classes of Products for conforming implementations by specialising Solid Notifications Protocol's Classes of Products. These products are referenced throughout this specification.

Subscription Client: A Subscription Client requests subscriptions by building on Subscription Client [SOLID-NOTIFICATIONS-PROTOCOL].
Subscription Server: A Subscription Server responds to subscription requests by building on Subscription Server [SOLID-NOTIFICATIONS-PROTOCOL] and Receiver [LDN].
Notification Sender: A Notification Sender is the sender of a notification message by building on Notification Sender [SOLID-NOTIFICATIONS-PROTOCOL]
Notification Receiver: A Notification Receiver is the recipient of a notification message by building on Notification Receiver [SOLID-NOTIFICATIONS-PROTOCOL] and Receiver [LDN].
Resource Server: A resource server that builds on Resource Server [SOLID-NOTIFICATIONS-PROTOCOL].

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

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

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 data model and conforms to the LDNChannel2023 notification channel type.

Protocol

This section specifies the discovery mechanism, capabilities of subscriptions, and establishing a connection to a notification channel.

Implementations are encouraged to use existing approaches, such as those described in the Solid Protocol sections on Authentication and Authorization [SOLID-PROTOCOL].

Issue: Authentication: exchanging public keys, signing messages

Details need to be further specified. The Security Vocabulary (or The Cert Ontology, WOT) can be used.

Subscription Clients to share Notification Receiver's public key, where sendTo has a controller (which is the receiver).
Subscription Servers to share Notification Sender's public key, where sender describes the key.

See Notification Channel Data Model for example subscription requests and response including public keys.

Subscription Client lets the Notification Receiver know about the Notification Sender and their public key.

Notification Receiver sets Authorization rules for Notification Sender.

Notification Sender can optionally use HTTP Message Signatures.

Discovery

This specification's discovery mechanism is a constraint of Solid Notifications Protocol's description resource in that the description resource only advertises the subscription resource.

Subscription

The subscription mechanism enables Subscription Clients and Subscription Servers with the creation and management of subscriptions.

A subscription response is an extension of subscription response [SOLID-NOTIFICATIONS-PROTOCOL] (where the Subscription Server conforms to Receiver [LDN]).

Subscription Clients MUST use the Notification Channel Data Model in the subscription request payload.

Subscription Servers MUST use the Notification Channel Data Model in the subscription response payload.

Example: Subscription request and modification.

POST https://ldn.example/subscription/

HTTP/1.1 201 Created
Location: https://ldn.example/subscription/c452ea4f-77dc-4818-af6b-845455881a6b

POST https://ldn.example/subscription/c452ea4f-77dc-4818-af6b-845455881a6b
Accept: application/ld+json

HTTP/1.1 200 OK
Content-Type: application/ld+json

DELETE https://ldn.example/subscription/c452ea4f-77dc-4818-af6b-845455881a6b

HTTP/1.1 204 No Content

Creating, modifying, and removing a subscription with JSON-LD serialization.

Notification Channel

Notification Sender MUST be able to produce message payloads using the Notification Message Data Model.

Notification Receiver MUST be able to process message payloads using the Notification Message Data Model.

LDNChannel2023

This specification defines the LDNChannel2023 notification channel type with the URI http://www.w3.org/ns/solid/notifications#LDNChannel2023 that can be used with Solid Notifications Protocol.

Features

The following features can be used with the LDNChannel2023 notification channel type:

activityType: A property used to indicate the notification activity type.

Issue: Add activityType to vocab and JSON-LD context

#http://www/w3.org/ns/solid/notifications
notify:activityType
    a rdf:Property ;
    rdfs:label "notification activity type"@en ;
    rdfs:comment "A property used to indicate the notification activity type."@en ;
    rdfs:isDefinedBy <http://www.w3.org/ns/solid/notifications#> ;
    vs:term_status "testing" .

#https://www.w3.org/ns/solid/notification/v1
    "activityType": {
      "@id": "notify:activityType",
      "@type": "@id" },

Notification Message

A Notification Sender is triggered by a process to deliver messages to Notification Receiver.

Notification Receivers MUST conform to the receiver requirements of the Linked Data Notifications [LDN] specification when allowing requests to the resource specified by sendTo.

Notification Senders MUST use the sender value to identify themselves when the Notification Receiver requires authentication.

Notification Receiver is expected to accept notifications from the sender at the sendTo location.

Data Model

This section describes the description resource, subscription resource, notification channel, and notification message data models which specialises the data models of Solid Notification Protocol.

Description Resource

The description resource has the following properties:

One id property to identify the resource described by the description resource.
One or many subscription property to identify the available subscription resources.

Example: Representation of a description resource.

{
  "@context": [
    "https://www.w3.org/ns/solid/notification/v1"
  ],
  "id": "https://example.org/guinan/photos/",
  "subscription": [{
    "id": "https://ldn.example/subscription/",
    "channelType": "LDNChannel2023",
    "feature": ["activityType", "startAt", "endAt", "rate"]
  }]
}

JSON-LD serialization of a description resource.

Subscription Resource

The subscription resource has the following properties:

One id property to identify subscription resource.
One channelType property whose object is LDNChannel2023.
Zero, one or many feature property value(s) to state the supported features.

Example: Representation of a subscription resource.

{
  "@context": [
    "https://www.w3.org/ns/solid/notification/v1"
  ],
  "id": "https://ldn.example/subscription/",
  "channelType": "LDNChannel2023",
  "feature": ["activityType", "startAt", "endAt", "rate"]
}

JSON-LD serialization of a subscription resource.

Notification Channel

The notification channel has the following properties:

One id property to identify the notification channel.
One type property whose object is LDNChannel2023.
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 in the subscription request has the following property:

One sendTo property to identify the resource that can accept notifications (LDN inbox).
Zero or one receiver property to identify the party that controls the sendTo resource.

Issue: Add receiver to vocab and JSON-LD context

Issues: notifications/issues/153

#http://www/w3.org/ns/solid/notifications
notify:receiver
    a rdf:Property ;
    rdfs:label "receiver"@en ;
    rdfs:comment "The property used to identify the party that receives notifications."@en ;
    rdfs:isDefinedBy <http://www.w3.org/ns/solid/notifications#> ;
    vs:term_status "testing" .

#https://www.w3.org/ns/solid/notification/v1
    "receiver": {
      "@id": "notify:receiver",
      "@type": "@id" },

Example: Requesting a subscription to a topic resource.

{
  "@context": [
    "https://www.w3.org/ns/solid/notification/v1",
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/security/v1"
  ],
  "id": "",
  "type": "LDNChannel2023",
  "topic": "https://example.org/guinan/photos/",
  "sendTo": {
    "id": "https://notification-receiver.example.org/inbox/",
    "controller": {
       "id": "https://notification-receiver.example.org/profile#i",
       "publicKey": {
         "id": "https://notification-receiver.example.org/profile#key-MIID8zCCAt",
         "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMIID8zCCAt...ysw/GRyQ==\n-----END PUBLIC KEY-----\n"
       }
    }
  }
  "receiver": "https://notification-receiver.example.org/profile#i",
  "activityType": "Add",
  "endAt": "2023-12-31T23:59:59Z",
  "rate": "PT1M"
}

Subscription request including id, type, topic, sendTo, and receiver.

Notification channel in the subscription response has the following property:

One sender property to identify the party that sends notifications.

Example: Responding to a subscription request.

{
  "@context": [
    "https://www.w3.org/ns/solid/notification/v1",
    "https://www.w3.org/ns/activitystreams",
    "https://w3id.org/security/v1"
  ],
  "id": "https://ldn.example/subscription/c452ea4f-77dc-4818-af6b-845455881a6b",
  "type": "LDNChannel2023",
  "topic": "https://example.org/guinan/photos/",
  "sender": {
    "id": "https://notification-sender.example.net/profile#i",
    "publicKey": {
      "id": "https://notification-sender.example.net/profile#key-MIIAwIBAgI",
      "publicKeyPem": "-----BEGIN PUBLIC KEY-----\MIIAwIBAgI...5zQYzPyswx\n-----END PUBLIC KEY-----\n"
      "controller": "https://notification-sender.example.net/profile#i",
    }
  }
  "sendTo": "https://notification-receiver.example.org/inbox/",
  "receiver": "https://notification-receiver.example.org/profile#i",
  "activityType": "Add",
  "startAt": "2023-01-01T00:00:00Z",
  "endAt": "2023-12-31T23:59:59Z",
  "rate": "PT5M"
}

Subscription response including id, type, topic, and sender.

Notification Message

Example: An add activity

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

An activity indicating that an object (image) was added to the target (photos).

References

Normative References

[LDN]: Linked Data Notifications. Sarven Capadisli; Amy Guy. W3C. 2 May 2017. W3C Recommendation. URL: https://www.w3.org/TR/ldn/
[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
[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
[SOLID-NOTIFICATIONS-PROTOCOL]: Solid Notifications Protocol. Sarven Capadisli. W3C Solid Community Group. Version 0.2.0. URL: https://solidproject.org/TR/notifications-protocol

Informative References

[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