Linked Data Notifications

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 document Social Web Protocols.

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.

The sender discovers where to deliver the notification based on the addressee or subject of the notification (the receiver) who advertises the appropriate location to send it to (the Inbox). The receiver also 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.

Senders and consumers discover a resource's Inbox URL(s) through a relation in the HTTP Link header or body of the resource.

The Sender:

• Creates the body of the notification according to the needs of application.
• Sends the notification to the Inbox URL by making a POST request, containing the body in JSON-LD or in another serialization acceptable by the server.

The Consumer:

• Retrieves the contents of the Inbox URL with a GET request, and uses according to the needs of application.

The Receiver:

• Responds to GET requests made to the Inbox URL with a JSON-LD representation (or if possible, requested serialization) of the URLs of the notifications that have previously been sent to the Inbox.
• Accepts POST requests at the Inbox URL to create notifications.
• Optionally enforces constraints on notifications sent to the Inbox.

An Inbox, the endpoint which notifications are sent to or consumed from, can be discovered from any resource, for example a blog post, a dataset, a user profile. The starting point for discovery is the resource which the notification is to or about: the target. Choosing the most appropriate target resource from which to begin discovery is at the discretion of the sender or consumer.

To discover the Inbox URL, senders and consumers MUST:

• make a HEAD request on the target URL, to check for an HTTP Link header with a rel value of http://www.w3.org/ns/ldp#inbox
• fetch the target URL (and follow redirects) and use the object URI(s) of the predicate http://www.w3.org/ns/ldp#inbox in RDF Sources [LDP-RS]

These may be carried out in either order, but if the first fails to result in an Inbox the second MUST be tried.

A resource MUST advertise only one Inbox. One Inbox MAY 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.

HEAD /profile HTTP/1.1
Host: user.example

HTTP/1.1 200 OK
Link: <https://user.example/inbox/>; rel="http://www.w3.org/ns/ldp#inbox"
                            

GET /profile HTTP/1.1
Host: user.example
Accept: application/ld+json

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

{
  "@context": "https://www.w3.org/ns/ldp",
  "@id": "https://user.example/profile",
  "inbox": "https://user.example/inbox/"
}
                            

GET /profile HTTP/1.1
Host: user.example
Accept: text/html

HTTP/1.1 200 OK
Content-Type: text/html

<a href="/inbox/" rel="http://www.w3.org/ns/ldp#inbox">My inbox</a>

                            

The sender MUST discover the Inbox through the ldp:inbox relation either through a HEAD request or in response body (see discovery).

Senders MUST deliver notifications through a POST request to the Inbox URL. Senders can expect a 201 Created (with a Location Link header) in response to a successful request.

The sender MAY use an OPTIONS request to determine the RDF content types accepted by the server, and serialize the notification in the request body according to the value of the Accept-Post header [Accept-Post] returned. Otherwise, the body of the POST request MUST contain the notification payload in JSON-LD.

The sender MAY include additional headers or content for the purposes of authentication or authorization e.g., Authorization: Bearer XXX.

Request:

POST /inbox/ HTTP/1.1
Host: user.example
Content-Type: application/ld+json

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "@id": "",
  "@type": "Announce",
  "actor": { "@id": "https://example.org/profile#alice" },
  "object": { "@id": "https://example.org/annotation-1" },
  "target": { "@id": "https://user.example/article#introduction" },
  "updated": "2016-06-23T15:03:01Z"
}
                            

Response:

HTTP/1.1 201 Created
Location: https://user.example/inbox/notification-1
                            

Consumers retrieve the URIs of notifications in an Inbox through making a GET request on the Inbox URL (to find this URL, see discovery).

The URIs of the notifications MUST be discoverable through the ldp:contains predicate of the Inbox URL.

When retrieving individual notifications, the consumer MAY send an Accept header to indicate preferred content types. If no Accept header is sent, or the receiver cannot comply with the content type requested, the consumer MUST accept JSON-LD. Fetching the notifications — if any, how many, or according to a particular criteria (e.g., content-length, timestamp) — is at the discretion of the consumer.

