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. Specific subsections of Social Web Protocols are referenced throughout this specification to highlight points of extensibility or interoperability with other 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; a scientific observation.

The sender chooses a target resource to send notifications to; the sender then discovers the location of the target’s Inbox, 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.

Senders and consumers discover a resource’s Inbox URL 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 Receiver:

• Responds to GET requests made to the Inbox URL with a listing of the URLs of notifications that have previously been accepted.
• Responds to GET requests made to the individual notification URLs with JSON-LD (or optionally other serializations).
• Accepts POST requests at the Inbox URL to create notifications.
• Optionally enforces constraints on notifications sent to the Inbox.

The Consumer:

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

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

LDN implementations may be senders, receivers or consumers. The conformance criteria for each of these roles are described in their respective sections of this specification.

An Inbox, 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: the target. 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 HTTP HEAD or GET request on the target URL, and use the Link header with a rel value of http://www.w3.org/ns/ldp#inbox.
• make an HTTP GET request on the target URL to retrieve an RDF representation [RDF 1.1], whose encoded RDF graph contains a relation of type http://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 second MUST be tried. Senders and consumers SHOULD omit the Link header discovery when specifically targeting URIs with fragment identifiers.

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 /article HTTP/1.1
Host: example.org
Accept: application/ld+json

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

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

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

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

GET /event HTTP/1.1
Host: example.org
Accept: text/html, application/ld+json

HTTP/1.1 200 OK
Content-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>

GET /article HTTP/1.1
Host: example.org
Accept: text/html, application/ld+json

HTTP/1.1 200 OK
Content-Type: text/html;charset=utf-8

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

GET /article HTTP/1.1
Host: example.org
Accept: text/html, application/ld+json

HTTP/1.1 200 OK
Content-Type: text/html;charset=utf-8

<section id="results" about="#results"
  property="http://www.w3.org/ns/ldp#inbox" resource="/inbox/">
</section>

GET / HTTP/1.1
Host: csarven.ca
Accept: text/turtle, application/ld+json

HTTP/1.1 200 OK
Content-Type: text/turtle;charset=utf-8

<http://csarven.ca/#i>
  <http://www.w3.org/ns/ldp#inbox> <http://csarven.ca/inbox/> .

Please see Social Web Protocols for recommendations on how to carry out discovery, particularly with consideration to servers which may be unaware of this protocol.

Following discovery, senders who want to send notifications MUST deliver them through a POST request to the Inbox URL. Senders can expect a 201 Created (with a Location Link header) or a 202 Accepted 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 with header Content-Type: application/ld+json. The Content-Type header MAY include a profile URI [RFC6906].

The sender MAY 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 arbitrary POST request to itself. Senders SHOULD NOT make POST requests to the Inbox that are localhost or a loopback IP address.

POST /inbox/ HTTP/1.1
Host: example.org
Content-Type: application/ld+json;profile="https://www.w3.org/ns/activitystreams"
Content-Language: en

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "@id": "",
  "@type": "Announce",
  "actor": "https://rhiaro.co.uk/#me",
  "object": "http://example.net/note",
  "target": "http://example.org/article",
  "updated": "2016-06-28T19:56:20.114Z"
}

HTTP/1.1 201 Created
Location: http://example.org/inbox/5c6ca040

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

OPTIONS /inbox/ HTTP/1.1
Host: example.org

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

POST /inbox/ HTTP/1.1
Host: example.org
Content-Type: application/ld+json;profile="https://www.w3.org/ns/activitystreams"
Content-Language: en

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "@id": "",
  "@type": "Announce",
  "actor": "https://rhiaro.co.uk/#me",
  "object": "http://example.net/note",
  "target": "http://example.org/article",
  "updated": "2016-06-28T19:56:20.114Z"
}

HTTP/1.1 201 Created
Location: http://example.org/inbox/92d72f00

