Copyright © 2016 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
The Social Web Protocols are a collection of standards which enable various aspects of decentralised social interaction on the Web. This document describes the purposes of each, and how they fit together.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This document was published by the Social Web Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-socialweb@w3.org (subscribe, archives). All comments are welcome.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 September 2015 W3C Process Document.
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:
regardless of what that content is or where it is stored.
These components are core building blocks for interoperable social systems.
Each of these components 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:
This is an overview of the current state of specifications of the Social Web Working Group. This document also describes Social Web Working Group specifications in context of W3C recommendations and relevant drafts from other communities outside of the Social Web Working Group. As many of these specs are under ongoing development, this document is subject to change alongside them.
You might also want to take a look at the Working Group's Social API Requirements to understand the division of concerns.
Due to the diversity of viable technical approaches proposed within the Working Group, several specifications on the recommendation track provide overlapping functionality through differing mechanisms. Thus this document exists to provide informative guidance on how and when to implement the various specifications, as well as normative instructions to implement bridges between recommendations with overlapping functionality. This is currently a recommendation-track document, but may finally be published as a Note.
This table shows the high level requirements according to the Social Web Working Group charter and the Social API Requirements, and how the specifications of the Working Group overlap with respect to each.
| Vocabulary | Syntax | Read | Create | Update | Delete | Subscription | Delivery | Profiles | |
|---|---|---|---|---|---|---|---|---|---|
| ActivityPub | X | X | X | X | X | X | X | ||
| ActivityStreams 2.0 | X | X | |||||||
| jf2 | X | X | |||||||
| Linked Data Notifications | X | X | |||||||
| Micropub | X | X | X | ||||||
| Post-type discovery |
X | ||||||||
| PubSub |
X | ||||||||
| Webmention | X |
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.
[ActivityStreams2] content MUST be served with the Content-Type application/activity+json or, if necessary for JSON-LD extended implementations, application/ld+json; profile="http://www.w3.org/ns/activitystreams". Content MUST be described using the [ActivityStreams2] vocabulary, and MAY use other vocabularies in addition or instead, per the [ActivityStreams2] extension mechanism.
Note: [ActivityStreams2] builds upon [AS1] and is not fully backwards compatible; the relationship between AS1 and AS2 is documented in the AS2 spec. If you have implemented [AS1], you should transition to [ActivityStreams2].
[Activitypub] servers and clients publish, consume and deliver [ActivityStreams2] JSON with the content type application/ld+json; profile="http://www.w3.org/ns/activitystreams".
In order to support [Activitypub] clients, content MUST be available as [ActivityStreams2] JSON. This could be directly, through content negotiation (when requested with an appropriate Accept header), or via a rel="alternate" type="application/activity+json" link (which could be to a different domain, for third-party services which dynamically generate [ActivityStreams2] JSON on behalf of the publisher).
This is a simpler form of the parsed microformats2 syntax, and alternative/supplement to [ActivityStreams2], being worked on as a WG Note. It is not currently referenced by any other specifications in the WG.
[LDN] is agnostic about the vocabulary of individual notifications, but the syntax MUST be JSON-LD, though consumers MAY request other RDF syntaxes and receivers MAY offer other RDF syntaxes. Thus, notifications may be represented with [ActivityStreams2].
LDN specifies how to represent the relation between an inbox and its contents using the [LDP] vocabulary term contains.
Currenty LDN expects inboxes to be represented with ldp:contains and ActivityPub expects them with as:items. This does not affect sending interoperability, but could be confusing for some reading/consuming clients. See issue 36 and interim interoperability notes.
[Micropub] update clients MUST consume content as JSON in the parsed microformats2 syntax.
All objects MUST have URLs in the id property, which return the properties of an object according to content representation, and depending on the requester's right to access the content.
Each stream MUST have a URL which MUST result in the contents of the stream (according to the requester's right to access, and could be paged), and MAY include additional metadata about the stream (such as title, description).
Each object in a stream MUST contain at least its URL, which can be dereferenced to retrieve all properties of the object, and MAY contain other properties of the object.
One user may publish 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 user profile MAY include links to multiple streams, which a consumer could follow to read or subscribe to.
[Activitypub] specifies four feeds that MUST be accessible from a profile via the following properties:
inbox: A reference to an [ActivityStreams2] collection comprising of all the messages received by the actor.outbox: An [ActivityStreams2] collection comprising of all the messages produced by the actor.following: An [ActivityStreams2] collection of the actors that this actor is following.followers: An [ActivityStreams2] collection of the actors that follow this actor.[Activitypub] also specifies a further property for accessing additional feeds, which MAY be included in a profile:
streams: A list of supplementary Collections which may be of interest. ActivityPub discovery mechanism for this to be specified, likely link relations per issue 50.
[Activitypub] permits arbitrary streams to be created through specifying special behavior for the server when it receives activities with types Add and Remove. When a server receives such an activity in the outbox, and the target is a Collection, it MUST add the object to the target (for Add) or remove the object from the target (for Remove).
An inbox is a collection or stream of objects to which new objects may be delivered. The contents of this collection may also be read. Currently LDN consumers and ActivityPub consumers expect different representations for this collection.
This section describes a workaround until it can be resolved in the specifications themselves. We particularly welcome implementations of this workaround to help us determine the best solution.
ActivityPub servers wishing to be read by LDN consumers MUST:
application/ld+json; profile="http://www.w3.org/ns/activitystreams".Collection, every item in the Inbox related with the ldp:contains property.ActivityPub clients wishing to read from LDN Inboxes MUST:
application/ld+json. Running it through JSON-LD compacting should help.ldp:contains property (rather than AS2 items).LDN receivers wishing to interoperate with ActivityPub consuming clients MUST:
application/activity+json as equivalent to application/ld+json; profile="http://www.w3.org/ns/activitystreams".Collection (where each notification is related to the inbox with the AS2 items property).LDN consumers wishing to read from inboxes on ActivityPub servers MUST:
application/activity+json and missing an @context, apply the default AS2 context, and treat it as JSON-LD.items property (rather than ldp:contains).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:
[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:
[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:
Content is updated when a client sends changes to attributes (additions, removals, replacements) to an existing object. If a server has implemented a delivery or subscription mechanism, when an object is updated, the update MUST be propagated to the original recipients using the same mechanism.
[Activitypub] clients replace the complete object by sending an HTTP POST request containing an [ActivityStreams2] Update activity to the outbox of the authenticated user, where the object is a nested object, including an id, which serves as the replacement.
ActivityPub currently only supports updates of a whole object at once. Issue 85 for partial updates.
[Micropub] clients perform updates, as either form-encoded or JSON POST requests, using the mp-action=update parameter, as well as a replace, add or delete property containing the updates to make, to the Micropub endpoint (discovery described in creating). 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.
[LDP] clients perform replacement-style updates by sending an HTTP PUT request to the URL of the object to be updated. Partial-style updates are performed with an HTTP PATCH request.
Content is deleted when a client sends a request to delete an existing object. If a server has implemented a delivery or subscription mechanism, when an object is deleted, the deletion MUST be propagated to the original recipients using the same mechanism.
[Activitypub] clients delete an object by sending an HTTP POST request containing an [ActivityStreams2] Delete activity to the outbox of the authenticated user. Servers MUST replace the object of this activity with a tombstone and return a 410 Gone status code, or just return a 404 Not Found, from its URL.
[Micropub] delete requests are two key-value pairs, in form-encoded or JSON: mp-action: delete and url: url-to-be-deleted, sent to the Micropub endpoint (discovery described in creating).
[LDP] deletes are performed by sending an HTTP DELETE request to the URL of the object to be deleted.
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.
Nothing should rely on implementation of a subscription mechanism.
[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, and as a result, servers deliver the Activity to the inbox of each user in the collection.
Subscription requests (requests to be added to this collection) are made by the subscriber's server POSTing a Follow Activity to the target's inbox. 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.
Simultaneously, the subscriber's server (upon receipt of the Follow in their outbox) MAY add the target to the subscriber's Following collection.
It works, in conjunction with delivery, when the publisher and subscriber are on different domains, thus serving as a federation protocol. This is a suitable subscription mechanism when:
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. The hub verifies this request. When the target posts new content, the target's server sends a form-encoded POST to their hub with values for hub.mode ("publish") and hub.url and the hub checks the URL for new content and subsequently delivers updates to the subscriber's callback URL.
These descriptions are temporary so we don't forget about them, but will likely be removed from this document eventually.
Maintain a list of feeds you want to subscribe to, and periodically fetch the content. ie. just reading an [ActivityStreams2] feed.
[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:
[Webmention] can be deployed in a limited manner 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. This is a suitable subscription mechanism when:
The subscriber follows the urn:ietf:params:push link relation to the target's Push Service, and then Subscribes for Push Messages
A user or application may wish to push a notification to another user, for example to send a message or some new information; because they have linked to (replied, liked, bookmarked, reposted, etc) their content; because they have linked to (tagged, addressed) the user directly; to make the recipient aware of a change in state of some document or resource on the Web.
Note: we need to leave it open for users to refuse content they have not explicitly subscribed to, ie. nothing else should rely on implementation of Delivery.
The target of a notification is usually the addressee or the subject, as referenced by a URL. Once you have determined your target, you need to discover where to send the notification for that particular target. Do this by fetching the target URL and looking for a link to an endpoint which will accept the type of notification you want to send.
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.
[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:
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.
[LDN] provides a protocol for sending, receiving and consuming notifications which may contain any content, or be triggered by any person or process. Senders, receivers and consumers can all be on different domains, thus this meets the criteria for a federation protocol. This is a suitable notification mechanism when:
[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 RDF body. 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. Consumers retreive the Inbox listing as such, 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.
An existing [LDP] implementation can serve as an [LDN] receiver, by simply advertising any ldp:Container as the Inbox for a resource.
Receivers 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 retreive them. Receivers may also access control their inbox for example by requiring an Authorization header from both senders and consumers.
[Activitypub] uses [LDN] to send notifications with some specific constraints. These are:
[Activitypub] specifies how to define the target(s) to which a notification is to be sent (a pre-requisite to [LDN] sending), via the [ActivityStreams2] 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:
Create, Update and Delete activities.Undo activity.Follow, Like and Block activities.Add and Remove activities.[PubSub] targets 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 both cases. This may be refined as the spec develops.
This section describes how receiver implementations of either Webmention or LDN may create bridging code in order to accept notifications from senders of the other. This can also be read to understand how a sender of either Webmention or LDN should adapt their discovery and payload in order to send to a receiver of the other.
Webmention receivers wishing to also accept LDN POSTs at their Webmention endpoint MUST:
rel="http://www.w3.org/ns/ldp#inbox" in addition to rel="webmention" (in the Link header, HTML body or JSON body of a target).application/ld+json. Expect the body of the request to be:
{
"@context": "http://www.w3.org/ns/webmention#",
"source": { "@id": "https://waterpigs.example/post-by-barnaby" },
"target": { "@id": "https://aaronpk.example/post-by-aaron" }
}source->@id and target->@id values as the source and target of the Webmention, and proceed with verification.201 Created, it MUST return a Location header with a URL from which the contents of the request posted can be retrieved. 202 Accepted is still fine.LDN receivers wishing to also accept Webmentions to their Inbox MUST:
rel="webmention" in addition to rel="http://www.w3.org/ns/ldp#inbox" (in the Link header, HTML body or JSON body of a target).application/x-www-form-urlencoded. Convert these requests from:
source=https://waterpigs.example/post-by-barnaby&
target=https://aaronpk.example/post-by-aaron{
"@context": "http://www.w3.org/ns/webmention#",
"source": { "@id": "https://waterpigs.example/post-by-barnaby" },
"target": { "@id": "https://aaronpk.example/post-by-aaron" }
}201 Created with a Location header or 202 Accepted.A webmention may be represented as a persistent resource with [ActivityStreams2]:
{
"@context": "https://www.w3.org/ns/activitystreams#",
"type": "Relationship",
"subject": "https://waterpigs.example/post-by-barnaby",
"object": "https://aaronpk.example/post-by-aaron"
}A receiver or sender may want to augment this representation with the relationship between the two documents, and any other pertinent data. In the receiver's case, this could be gathered when they parse the source during the verification process. For example:
{
"@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"
}Stub, needs expansion
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.
Semantics and representation of personal relationships are implementation specific. This specification deals with relationships only when distribution of content is affected, for example if one user ‘friending' another triggers a subscription request from the first user's server to the second. Lists of other relationships MAY be discoverable from a user profile, SHOULD be represented according to the ActivityStremas 2 syntax and MAY (and are likely to) use extension vocabularies as needed.
Follow Activity in its inbox, the subject is added to a Followers Collection, which is discoverable from the subject's profile.