Social Web Protocols

2.1 Contents

This is an overview of the specifications of the Social Web Working Group.

Due to the diversity of viable technical approaches proposed within the Working Group, several specifications reached recommendation which provide overlapping functionality through differing mechanisms. This document exists to provide informative guidance on how and when to implement the various specifications, as well as some hints towards routes to bridging between similar specifications.

2.2 Definitions

This document is divided into five sections, pertaining to the components above, and derived from the Social API Requirements. The various Social Web Working Group specifications implement different combinations of these requirements (see 2.3.1 Requirements) so for clarity the requirement are defined here.

reading

covers specifications which describe the syntax and vocabulary to be used for social content. Useful for applications which expose feeds, as well as those which consume them.

publishing

covers Social API specifications which tell clients how to instruct servers to create, update or delete content.

subscribing

covers Federation Protocol specifications which describe how to ask for notifications about content, and subsequently how those notifications should be delivered.

delivery

covers Federation Protocol specifications which describe how to deliver notifications which have not been solicited through subscription.

profiles

covers specifications which describe profiles.

2.3 Specifications

These are the specifications produced by the Social Web Working Group. New implementation reports and feedback are always welcome (details for where to submit these are at the top of each document).

[Activitypub]

JSON(-LD)-based APIs for client-to-server interactions (ie. publishing) and server-to-server interactions (ie. federation).

ActivityStreams 2.0 [activitystreams-core] and [activitystreams-vocabulary]

The syntax and vocabulary for representing social activities, actors, objects, and collections in JSON(-LD).

Linked Data Notifications ([LDN])

A JSON-LD-based protocol for delivery.

[Micropub]

A form-encoding and JSON-based API for client-to-server interactions (ie. publishing).

[Webmention]

A form-encoding-based protocol for delivery.

[WebSub]

A protocol for subscription to any resource and delivery of updates about it.

Specifications which are not Social Web Working Group recommendations, but which are nonetheless relevent to the charter deliverables, are described in 8. Related specifcations.

3.1 Content representation

ActivityStreams 2.0 is the recommended syntax ([activitystreams-core]) and vocabulary ([activitystreams-vocabulary]) for social data. ActivityStreams 2.0 represents content and interactions as Objects and Activities. The ActivityStreams vocabulary defines a finite set of common Object and Activity types and properties, as well as an extension mechanism for applications which want to expand on or specialise these.

ActivityStreams 2.0 content is served with the Content-Type application/activity+json or for JSON-LD extended implementations, application/ld+json; profile="https://www.w3.org/ns/activitystreams". Consumers should recognise both of these Content-Types as ActivityStreams 2.0; they should be treated as equivalent.

In order to claim ActivityStreams 2.0 conformance, a data publisher must use ActivityStreams 2.0 vocabulary terms where available, and only use other vocabularies in addition, or where no appropriate ActivityStreams 2.0 term exists.

To make content available as ActivityStreams 2.0 JSON, one could do so directly when requested with an appropriate Accept header (eg. application/activity+json or application/ld+json), or indirectly via a rel="alternate" type="application/activity+json" link . This link could be to a different domain, for third-party services which dynamically generate ActivityStreams 2.0 JSON on behalf of a publisher.

[Activitypub] uses ActivityStreams 2.0 for all data, and also extends ActivityStreams 2.0 with additional terms. Thus, ActivityPub requires responses to have the Content-Type application/ld+json; profile="https://www.w3.org/ns/activitystreams". Publishers are however expected to also respect requests with the application/activity+json Accept header.

3.2 Objects

All ActivityStreams 2.0 objects have URLs in the id property, which return the properties of an object. The response may vary depending on the requester's right to access the content.

3.3 Collections