The consumer MAY include additional headers or content for the purposes of authentication or authorization.

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

Receivers MUST support GET and POST requests on the Inbox URL. In LDP terms, an Inbox is a Container.

HEAD /inbox/ HTTP/1.1
Host: user.example

HTTP/1.1 200 OK
Allow: HEAD, GET, POST
Accept-Post: application/ld+json, text/turtle

POST /inbox/ HTTP/1.1
Host: user.example
Content-Type: application/ld+json

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "@id": "",
  "@type": "Announce",
  "actor": { "@id": "https://example.org/profile#alice" },
  "object": { "@id": "https://example.org/annotation-1" },
  "target": { "@id": "https://user.example/article#introduction" },
  "updated": "2016-06-23T15:03:01Z",
}

HTTP/1.1 201 Created
Location: https://user.example/inbox/notification-2
                                    

{
  "@context": "https://www.w3.org/ns/ldp",
  "@id": "https://user.example/inbox/",
  "contains": [
    { "@id": "https://user.example/inbox/notification-1" },
    { "@id": "https://user.example/inbox/notification-2" }
  ]
}
                                    

This section is non-normative. Here are some examples of notification content:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "@id": "https://example.org/note",
  "inReplyTo": "https://example.net/article"
}
                                    

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "@id": "",
  "@type": "Announce",
  "actor": { "@id": "https://example.org/profile#alice" },
  "object": { "@id": "https://example.org/annotation-1" },
  "target": { "@id": "https://user.example/article#introduction" },
  "updated": "2016-06-23T15:03:01Z"
}

                                    

{
  "@id": "",
  "@type": "http://purl.org/net/pingback/Item",
  "http://purl.org/net/pingback/source":
    { "@id": "https://example.org/annotation-1" },
  "http://purl.org/net/pingback/target":
    { "@id": "https://user.example/article#introduction" }
}

                                    

{
  "@context": [
    { "sioc": "http://rdfs.org/sioc/ns#" },
    { "foaf": "http://xmlns.com/foaf/0.1/" }
  ],
  "@id": "",
  "@type": "sioc:Comment",
  "sioc:reply_of": { "@id": "https://user.example/article" },
  "sioc:created_at": "2015-12-23T16:44:21Z",
  "sioc:content" : "This is a great article!",
  "sioc:has_creator": {
    "@id": "https://example.org/profile/",
    "@type": "sioc:UserAccount",
    "sioc:account_of": { "@id": "https://example.org/profile#alice" },
    "sioc:avatar": { "@id": "https://example.org/profile/avatar.png" },
    "foaf:name": "Alice"
  }
}
                                    

Inbox URLs can announce their own shape constraints (e.g., SHACL, Web Annotation Protocol) via an HTTP Link header with a rel value of http://www.w3.org/ns/ldp#constrainedBy at a target URL. Senders should comply with constraint specifications or the receiver may reject their notification.

Given the nature of the notification payload, consumers may want to take precautions when ascertaining the veracity of the contents. The open-world assumption applies here.

Receivers SHOULD ensure or 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
• retrieve a copy of the notification from the sender's domain to verify its origin
• checking a digital signature which accompanies the notification

Receivers SHOULD use constraints to filter unwarranted notifications from being created on the server and exposed by the Inbox. Consumers MAY also want to check the notifications against any constraints as announced by an Inbox before further processing or use.

If the sender has any services that listen on localhost that don't require authentication, it's possible for a malicious script to run at the Inbox endpoint that could cause the sender to make an arbitrary POST request to itself. Senders SHOULD NOT make POST requests to the Inbox that are localhost or a loopback IP address.

Receivers could consider implementing access control on the Inbox URL to restrict writing to a whitelist of trusted senders.

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.

• Improve examples; update, syntactical fixes, @context in https
• Typos, punctuation, naming
• Use informative discretion about the payload