Linked Data Notifications is a protocol that describes how servers (receivers) can have messages pushed to them by applications (senders), as well as how other applications (consumers) may retrieve those messages. Any resource can advertise a receiving endpoint (Inbox) for the messages. Messages are expressed in RDF, and can contain any data.
Status of This Document
Status Update (May 2017): Links in theoverview diagram were fixed in-place on May 22 2017: they were pointing to incorrect internal anchors.
Status Update (Sep 2017): A concept URI was fixed in-place on Sep 5 22 2017: it was pointing to incorrect internal URI.
Data on the Web should not be locked in to particular systems or be only readable by the applications which created it. Users should be free to switch between applications and share data between them. Applications generate notifications about activities, interactions, and new information, which may be presented to the user or processed further.
Linked Data Notifications (LDN) supports sharing and reuse of notificationsacross 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. The protocol is intended to allow senders, receivers and consumers of notifications, which are independently implemented and run on different technology stacks, to seamlessly work together, contributing to decentralisation of our interactions on the Web.
Instead of treating notifications as ephemeral or non-persistent entities, this specification enables the notion of a notification as an individual entity with its own URI. As such, notifications can be retrieved and reused. We support a range of different application domains, social and otherwise, thus the contents of notifications are left up to applications to define. Authentication and verification of notifications is encouraged, but the mechanism to do so is at the discretion of receivers and consumers, as needs differ according to types of notification and different application domains.
1.1Social Web Working Group
LDN is one of several related specifications being produced by the Social Web Working Group. Implementers interested in alternative approaches and complimentary protocols should start by reading the overview documentSocial Web Protocols. Specific subsections of Social Web Protocols are referenced throughout this specification to highlight points of extensibility or interoperability with other protocols.
1.2Overview
Overview of Linked Data Notifications
A sender is triggered, either by a human or an automatic process, to deliver a notification to a server. The notification is data intended for the attention of the receiver, for example: a personal message from a friend; a pingback link; a comment on a blog post; an invitation to collaborate; a calendar reminder; a scientific observation.
The sender chooses a target resource to send notifications to; the sender then discovers the location of the target’sInbox, and sends the notification there. Any resource can advertise an Inbox. The receiver exposes the notification data (according to appropriate access control) for use by consumers.
Consumers discover the location of the Inbox in the same way as the sender, and may perform further processing on the notifications, combine it with some other data, or simply present it in a suitable human-readable way.
1.3Summary
Senders and consumersdiscover a resource’sInbox URL through a relation in the HTTPLink header or body of the resource.
Retrieves the contents of the Inbox URL with aGET request, and uses according to the needs of application.
1.4Relation to Linked Data Platform
LDN is a specialized use of Linked Data Platform [LDP] for sending and consuming notifications. It is not dependent on a complete implementation of LDP, but an easy-to-implement subset. Having knowledge of LDP is not required to understand this specification, but those who do will find some concepts familiar. We describe the particular features necessary to make it easy to exchange notifications in a decentralised, interoperable way. An LDN Inbox is comparable to an LDPBasicContainer.
2.Conformance
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative.
2.1Conformance Classes
LDN implementations may besenders,receivers orconsumers. The conformance criteria for each of these roles are described in their respective sections of this specification.
3.Protocol
This section describes the discovery of the URL to which notifications are delivered or read from (theInbox) and the delivery mechanism. Notification contents are described inPayload.
3.1Discovery
AnInbox, the endpoint to which notifications are sent or from which they are consumed, can be discovered from any resource, for example a blog post, a user profile, a dataset, a video. The starting point for discovery is the resource which the notification is to or about: thetarget. Choosing the most appropriate target resource from which to begin discovery is at the discretion of the sender or consumer, since any resource (RDF or non-RDF) may have its own Inbox.
Senders and consumers do the following to discover the Inbox URL:
make an HTTPHEAD orGET request on the target URL, and use theLink header with arel value ofhttp://www.w3.org/ns/ldp#inbox.
make an HTTPGET request on the target URL to retrieve an RDF representation [RDF 1.1], whose encoded RDF graph contains a relation of typehttp://www.w3.org/ns/ldp#inbox. The subject of that relation is target and the object is the Inbox.
These may be carried out in either order, but if the first fails to result in an Inbox the secondMUST be tried. Senders and consumersSHOULD omit theLink header discovery when specifically targeting URIs with fragment identifiers.
Note
If the target contains a fragment identifier, the fragment is not part of the request to the server. Senders and consumers should be aware that any Inbox found in theLink header will be for the resolved URL,without the fragment. See [Cool URIs for the Semantic Web - Hash URIs].
A resourceMUST advertise only one Inbox. One InboxMAY be used by multiple resources, for example using the same Inbox for replies to all of my blog posts and shares of all of my photos.
Discovery example 1: Link header
HEAD /article HTTP/1.1Host: example.orgAccept: application/ld+jsonHTTP/1.1 200 OKLink: <http://example.org/inbox/>; rel="http://www.w3.org/ns/ldp#inbox"
Request and response when discovering an Inbox with aHEAD request, and receiving aLink header.
Discovering an Inbox with aGET request to retrieve JSON-LD. Response in JSON-LD compact form.
Discovery example 3: Visible HTML
GET /event HTTP/1.1Host: example.orgAccept: text/html, application/ld+jsonHTTP/1.1 200 OKContent-Type: text/html;charset=utf-8<p about="http://example.org/event" typeof="http://schema.org/Event" lang="en"> <a rel="http://www.w3.org/ns/ldp#inbox" href="/inbox/">RSVP</a> to event</p>
Discovering an Inbox with aGET request to retrieve HTML. The Inbox link is visible to humans, and marked up with RDFa so the Inbox URL can be discovered by machines.
Discovering an Inbox with aGET request to retrieve HTML. An invisible Inbox expressed with the RDFaproperty attribute, so that a resource identified with a fragment URI may be the target.
Discovering an Inbox with aGET request to retrieve Turtle.
Please seeSocial Web Protocols for recommendations on how to carry out discovery, particularly with consideration to servers which may be unaware of this protocol.
3.2Sender
Followingdiscovery,senders who want to send notificationsMUST deliver them through aPOST request to the Inbox URL. Senders can expect a201 Created (with aLocation Link header) or a202 Accepted in response to a successful request.
The senderMAY use anOPTIONS request to determine the RDF content types accepted by the server, and serialize the notification in the request body according to the value of theAccept-Post header [Accept-Post] returned. Otherwise,the body of thePOST requestMUST contain the notificationpayload in JSON-LD with headerContent-Type: application/ld+json. TheContent-Type headerMAY include aprofile URI [RFC6906].
The senderMAY include additional headers or content for the purposes of authentication or authorization e.g.,Authorization: Bearer XXX.
If the sender has any services that listen on localhost that do not require authentication, it’s possible for a malicious script to run at the Inbox endpoint that could cause the sender to make an arbitraryPOST request to itself. SendersSHOULD NOT makePOST requests to the Inbox that are localhost or a loopback IP address.
ReceiversMUST supportGET andPOST requests on the Inbox URL.In LDP terms, an Inbox is aContainer.
3.3.1Receiving notifications
Upon receipt of aPOST request, if the notification resource was processed successfully, receiversMUST respond with status code201 Created and theLocation header set to the URL from which the notification data can be retrieved (seeConsumer). If the request was queued to be processed asynchronously, the receiverMUST respond with a status code of202 Accepted and include information about the status of the request in the body of the response.
Receivers which enforce constraints on the notifications (seeConstraints)SHOULD fail to process the notification if the constraints are not met and return the appropriate4xx error code.
ReceiversMUST accept notifications where the request body is JSON-LD, with theContent-Type: application/ld+json, whichMAY include aprofile URI [RFC6906].
ReceiversMAY accept other RDF content types (e.g.,text/turtle,text/html), and if so,SHOULD advertise the content types they accept with anAccept-Post [Accept-Post] header in response to anOPTIONS request on the Inbox URL.
Receiver responding to aPOST request on the Inbox by creating a notification.
3.3.2Making Inbox contents available to consumers
A successfulGET request on the InboxMUST return aHTTP 200 OK with the URIs of notifications, subject to the requester’s access (returning4xx error codes as applicable).ReceiversMAY list only URIs of notifications in the Inbox that the consumer is able to access.The Inbox URLMUST use thehttp://www.w3.org/ns/ldp#contains predicate to refer to the notifications.
Each notificationMUST be anRDF source. If non-RDF resources are returned, the consumerMAY ignore them. A successfulGET request on the notification URIMUST return aHTTP 200 OK subject to the requester’s access (returning4xx error codes as applicable).
The JSON-LD content typeMUST be available for all resources, but clients may sendAccept headers preferring other content types (RFC7231 Section 3.4 - Content Negotiation).If the client sends noAccept header, the server may send the data in JSON-LD or any format which faithfully conveys the same information (e.g., Turtle).
Any additional description about the Inbox itselfMAY also be returned (e.g.,Constraints).
Note
This specification does not define a paging mechanism to serve the list of notifications in an Inbox. Implementations that wish to enable paging may want to use existing mechanisms to allow efficient retrievals e.g.,Linked Data Platform Paging 1.0,Activity Streams 2.0 Collection.
Receiver responding to aGET request on the Inbox with a listing of notifications.
3.3.3Sender Verification
ReceiversSHOULD verify the sender of the notification. For example:
by having a whitelist of senders with write access to the Inbox
requiring authentication to enforce receiver’s knowledge of every sender
retrieving a copy of the notification from the sender’s domain to verify its origin
checking a digital signature which accompanies the notification
3.3.4Preventing Abuse
ReceiversSHOULD useconstraints to filter unwarranted notifications from being created on the server and exposed by the Inbox.
Receivers could consider implementing access control on the Inbox URL to restrict writing to a whitelist of trusted senders.
3.4Consumer
Consumers retrieve the URIs of notifications in an Inbox through making aGET request on the Inbox URL (to find this URL, seediscovery).
The URIs of the notificationsMUST be discoverable through thehttp://www.w3.org/ns/ldp#contains predicate of the Inbox URL (seeexample for Inbox content).
When retrieving the Inbox or the individual notifications, the consumerSHOULD explicitly set theAccept header to indicate preferred content types, including for JSON-LD. Fetching the individual notifications — if any, how many, or according to a particular criteria (e.g., content-length, timestamp) — is at the discretion of the consumer.
The consumerMAY include additional headers or content for the purposes of authentication or authorization.
ConsumersMAY perform additional fetching or inferring of information from the payload (e.g., dereferencing resources referenced in the notification to fetch their contents) at their discretion. ConsumersMAY also want to check the notifications against any constraints as announced by an Inbox before further processing or use.
Note
The fetched URI for a notificationmay contain RDF statements with one or more subject IRIsdifferent from the requested URI itself. Consumers should also not assume that the notification containsany triples with the requested URI as the subject. This is also pertinent when the body of the notification uses relative IRIs. Implementations may wish to treat notification URIs as graphs which contain the RDF from the notification payload.
Note
Consumers should be aware that anything can be posted to an Inbox (depending on restrictions in place by the receiver, which are not defined by this protocol), so when it comes to making use of notification data consumers may want to take precautions when ascertaining the veracity of the contents.
Result of a GET request on an individual notification discovered in an Inbox.
4.Payload
The payload of the notificationMUST be JSON-LD unless another RDF syntax has been negotiated with the receiver. To allow for a wide variety of use cases, the actual vocabulary of the payload is deliberately not specified here.
An event RSVP described by the schema.org vocabulary.
A notification may contain arbitrary information, including references to multiple resources with their own URIs, without necessarily referring to one particular external resource or origin for the data. The receiver is expected to return all triples that were initially sent when such a notification is requested by a consumer.
A notification containing data about a comment and the user who created the comment, described by the Semantically Interlinked Online Communities (SIOC) and Friend-of-a-Friend (FOAF) vocabularies.
A changelog entry described by the Provenance vocabulary.
5.Security, Privacy and Content Considerations
This section is non-normative. Normative requirements for security and privacy are called out in the section of the specification to which they are most applicable.
5.1Constraints
Inbox URLs can announce their own constraints (e.g.,SHACL,Web Annotation Protocol) via an HTTPLink header or body of the resource with arel value ofhttp://www.w3.org/ns/ldp#constrainedBy. Senders should comply with constraint specifications or the receiver may reject their notification and return an appropriate4xx error code.
5.2Target Ownership
Publishers of the resources advertising an Inbox (target) should do so on a server they trust. Publishers must be aware that third-party access to headers or content could result in notifications being redirected.
5.3Subscribing to Notifications
This specification describes how consumers can read notifications from a receiver throughpull, however consumers may want to ask to have incoming notifications or changes to Inbox’s contents pushed to them. Similarly, receivers may wish to make a request for notifications from a particular sender. This kind of subscription mechanism is left out of scope, but senders, receivers and consumers are not prohibited from making such an arrangement. Implementations that wish to enable subscribing may want to use existing mechanisms e.g.,ActivityPub,WebSub,The WebSocket Protocol,HTTP Web Push.
Building an international base of users is important in a federated network. Some LDN interactions can return content with natural language text, such as HTML fragments, or summary fields. Providing multiple language representations of each item might not be feasible in all circumstances. Implementations are encouraged to provide means of discovering the available languages and/or negotiating the language returned, such as using the HTTPAccept-Language header to negotiate and select the most appropriate language representation to send for a given request.
5.6Authenticated Inboxes
If a receiver expects senders or consumers to authenticate, it should check the validity of their credentials before returning any other data, including other error codes. For example, the receiver shouldnot first check for the existence of the inbox and return404 Not Found if the requester has not been verified.
Authentication involving token passing must be done over HTTPS.
Notification payloads may contain any data including that which identifies the sender or the receiver. Access to notification data is under the control of the receiver. In the case of sending sensitive information, the sender should be aware that the receiver may implement access control on the Inbox that allows for public reading of the contents.
This specification advanced to Proposed Recommendation with at least two independent, interoperable implementations of each feature. Each feature was implemented by a different set of products. There was no requirement that all features needed to be implemented by a single product.
Independent implementations are developed by different parties and cannot share, reuse or derive form another qualifying implementation code which is directly pertinent to the implementation of this specification.
Interoperability occurs between senders and receivers, or between consumers and receivers, when the sender/consumer makes a request to the receiver, and the receiver sends the expected response, as defined by this specification.
Animplementation is an LDN sender, receiver or consumer which implements the corresponding conformance class of the specification.
For the purposes of evaluating exit criteria, each of the following was considered a feature:
Advertising the Inbox of a given resource through theLink header.
Advertising the Inbox of a given resource through the body of the resource.
Sending a notification to the Inbox of a given target.
Receiving a notification and responding with the appropriate status code according to how it was processed and if it was accepted. Responding toGET requests on the Inbox with the Inbox listing, and responding toGET requests on the individual notifications with their representations.
Reading the Inbox listing of a given target.
Reading the individual notifications in the Inbox of a given target.
B.Acknowledgements
We would like to thank and acknowledge the following people for their contributions to this specification: