Conformance
Document Conventions
All of the text of this specification is normative except assertions, diagrams, examples, notes and sections explicitly marked as non-normative as described in [RFC2119].
The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT" and "MAY" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
The above-mentioned key words are used exclusively in the normative parts of this document and appear only in all capitals.
Specification Category
The Solid-PREP identifies the following Specification Category to distinguish the types of conformance:
-
API,
-
Notation/syntax,
-
Set of events,
-
Protocol.
Classes of Products
The Solid-PREP identifies the following Classes of Products for conforming implementations. These products are referenced throughout this specification.
- Solid Server
-
A Solid server that builds on a server [SOLID] and resource server [PREP] by defining the behaviour of resources.
- Solid Client
-
A Solid client that builds on a client [SOLID] and application client [PREP].
Interoperability
Interoperability occurs between Solid Client—Solid Server as defined by the Solid-PREP.
- Solid Client—Solid Server Interoperability
-
Interoperability of implementations for Solid clients and Solid servers is tested by evaluating an implementation’s ability to transmit and receive PREP Notifications that conform to Solid-PREP.
Namespaces
This document uses the following RDF vocabularies and corresponding namespace prefix bindings:
| Prefix | Namespace | Description |
|---|---|---|
xs
| http://www.w3.org/2001/XMLSchema# | [XMLSCHEMA11-1] |
as
| https://www.w3.org/ns/activitystreams# | [ACTIVITYSTREAMS-VOCABULARY] |
1. Introduction
This section is non-normative.
Solid [SOLID] uses linked data to interconnect data across decentralized data stores called PODS. Per Resource Events Protocol [PREP] allows servers to transmit notifications over HTTP that can be customized for any given resource. This specification defines representation and semantics for PREP notifications sent from linked data resources hosted on Solid PODS.
1.1. Audience
This section is non-normative.
This specification is for:
-
Server developers who wish to enable clients to listen for updates to LDP Resources on Solid PODS.
-
Application developers who wish to implement a client to listen for updates to LDP Resources on Solid PODS.
2. Request
A Solid server implementing Per Resource Events Protocol on an LDP Resource MUST accept requests [PREP] when the `accept` event-field associated with the `PREP` list item in the Accept-Events header field indicates a preferred media type of `application/ld+json` [JSON-LD11].
3. Format
A Solid server implementing Per Resource Events Protocol on an LDP Resource MUST be able to transmit PREP notifications using the `application/ld+json` [JSON-LD11] media type. It MAY also support other media types to transmit PREP notifications.
4. Triggers
A Solid server implementing the Per Resource Events Protocol on an LDP Resource SHOULD send a PREP notification when the state of the said resource is modified.
A Solid server MUST NOT transmit a PREP notification before the resource has been modified and a confirmation (if necessary) has been sent to (but might not have been received by) the agent that initiated the resource modification.
The Solid Protocol [SOLID] requires an LDP container’s state is modified when certain HTTP events occur on a contained resource. Thus, an HTTP event on a resource can trigger a Solid server to transmit a PREP notification on that resource or its container or both.
It follows that a Solid server ought to send PREP notification(s) on an resource and/or its container, when a request with one of the following HTTP methods generates a response with any of the following HTTP status codes:
| Request Method | Response Status | Notify | |
|---|---|---|---|
| Resource | Container | ||
PUT
| 200 (OK)
| ✓ | ✓ |
201 (Created)
| ✓ | ||
POST
| 200 (OK)
| ✓ | ✓ |
201 (Created)
| ✓ | ||
DELETE
| 200 (OK)
| ✓ | ✓ |
Additionally, a Solid server ought to send PREP notification(s) on a resource and/or its container when modified at a later time as result of HTTP request that generates a 202 (Accepted) status code.
A Solid server needs to ensure that a PREP notification is not transmitted before a response has been sent to the user agent that initiated the HTTP request that triggered the said notification.
5. Data Model
The core notification data is expressed with the Activity Streams [ACTIVITYSTREAMS-VOCABULARY] and Solid Notifications [SOLID-NOTIFICATIONS] vocabularies.
5.1. Properties
A PREP notification from an LDP Resource on a Solid server MUST have the following properties:
id <xs:string>- an opaque identifier for the notification. Can be used to set `Last-Event-ID` in a subsequent PREP notifications request.
type <as:Activity>- the type of activity that triggered the notification.
published <xs:dateTime>- the date and time of the notification.
A PREP notification from an LDP Resource on a Solid server SHOULD have the following properties:
state <xs:string>- an opaque identifier for the last known state of the resource.
5.2. Extended Content
A Solid server MAY augment the JSON-LD Context [JSON-LD11] definition and extend the content of notifications.
NOTE: See examples of using multiple vocabularies in the Activity Streams [ACTIVITYSTREAMS-CORE] specification.
6. Activity Mapping
A Solid server sending a PREP notification as a result of some activity on an LDP Resource MUST set the type property as the type of activity that triggered the notification as specified by the Activity Streams vocabulary [ACTIVITYSTREAMS-VOCABULARY].
When an LDP resource is modified by virtue of an HTTP request, the activity type ought to be set as follows:
-
When the PREP notification is triggered by a request on the resource with one of the following HTTP methods:
Activity Mapping for LDP Resources Request Method Activity Type PUTas:UpdatePATCHPOSTDELETEas:Delete
-
When the PREP notification is triggered by a request on a contained resource with one of the following HTTP methods:
Activity Mapping for LDP Containers when contained resources change Request Method Activity Type PUTas:UpdatePATCHPOSTDELETEas:Remove
-
When the PREP notification is triggered by a request to create a new resource inside that container (resource) with one of the following HTTP methods:
Activity Mapping for LDP Containers when contained resources are created Request Method Activity Type PUTas:AddPATCH
Considerations
This section is non-normative.
This section details security and privacy considerations.
Some of the normative references within 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.
Since Solid-PREP defines representation and semantics for the use of Per Resource Events Protocol to transmit notifications from Solid resources, it follows that the Solid-PREP inherits security and privacy considerations of both the Per Resource Events Protocol and the Solid Protocol. Considerations relevant to the use of Per Resource Events Protocol for transmitting notifications are discussed in [PREP] § 11 Considerations, and considerations relevant to Solid Protocol are discussed in [SOLID] § 10 Considerations.
Security Considerations
This section is non-normative.
Solid servers are strongly discouraged from exposing information beyond the minimum amount necessary in a notification. Solid clients are strongly discouraged from exposing information beyond the minimum amount necessary to receive notifications from particular resources.
Solid clients are discouraged from sending requests for notifications to untrusted Solid servers, including localhost or any other loopback IP address, in order to avoid making arbitrary requests.