GET /inbox/ HTTP/1.1
Host: example.org
Accept: application/ld+json
Accept-Language: en-GB,en;q=0.8, en-US;q=0.6

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

{
  "@context": "http://www.w3.org/ns/ldp",
  "@id": "http://example.org/inbox/",
  "contains": [
    "http://example.org/inbox/5c6ca040",
    "http://example.org/inbox/92d72f00"
  ]
}

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 http://www.w3.org/ns/ldp#contains predicate of the Inbox URL (see example for Inbox content).

When retrieving the Inbox or the individual notifications, the consumer SHOULD explicitly set the Accept 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 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. Consumers MAY also want to check the notifications against any constraints as announced by an Inbox before further processing or use.

GET /inbox/14a792f0 HTTP/1.1
Host: example.org
Accept: application/ld+json, text/turtle, application/xhtml+xml, text/html
Accept-Language: en-GB,en;q=0.8, en-US;q=0.6

HTTP/1.1 200 OK
Content-Type: application/ld+json;profile="https://www.w3.org/ns/activitystreams"
Content-Language: en

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    { "@language": "en" }
  ],
  "@id": "http://example.org/inbox/14a792f0",
  "@type": "Announce",
  "actor": {
    "@id": "http://csarven.ca/#i",
    "name": "Sarven Capadisli"
  },
  "object": {
    "@context": "http://www.w3.org/ns/anno.jsonld",
    "@id": "http://example.net/note",
    "@type": "Annotation",
    "motivation": "http://www.w3.org/ns/oa#assessing",
    "rights": "http://creativecommons.org/licenses/by/4.0/"
  },
  "target": "http://example.org/article",
  "updated": {
    "@type": "http://www.w3.org/2001/XMLSchema#dateTime",
    "@value": "2016-06-28T19:56:20.114Z"
  }
}

This section is non-normative.

{
  "@context": "http://schema.org/",
  "@id": "http://example.net/note#foo",
  "citation": { "@id": "http://example.org/article#results" }
}

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "@id": "",
  "@type": "Announce",
  "actor": "https://rhiaro.co.uk/#me",
  "object": "http://example.net/note",
  "target": "http://example.org/article",
  "updated": "2016-06-28T19:56:20.114Z"
}

{
  "@context": { "pingback": "http://purl.org/net/pingback/" },
  "@id": "",
  "@type": "pingback:Item",
  "pingback:source": { "@id": "http://example.net/note#foo" },
  "pingback:target": { "@id": "http://example.org/article#results" }
}

{
  "@context": "http://schema.org/",
  "@id": "",
  "@type": "RsvpAction",
  "event": { "@id": "http://example.org/event" },
  "agent": { "@id": "https://rhiaro.co.uk/#me" }
}

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.

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

{
  "@context": [{"prov": "http://www.w3.org/ns/prov#"}],
  "@id": "http://example.org/activity/804c4e7efaa828e146b4ada1c805617ffbc79dc7",
  "@type": "prov:Activity",
  "http://www.w3.org/2000/01/rdf-schema#label": {
    "@language": "en",
    "@value": "Make it so"
  },
  "prov:endedAtTime": {
    "@type": "http://www.w3.org/2001/XMLSchema#dateTime",
    "@value": "2016-06-14T20:57:39.000Z"
  },
  "prov:generated": {
    "@id": "http://example.org/entity/804c4e7efaa828e146b4ada1c805617ffbc79dc7",
    "@type": "prov:Entity",
    "prov:specializationOf": { "@id": "http://example.org/entity/file" },
    "prov:wasGeneratedBy": {
      "@id": "http://example.org/activity/804c4e7efaa828e146b4ada1c805617ffbc79dc7"
    }
  },
  "prov:wasAssociatedWith": {
    "@id": "http://csarven.ca/#i",
    "@type": "prov:Agent",
    "http://xmlns.com/foaf/0.1/name": {
      "@language": "hy",
      "@value": "Սարվէն Չափատիշլի"
    }
  }
}

Inbox URLs can announce their own constraints (e.g., SHACL, Web Annotation Protocol) via an HTTP Link header or body of the resource with a rel value of http://www.w3.org/ns/ldp#constrainedBy. Senders should comply with constraint specifications or the receiver may reject their notification and return an appropriate 4xx error code.

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.

This specification describes how consumers can read notifications from a receiver through pull, 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.

Receiver implementations that wish to support Activity Streams 2.0 Core can see Social Web Protocols - Inbox Interop for Content-Type and vocabulary equivalences.

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 HTTP Accept-Language header to negotiate and select the most appropriate language representation to send for a given request.

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 should not first check for the existence of the inbox and return 404 Not Found if the requester has not been verified.

Authentication involving token passing must be done over HTTPS.

These questions provide an overview of security and privacy considerations for this specification as guided by Self-Review Questionnaire: Security and Privacy.

Does this specification deal with personally-identifiable information?

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.

Does this specification deal with high-value data?

Same implications as personally-identifiable information in notification payload (as mentioned above).

Does this specification introduce new state for an origin that persists across browsing sessions?

No.

Does this specification expose persistent, cross-origin state to the web?

No.

Does this specification expose any other data to an origin that it doesn’t currently have access to?

No.

Does this specification enable new script execution/loading mechanisms?

No.

Does this specification allow an origin access to a user’s location?

No.

Does this specification allow an origin access to sensors on a user’s device?

No.

Does this specification allow an origin access to aspects of a user’s local computing environment?

No.

Does this specification allow an origin access to other devices?

No.

Does this specification allow an origin some measure of control over a user agent’s native UI?

No.

Does this specification expose temporary identifiers to the web?

No.

Does this specification distinguish between behavior in first-party and third-party contexts?

No.

How should this specification work in the context of a user agent’s "incognito" mode?

Works in such a way that the website would not be able to determine that the user was in "incognito".

Does this specification persist data to a user’s local device?

No.

Does this specification have a "Security Considerations" and "Privacy Considerations" section?

:)

Does this specification allow downgrading default security characteristics?

No.

• Fix a syntax error in an example
• Add 'in reply to' link to Social Web Group Charter
• Add links to past versions of the spec
• Update references

• Update acknowledgements

• Add Acknowledgements
• Clarify the implied response codes for notifications and request URI in note
• Update references

• Add Natural Language Content section under Considerations
• Fix reference to PubSub
• Add URLs to implementation reports and test suite
• Add legend to SVG
• Fix AS2 bib fragment
• Reword payload verification
• Added 'Authenticated Inboxes' security guidance

• Add and update examples
• Improve discovery wording for HTTP HEAD/GET
• Editorial; grammar, paraphrasing
• Fix Accept-Post reference and be explicit about its appearance in OPTIONS
• Integrate feedback from internationalisation review (examples)

• Fix typos and links
• Reorder sections to Sending, Receiving, Consuming
• Update examples
• Add reference to RFC7231
• Clarify wording for URI discovery
• Add sub-headings for the non-normative sections under Considerations
• Add overview diagram
• Add non-normative sub-section for Retry Discovery under Considerations
• Mention being courteous for Discovery
• Move Preventing Abuse to respective normative sections
• Move Sender Verification to go under Receiving
• Move ActivitStreams 2.0 Support to Considerations
• Move Payload Verification to Consuming as a Note
• Move normative and some non-normatives from Considerations to earlier sections
• Add Security and Privacy Review section
• Update Introduction

• Typos, punctuation, naming
• Add Exit Criteria
• Clarify behaviour when Accept header is used and omitted
• Add a note about subject of the relation for the Link header field
• Add GET for possible Link header, clarify subject URI (for its Inbox) in target URL
• Revise Abstract
• Add consideration about target ownership
• Mention 'any resource can have its own inbox'
• Add Subscribing to Notifications section

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