1. Overview

People and the content they create are the core components of the social web; they make up the social graph. This document describes a standard way in which people can:

• connect with other people and subscribe to their content;
• create, update and delete social content;
• interact with other people’s content;
• be notified when other people interact with their content;

regardless of what that content is or where it is stored.

These components are core building blocks for interoperable social systems.

Each of these specifications can be implemented independently as needed, or all together in one system, as well as extended to meet domain-specific requirements. Users can store their social data across any number of compliant servers, and use compliant clients hosted elsewhere to interact with their own content and the content of others. Put simply, this document tells you, according the recommendations of the Social Web Working Group:

• how to expose/consume social content (reading).
• what to post, and where to, in order to create, update or delete content.
• how to ask for notifications about content (subscribing).
• how to deliver notifications about content or users (delivery).
• how to expose profiles and relationships.

2. Reading

If you are a content publisher, this section is about how you should publish your content. If you are a content consumer, this is what you should expect to consume.

3. Creating content

Content generated through a client (such as a web form, mobile app, smart device) is created when it is sent to a server for processing, where it is typically stored and usually published (either publicly or to a restricted audience). Clients and servers may independently support creating, updating and deleting; there are no dependencies between them. Authentication and authorization for creating content is left out of scope.

[Activitypub] clients discover the outbox of the authenticated user from their JSON profile, then make an HTTP POST request with an appropriate [ActivityStreams2] activity as a JSON payload. [Activitypub] requires use of the [ActivityStreams2] vocabulary and syntax, which may be extended with JSON-LD. The URL of the created resource is generated at the discretion of the server. This is an appropriate protocol to use when:

• You want to send/receive a JSON or JSON-LD payload.
• Your data is described with [ActivityStreams2] (optionally extensible via JSON-LD).

[Micropub] clients discover the Micropub endpoint from the current user's homepage (likely entered by the user as part of authentication) from a rel="micropub" link, then 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. Micropub requires use of the Microformats 2 [h-entry] vocabulary, as well as a set of reserved attributes as commands to the server. Any additional key names sent outside of this vocabulary may be ignored by the server.

[Micropub] requests may alternatively be sent as a JSON payload, the syntax of which is derived from the Microformats 2 parsing algorithm. 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.