Each ActivityStreams 2.0 collection has a URL in the id property which returns the contents of the stream (according to the requester's right to access). This could be paged - ActivityStreams 2.0 provides a paging mechanism. It may include additional metadata about the stream (such as title, description).

Each object in a collection contains at least its URL (id), as well as optionally other properties of the object.

Collections may represent changing streams of objects, or fixed sets. One profile may be associated with one or more streams of content. Streams may be generated automatically or manually, and might be segregated by post type, topic, audience, or any arbitrary criteria decided by the curator of the stream. A profile may include links to multiple streams, which a consumer could follow to read or subscribe to.

4.1 Creating

The publishing endpoint of [Activitypub] is the outbox. Clients are assumed to have the URL of a (ideally authenticated) profile as a starting point, and discover the value of the https://www.w3.org/ns/activitystreams#outbox property found at the profile URL (which should be available as JSON). The client then makes an HTTP POST request with an ActivityStreams 2.0 activity or object as a JSON payload with a content type of application/ld+json; profile="https://www.w3.org/ns/activitystreams". The URL of the created resource is generated at the discretion of the server, and returned in the Location HTTP header. This is an appropriate protocol to use when:

• You want to send/receive a JSON or JSON-LD payload.
• Your data is described with [activitystreams-core] and [activitystreams-vocabulary] (optionally extensible via JSON-LD).
• You want servers to carry out a known set of actions upon content creation.

Side-effects of creating content with ActivityPub are for the most part adding things to various different collections collections (likes, follows, etc); but also include requirements about blocking users, and a hook to enable federated servers.

The publishing endpoint for [Micropub] is the micropub endpoint. Clients discover this from a profile URL via a rel="micropub" link (in an HTTP Link header, or an HTML <link> element). Clients make a x-www-form-urlencoded POST request containing the key-value pairs for the attributes of the object being created. The URL of the created resource is generated at the discretion of the server, and returned in the Location HTTP header. Clients and servers must support attributes from the Microformats2 [h-entry] vocabulary. Micropub also defines four reserved attributes (access_token, h, action and url) as well as reserves any attribute prefixed with mp-; these are used as commands to the server. Any additional key names sent outside of these vocabularies may be ignored by the server.

Micropub requests may alternatively be sent as a JSON payload, the syntax of which is derived from [microformats2-parsing].

This is an appropriate protocol to use when:

• You want to send/receive a form-encoded or JSON payload.
• Your data is described with the [h-entry] syntax and vocabulary.
• You can rely on out-of-band agreements between clients and servers for vocabulary extensibility.

4.2 Updating

Content is updated when a client sends changes to attributes (additions, removals, replacements) to an existing object.

[Activitypub] clients send an HTTP POST request to the outbox containing an ActivityStreams 2.0 Update activity. The object of the activity is an existing object, including its id, and the fields to update should be nested. If a partial representation of an object is sent, omitted fields are not deleted by the server. In order to delete specific fields, the client can assign them a null value.

In the case of ActivityPub federated servers, updates should be propagated to the inboxes of recipients of the original objects. However, when a federated server passes an Update activity to another server's inbox, the recipient must assume this is the complete object to be replaced; partial updates are not performed server-to-server.

An Undo with the object of the previous Update can be used to revert changes.

[Micropub] clients perform updates as JSON POST requests, using the "action": "update" directive, as well as a replace, add or delete property containing the updates to make, to the Micropub endpoint. replace replaces all values of the specified property; if the property does not exist already, it is created. add adds new values to the specified property without changing the existing ones; if the property does not exist already, it is created. delete removes the specified property; you can also remove properties by value by specifying the value.

If a server also implements [Webmention] it should propagate the updates to anyone who received Webmentions for the original.

If a server also implements [WebSub], and the updated resource is part of a topic, the server should notify the hub of an update to the topic URL.

4.3 Deleting

Content is deleted when a client sends a request to delete an existing object.

[Activitypub] clients delete an object by sending an HTTP POST request containing an ActivityStreams 2.0 Delete activity to the outbox of the authenticated user. Servers must either replace the object of this activity with a tombstone and return a 410 Gone status code, or return a 404 Not Found, from its URL.

An Undo with the object of the previous Delete may be used to restore the object.

[Micropub] delete requests are two key-value pairs, JSON: "action": "delete" and "url": url-to-be-deleted, sent to the Micropub endpoint. Posts may be resotred with "action": "undelete".

As with updating, servers implementing ActivityPub federation, Webmention or WebSub should propagate deletes accordingly.

5.1 Subscribing with as:Follow

[Activitypub] servers maintain a Followers collection for all users. This collection may be directly addressed, or addressed automatically or by default, in the to, cc or bcc field of any Activity. As a result, federated servers deliver the Activity to the inbox of each profile in the collection.

Subscription requests are essentially requests to be added to this collection. They are made by the subscriber's server POSTing a Follow Activity to the target's inbox. This request should be authenticated, and therefore doesn't need additional verification. The target server then should add the subscriber to the target's Followers collection. Exceptions may be made if, for example, the target has blocked the subscriber.

This is a suitable subscription mechanism when:

• The subscriber wants to request updates from a specific profile's outbox (rather than objects, streams, feeds, collections, conversation threads).
• The subscriber and publisher both speak ActivityStreams 2.0.
• The publisher is aware of who has subscribed, and capable of delivering content to subscribers itself.

Since delivery is only a requirement for federated servers, prospective subscribers will not be able to POST their Follow activity to the inbox of a profile which is on a non-federated server (expect a 405 Method Not Allowed), and thus are not able to subscribe to these profiles. In this case, prospective subscribers may wish to periodically pull from the publisher's outbox instead.

5.2 Subscribing with a hub

[WebSub] provides a mechanism to delegate subscription handling and delivery of content to subscribers to a third-party, called a hub. All publishers need to do is link to their chosen hub(s) using HTTP Link headers or HTML <link> elements with rel="hub", and then notify the hub when new content is available. The mechanism for notifying the hub is left deliberately unspecified, as publishers may have their own built in hub, and therefore use an internal mechanism.

The subscriber discovers the hub from the publisher, and sends a form-encoded POST request containing values for hub.mode ("subscribe"), hub.topic (the URL to subscribe to) and hub.callback (the URL where updates should be sent to, which should be 'unguessable' and unique per subscription). The hub and subscriber carry out a series of exchanges to verify this request.

When the hub is notified of new content by the publisher, the hub fetches the content of the topic URL, and sends this to the subscriber's callback URL via a POST request. The body of the request is the content of the topic URL, and the Content-Type must match. A rel=hub Link header should be included.

This is a suitable subscription mechanism when:

• The subscriber wants to request updates from any resource (not just user profiles), and of any content type.
• Subscription requests are not authenticated, so you need a way to verify them.
• The publisher wants to delegate distribution of updates to another service (the hub) instead of doing it itself.

6.1 Targeting and discovery

The target of a notification is usually the addressee or the subject, as referenced by a URL. The target may also a resource which has previously requested notifications through a subscription request. Once you have determined your target, you need to discover where to send the notification for that particular target. Discovery is fetching the target URL and looking for a link to an endpoint which will accept the type of notification you want to send (read on, for all of your exciting options).

Bear in mind that many potential targets will not be configured to receive notifications at all. To avoid overloading unsuspecting servers with discovery-related requests, your application should employ a "back-off" strategy when carrying out discovery multiple times to targets on the same domin. This could involve increasing the period of time between subsequent requests, or caching unsuccessful discovery attempts so those domains can be avoided in future. You may wish to send a User-Agent header with a reference to the notification mechanism you are using so that recipient servers can find out more about the purpose of your requests.

Your application should also respect relevant cache control and retry headers returned by the target server.

6.2 Generic notifications

[LDN] is a federation protocol for sending, receiving and consuming notifications which may contain any content, and be triggered by any person or process. Senders, receivers and consumers can all be on different domains. This is a suitable notification mechanism when:

• Notifications need to be identifiable with their own URLs and exposed by the receiver for other applications to discover and re-use.
• Notifications are represented as a JSON-LD payload (ie. a 'fat ping').
• You need to advertise constraints on the type or contents of notifications accepted by a receiver.

[LDN] functionality is divided between senders, receivers and consumers. The endpoint to which notifications are sent is the inbox. Any resource (a user profile, blog post, document) can advertise its inbox so that it may be discovered through an HTTP Link header or the document body in any RDF syntax (including JSON-LD or HTML+RDFa). To this Inbox, senders make a POST request containing the JSON-LD (or other RDF syntax per [Accept-Post] negotation with the receiver) payload of the notification. The receiver returns a URL from which the notification data can be retrieved, and also adds this URL to a list which is returned upon a GET request to the Inbox (see 3. Reading). Consumers can retrieve this Inbox listing, and from there the individual notifications, as JSON-LD (optionally content negotiated to another RDF syntax). An obvious type of consumer is a script which displays notifications in a human-readable way.

The payload of notifications is deliberately left open so that LDN may be used in a wide variety of use cases. However, receivers with particular purposes are likely to want to constrain the types of notifications they accept. They can do this transparently (such that senders are able to attempt to conform, rather than having their requests rejected opaquely) by advertising data shapes constraints such as [SHACL]. Advertisement of such constraints also allows consumers to understand the types of notifications in the Inbox before attempting to retrieve them. Receivers may reject notifications on the basis of internal, undisclosed constraints, and may also access control the Inbox for example by requiring an Authorization header from both senders and consumers.

[WebSub] publishers deliver content to their hub, and hubs to their subscribers using HTTP POST requests. The body of the request is left to the discretion of the sender in the first case, and in the latter case must match the Content-Type of and contain contents from the topic URL.

6.3 Activity notifications

[Activitypub] uses [LDN] to send notifications with some specific constraints. These are:

• The notification payload MUST be a single ActivityStreams 2.0 Activity.
• The notification payload MUST be compact JSON-LD.
• The receiver MUST verify the notification by fetching its source from the origin server.
• All notification POST requests are authenticated.

[Activitypub] specifies how to define the target(s) to which a notification is to be sent (a pre-requisite to [LDN] sending), via the [activitystreams-vocabulary] audience targeting and object linking properties.

[Activitypub] also defines side-effects that must be carried out by the server as a result of notification receipt. These include:

• Creating, updating or deleting new objects upon receipt of Create, Update and Delete activities.
• Reversing the side-effects of prior activities upon receipt of the Undo activity.
• Updating specialised collections for Follow, Like and Block activities.
• Updating any other collections upon receipt of Add and Remove activities.
• Carrying out further delivery to propagate activities through the network in the case of federated servers.

6.4 Mentioning

[Webmention] provides an API for sending and receiving notifications when a relationship is created (or updated, or deleted) between two documents. A webmention sender is triggered by the creation (or modification) of content which includes the URL of another document. It works when the two documents are on different domains, thus serving as a federation protocol. This is a suitable notification mechanism when:

• You have a document (source) which contains the URL of another document (target).
• The owner of the endpoint has access to view the source (so the request can be verified).
• The only data you need to send over the wire are the URLs of the source and target documents (ie. a 'thin ping').

There are no constraints on the syntax of the source and target documents. Discovery of the [Webmention] endpoint (a script which can process incoming webmentions) is through a link relation (rel="webmention"), either in the HTTP Link header or HTML body of the target. This endpoint does not need to be on the same domain as the target, so webmention receiving can be delegated to a third party.

Webmentions are verified by the server dereferencing the source and parsing it to check for the existence of the target URL. If the target URL isn't found, the webmention MUST be rejected.

Webmention uses x-www-form-urlencoded for the source and target as parameters in an HTTP POST request. Beyond verification, it is not specified what the receiver should do upon receipt of a Webmention. What the webmention endpoint should return on a GET request is also left unspecified.

6.5 Delivery interop

This section describes how implementations of Webmention, ActivityPub and LDN may create bridging code in order to send and receive notifications from the others.

{
  "@context": "https://www.w3.org/ns/activitystreams#",
  "type": "Relationship",
  "subject": "https://waterpigs.example/post-by-barnaby",
  "object": "https://aaronpk.example/post-by-aaron"
}

{
  "@context": "https://www.w3.org/ns/activitystreams#",
  "type": "Relationship",
  "subject": {
    "id": "https://waterpigs.example/post-by-barnaby",
    "name": "Hi Aaron, great post."
  },
  "object": {
    "id": "https://aaronpk.example/post-by-aaron",
    "name": "Aaron's first post."
  },
  "relationship": "inReplyTo"
}

7.1 Relationships

Semantics and representation of personal relationships are implementation specific. These specifications deal with relationships only when distribution of content is affected, for example when 'following' triggers a subscription request from one server to another. Lists of other relationships may be discoverable from a user profile, should be represented according to the ActivityStreams 2.0 syntax and may (and are likely to) use extension vocabularies as needed.

• ActivityPub: When a server receives a Follow Activity in its inbox, the subject is added to a Followers Collection, which is discoverable from the subject's profile. Federated servers use this collection to deliver updates when new content is created by the owner of the collection.

7.2 Authentication, authorization, and access control

Authentication and authorization mechanisms were out of scope for the Social Web WG. Please follow the Community Group for development in this space. Meanwhile, some of the WG specifications contain non-normative notes on the topic:

• ActivityPub: Points to a Community Group best practices report in B.1 Authentication and Authorization.
• LDN: Recommends that receivers employ some kind of verification mechanism which may be authentication in 3.3.3 Sender verification, with additional security considerations in 5.6 Authenticated inboxes.
• Micropub: Requires bearer tokens, and suggests IndieAuth in 5. Authentication and Authorization.
• Webmention: Points to an extension for use with access controlled posts in B.3 Private Webmention.
• WebSub: Describes optional use of HMAC Signatures in 8.1 Authenticated Content Distribution.