[LDP] servers are written to by sending an HTTP POST request to a Container (any resource on the server which returns Link: <http://www.w3.org/ns/ldp#Container>; rel="type"), containing an RDF payload with attributes of the object being created. An identifier for the created resource is generated at the discretion of the server. The URL is created by appending the identifier to the URL of the Container that was posted to. [Solid] and [AnnotationProtocol] both use slightly altered [LDP] to create content; [Solid] restricts use to only Basic Containers, while the [AnnotationProtocol] specifies the [AnnotationVocab] and primary syntax as JSON-LD. This is an appropriate protocol to use when:

• Your data is represented as RDF.
• Clients and servers are vocabulary agnostic.
• You prefer a more RESTful API.

4. Subscribing

An agent (client or server) may ask to be notified of changes to a content object (eg. edits, new replies) or stream of content (eg. objects added or removed from a particular stream). This is subscribing. A server may also receive notifications of changes to content it has not subscribed to: see delivery.

[Activitypub] servers distribute the activities of an actor by sending POST requests containing the activities as JSON payloads to the inbox of all actors in an actor's Followers collection. For subscription requests, special behavior is defined for servers when an [ActivityStreams2] Follow activity is appears in an actor's outbox or inbox.

• For outbox (an outgoing subscription request): The activity is delivered as usual to the object's inbox, and additionally the object is added to the actor's Following collection.
• For inbox (an incoming subscription request): The recipient's (the object of the Follow activity) server adds the actor of the Follow activity to the recipient's Followers collection, to which all new activities of the recipient are subsequently delivered.

It works when the publisher and subscriber are on different domains, thus serving as a federation protocol. This is a suitable subscription mechanism when:

• The objects and streams being subscribed to are described with [ActivityStreams2].
• The subscriber wants to request updates from a specific actor (rather than objects, streams or threads, see issue 80.
• You need to send or receive the whole requested resource over the wire (ie. a 'fat ping').
• You need to send or receive JSON payloads only.
• Subscriptions requests and fulfillment are handled server-side.
• The publisher is aware of who has subscribed; this is a push mechanism.

[Solid] uses websockets to allow client-side applications to subscribe to changes in objects ([LDP] Resources) and streams ([LDP] Containers). The websocket endpoint is advertised in the Updates-Via HTTP Link Header. The subscriber sends the keyword sub followed by an empty space and then the URI of the resource, to the target’s websockets URI. The target’s server sends a websockets message containing the keyword pub, followed by an empty space and the URI of the resource that has changed, whenever there is a change. It works when the publisher and subscriber are on different domains, thus serving as a federation protocol. This is a suitable subscription mechanism when:

• You send live updates over websockets.
• You can send and receive on the URL of the requested resource over the wire (ie. a 'thin ping').
• Subscriptions are requested client-side and fulfilled server-side.
• The publisher is aware of who has subscribed; this is a push mechanism.

[Webmention] can be deployed as a subscription mechanism through the [Salmentions] extension. Documents contain links to the sources of received webmentions along with the content. Every time the document is updated, including when new incoming webmentions are added, the server (re-)sends webmentions to every link. Thus, all documents which originally sent a webmention receive a webmention back, enabling them to parse the document for changes, and detect new replies in a thread, as well as changes to the original document. It works when the publisher and subscriber are on different domains, thus serving as a federation protocol. This is a suitable subscription mechanism when:

• The subscriber wants to subscribe to a specific thread or object.
• The subscriber has a document which links to that thread or object, and has sent a [Webmention] about it.
• The publisher displays links to the sources of received webmentions with their content.
• The subscriber has linked to a document and wants to be notified of further changes.
• The subscriber has implemented [Webmention] receiving.
• The publisher is aware of who has subscribed; this is a push mechanism.

Other options yet to be debated...

• Web Push Protocol: The subscriber follows the urn:ietf:params:push link relation to the target’s Push Service, and then Subscribes for Push Messages
• PubSubHubbub: The subscriber discovers the target’s hub, and sends a form-encoded POST request containing values for hub.mode (“subscribe”), hub.topic and hub.callback. When the target posts new content, the target’s server sends a form-encoded POST to the hub with values for hub.mode (“publish”) and hub.url and the hub checks the URL for new content and POSTs updates to the subscriber’s callback URL. (See PuSH 0.4 and How To Publish And Consume PuSH)
• Pull, ie. just reading an [ActivityStreams2] feed.

5. Delivery

A user or application may wish to push a notification to another user, for example because they have linked to (replied, liked, bookmarked, reposted, …) their content or linked to (tagged, addressed) the user directly, or to make the recipient aware of a change in state of some document or resource on the Web.

[Webmention] provides an API for sending and receiving notifications when a relationship is created between two documents. 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 links to another document (target).
• The owner of the target has access to view the source (so that their webmention endpoint can parse the source and check the claimed link exists).
• The only data you need to send over the wire are the URLs of the source and target documents (ie. a 'thin ping').

Discovery of the [Webmention] endpoint (a script which can process incoming webmentions) is through a link relation (rel="webmention"), either in the HTTP Header or 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.

[Webmention] uses x-www-form-urlencoded for the source and target as parameters in an HTTP POST request. This means a webmention can be triggered from a web form or from the commandline with curl. Integration with existing applications is straightforward through translating this form-encoded data into JSON, RDF (namespace), or another preferred syntax at the recievers end if necessary. There are no constraints on the syntax of the source and target documents.

[Webmention] can be extended by adding additional parameters to the POST request; applications must have prior agreement in order to understand them, and there is potential for collision of extension terms.

[Activitypub] provides a JSON-based API for sending and receiving [ActivityStreams2] activities as notifications. It works when the two documents are on different domains, thus serving as a federation protocol. This is a suitable notification mechanism when:

• You describe the notification with [ActivityStreams2].
• You need to send or receive the whole notification over the wire (ie. a 'fat ping').
• You need to send or receive JSON payloads only.
• You need to add additional properties to your notifications unambiguously with JSON-LD.
• You need to send the same notification to multiple users from one activity.

The endpoint which processes incoming notifications is a user's [Activitypub] inbox, discoverable from the target user's profile. The recipient user may be addressed directly (through object, target, to, cc, and/or bcc), and/or inferred as the owner of another resource which is addressed (through object, target and/or inReplyTo).

An [Activitypub] server delivers the entire activity to all discovered endpoints as a JSON payload of an HTTP POST request.

An [Activitypub] server receiving such an activity must verify the notification is accurate (by fetching the source, or some prior trust arrangement with the sender, eg. through an authentication token or digital signature).

[Activitypub] delivery can be extended through the [ActivityStreams2] extension mechanism, with JSON-LD.

6. Profiles

The subject of a profile document can be a person, persona, organisation, bot, location, … the type of the subject of the profile is not required. Each profile document MUST have a URL which SHOULD return attributes of the subject of the profile; SHOULD return at least one link to a stream of content and MAY return content the subject has created. A JSON format MUST be available; other content types MAY be returned as well.