1.1 Social Web Working Group

2.1 Specification Profiles

This specification defines two closely related and interacting protocols:

A client to server protocol, or "Social API"

This protocol permits a client to act on behalf of a user. For example, this protocol is used by a mobile phone application to interact with the user's social stream.

A server to server protocol, or "Federation Protocol"

This protocol is used to distribute activities between users on different servers, tying them into the same social graph.

The ActivityPub specification is designed so that once either of these protocols are implemented, supporting the other is of very little additional effort. However, servers may still implement one without the other. This gives three conformance classes:

ActivityPub conformant Client

This designation applies to any implementation of the entirety of the client portion of the client to server protocol.

ActivityPub conformant Server

This designation applies to any implementation of the entirety of the server portion of the client to server protocol.

ActivityPub conformant Federated Server

This designation applies to any implementation of the entirety of the federation protocols.

It is called out whenever a portion of the specification only applies to implementation of the federation protocol. In addition, whenever requirements are specified, it is called out whether they apply to the client or server (for the client-to-server protocol) or whether referring to a sending or receiving server in the server-to-server protocol.

2.2 Candidate Recommendation Exit Criteria

For this specification to advance to Proposed Recommendation, there must be at least two independent, interoperable implementations of each feature. Each feature may be implemented by a different set of products. There is no requirement that all features be implemented by a single product.

• Independent implementations are developed by different parties and cannot share, reuse or derive from another qualifying implementation code which is directly pertinent to the implementation of this specification.
• Interoperability occurs between clients and servers, or between servers and other servers, when the client/server makes a request to the targeted server, and the targeted server sends the expected response, as defined by this specification.
• An implementation is an ActivityPub client, server or federated server which implements the corresponding conformance class of the specification.

For the purposes of evaluating exit criteria, each of the following is considered a feature:

• Discovering an actor's profile based on their URI (either the representation of the actor itself, which is probably an Actor Type, or a Profile object describing the actor). See the Actors section of this document for more information on what information is expected.
• A client receiving authorization and subsequently submitting an activity to the authenticated actor's outbox.
• A server handling an activity submitted by an authenticated actor to their outbox and handling client to server interaction side effects appropriately.
• A federated server delivering an activity posted by a local actor to the inbox endpoints of all recipients specified in the activity, including those on other remote federated servers.
• A federated server receiving an activity to its actor's inbox, validating that the activity and any nested objects were created by their respective actors, and handling server to server side effects appropriately.

2.3 At Risk features

The Working Group has marked the following features as At Risk and may seek to advance the specification with the removal of these features if insufficient implementation experience can be gathered.

• 6.11 Uploading Media and its associated endpoint.
• 3.3 The source property.
• The preferredUsername property.
• 7.1.3 Public Inbox Delivery section and its associated publicInbox endpoint.
• 6.1.1 Object creation without a Create Activity.
• 6.2.1 Partial Updates. In absence of this section, updates for client to server result in an entire replacement of the object rather than modifying individual fields.

3.1 Object Identifiers

All Objects in [ActivityStreams] should have unique global identifiers. ActivityPub extends this requirement; all objects distributed by the ActivityPub protocol MUST have unique global identifiers, unless they are intentionally transient (short lived activities that are not intended to be able to be looked up, such as some kinds of chat messages or game notifications). These identifiers must fall into one of the following groups:

1. Publicly dereferencable URIs, such as HTTPS URIs, with their authority belonging to that of their originating server. (Publicly facing content SHOULD use HTTPS URIs.)
2. An ID explicitly specified as the JSON null object, which implies an anonymous object (a part of its parent context)

Identifiers MUST be provided for activities posted in server to server communication, unless the activity is intentionally transient. However, for client to server communication, a server receiving an object posted to the outbox with no specified id SHOULD allocate an object ID in the user's namespace and attach it to the posted object.

All objects have the following properties:

id

The object's unique global identifier (unless the object is transient, in which case the id MAY be omitted).

type

The type of the object.

3.2 Retrieving objects

The HTTP GET method may be dereferenced against an object's id property to retrieve the activity. Servers MAY use HTTP content negotiation as defined in [RFC7231] to select the type of data to return in response to a request, but MUST present the ActivityStreams object representation in response to application/ld+json; profile="https://www.w3.org/ns/activitystreams", and SHOULD also present the ActivityStreams representation in response to application/activity+json as well. The client MUST specify an Accept header with the application/ld+json; profile="https://www.w3.org/ns/activitystreams" media type in order to retrieve the activity.

Servers MAY implement other behavior for requests which do not comply with the above requirement. (For example, servers may implement additional legacy protocols, or may use the same URI for both HTML and ActivityStreams representations of a resource).

Servers MAY require authorization as specified in 8. Authentication and Authorization, and may additionally implement their own authorization rules. Servers SHOULD fail requests which do not pass their authorization checks with the appropriate HTTP error code, or the 403 Forbidden error code where the existence of the object is considered private. An origin server which does not wish to disclose the existence of a private target MAY instead respond with a status code of 404 Not Found.

3.3 The source property

In addition to all the properties defined by the [ Activity-Vocabulary], ActivityPub extends the Object by supplying the source property. The source property is intended to convey some sort of source from which the content markup was derived, as a form of provenance, or to support future editing by clients. In general, clients do the conversion from source to content, not the other way around.

The value of source is itself an object which uses its own content and mediaType fields to supply source information.

{
  "@context": ["https://www.w3.org/ns/activitystreams",
               {"@language": "en"}],
  "object": "Note",
  "id": "http://postparty.example/p/2415",
  "content": "<p>I <em>really</em> like strawberries!</p>",
  "source": {
    "content": "I *really* like strawberries!",
    "mediaType": "text/markdown"},
}

4.1 Actor objects

Actor objects MUST have, in addition to the properties mandated by 3.1 Object Identifiers, the following properties:

inbox

A reference to an [ActivityStreams] OrderedCollection comprised of all the messages received by the actor; see 5.2 Inbox.

outbox

An [ActivityStreams] OrderedCollection comprised of all the messages produced by the actor; see 5.1 Outbox.

Implementations SHOULD, in addition, provide the following properties:

following

A link to an [ActivityStreams] collection of the actors that this actor is following; see 5.4 Following Collection

followers

A link to an [ActivityStreams] collection of the actors that follow this actor; see 5.3 Followers Collection.

liked

A link to an [ActivityStreams] collection of objects this actor has liked; see 5.5 Liked Collection.

{
  "@context": ["https://www.w3.org/ns/activitystreams",
               {"@language": "ja"}],
  "type": "Person",
  "id": "https://kenzoishii.example.com/",
  "following": "https://kenzoishii.example.com/following.json",
  "followers": "https://kenzoishii.example.com/followers.json",
  "liked": "https://kenzoishii.example.com/liked.json",
  "inbox": "https://kenzoishii.example.com/inbox.json",
  "outbox": "https://kenzoishii.example.com/feed.json",
  "preferredUsername": "kenzoishii",
  "name": "石井健蔵",
  "summary": "この方はただの例です",
  "icon": [
    "https://kenzoishii.example.com/image/165987aklre4"
  ]
}

Implementations MAY, in addition, provide the following properties:

streams

A list of supplementary Collections which may be of interest.

preferredUsername

A short username which may be used to refer to the actor, with no uniqueness guarantees.

endpoints

A json object which maps additional endpoints which may be useful either for this actor or someone referencing this actor. This mapping may be nested inside the actor document as the value or may be a link to a JSON-LD document with these properties.

The endpoints mapping MAY include the following properties:

uploadMedia

Upload endpoint URI for this user for binary data.

proxyUrl

Endpoint URI so this actor's clients may access remote ActivityStreams objects which require authentication to access. To use this endpoint, the client posts an x-www-form-urlencoded id parameter with the value being the id of the requested ActivityStreams object.

oauthAuthorizationEndpoint

If OAuth 2.0 bearer tokens [RFC6749] [RFC6750] are being used for authenticating client to server interactions, this endpoint specifies a URI at which a browser-authenticated user may obtain a new authorization grant.

oauthTokenEndpoint

If OAuth 2.0 bearer tokens [RFC6749] [RFC6750] are being used for authenticating client to server interactions, this endpoint specifies a URI at which a client may acquire an access token.

provideClientKey

If Linked Data Signatures and HTTP Signatures are being used for authentication and authorization, this endpoint specifies a URI at which browser-authenticated users may authorize a client's public key for client to server interactions.

signClientKey

If Linked Data Signatures and HTTP Signatures are being used for authentication and authorization, this endpoint specifies a URI at which a client key may be signed by the actor's key for a time window to act on behalf of the actor in interacting with foreign servers.

publicInbox

An optional endpoint used for wide delivery of publicly addressed activities. publicInbox endpoints SHOULD also be publicly readable OrderedCollection objects.

5.1 Outbox

The outbox is discovered through the outbox property of an actor's profile. The outbox MUST be an OrderedCollection.

The outbox stream contains objects the user has published, subject to the ability of the requestor to retrieve the object (that is, the contents of the outbox are filtered by the permissions of the person reading it). If a user submits a request without Authorization the server should respond with all of the Public posts. This could potentially be all relevant objects published by the user, though the number of available items is left to the discretion of those implementing and deploying the server.

The outbox accepts HTTP POST requests, with behaviour described in Client to Server Interactions.

5.2 Inbox

The inbox is discovered through the inbox property of an actor's profile. The inbox MUST be an OrderedCollection.

The inbox stream contains all objects received by the user. The server SHOULD filter content according to the requester's permission. In general, the owner of an inbox is likely to be able to access all of their inbox contents. Depending on access control, some other content may be public, whereas other content may require authentication for non-owner users, if they can access the inbox at all.

The server MUST perform de-duplication of activities returned by the inbox. Duplication can occur if an activity is addressed both to a user's followers, and a specific user who also follows the recipient user, and the server has failed to de-duplicate the recipients list. Such deduplication MUST be performed by comparing the id of the activities and dropping any activities already seen.

The inboxes of actors on federated servers accepts HTTP POST requests, with behaviour described in Delivery. Non-federated servers SHOULD return a 405 Method Not Allowed upon receipt of a POST request.

5.3 Followers Collection

Every actor SHOULD have a followers collection. This is a list of everyone who has sent a Follow activity for the user, added as a side effect. This is where one would find a list of all the users that are following the actor. The followers collection MUST be either an OrderedCollection or a Collection and MAY be filtered on privileges of an authenticated user or as appropriate when no authentication is given.

5.4 Following Collection

Every actor SHOULD have a following collection. This is a list of everybody that the actor has followed, added as a side effect. The following collection MUST be either an OrderedCollection or a Collection and MAY be filtered on privileges of an authenticated user or as appropriate when no authentication is given.

5.5 Liked Collection

Every actor MAY have a liked collection. This is a list of every object from all of the actor's Like activities, added as a side effect. The liked collection MUST be either an OrderedCollection or a Collection and MAY be filtered on privileges of an authenticated user or as appropriate when no authentication is given.

5.6 Public Addressing

In addition to [ActivityStreams] collections and objects, Activities may additionally be addressed to the special "public" collection, with the identifier https://www.w3.org/ns/activitystreams#Public. For example:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://www.w3.org/ns/activitystreams#Public",
  "type": "Collection"
}

Activities addressed to this special URI shall be accessible to all users, without authentication. Implementations MUST NOT deliver to the "public" special collection; it is not capable of receiving actual activities. However, actor has a publicInbox endpoint is available for efficient shared delivery of public posts; see 7.1.3 Public Inbox Delivery.

5.7 Likes Collection

Every object MAY have a likes collection. This is a list of all Like activities with this object as the object property, added as a side effect. The likes collection MUST be either an OrderedCollection or a Collection and MAY be filtered on privileges of an authenticated user or as appropriate when no authentication is given.

5.8 Shares Collection

Every object MAY have a shares collection. This is a list of all Announce activities with this object as the object property, added as a side effect. The shares collection MUST be either an OrderedCollection or a Collection and MAY be filtered on privileges of an authenticated user or as appropriate when no authentication is given.

6.1 Create Activity

The Create activity is used when posting a new object. This has the side effect that the object embedded within the Activity (in the object property) is created.

When a Create activity is posted, the actor of the activity SHOULD be copied onto the object's attributedTo field.

A mismatch between addressing of the Create activity and its object is likely to lead to confusion. As such, a server SHOULD copy any recipients of the Create activity to its object upon initial distribution, and likewise with copying recipients from the object to the wrapping Create activity. Note that it is acceptable for the object's addressing to be changed later without changing the Create's addressing (for example via an Update activity).

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Note",
  "content": "This is a note",
  "published": "2015-02-10T15:04:55Z",
  "to": ["https://example.org/~john/"],
  "cc": ["https://example.com/~erik/followers",
         "https://www.w3.org/ns/activitystreams#Public"]
}

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Create",
  "id": "https://example.net/~mallory/87374"
  "actor": "https://example.net/~mallory",
  "object": {
    "id": "https://example.com/~mallory/note/72",
    "type": "Note",
    "attributedTo": "https://example.net/~mallory",
    "content": "This is a note",
    "published": "2015-02-10T15:04:55Z",
    "to": ["https://example.org/~john/"],
    "cc": ["https://example.com/~erik/followers",
           "https://www.w3.org/ns/activitystreams#Public"]
  },
  "published": "2015-02-10T15:04:55Z",
  "to": ["https://example.org/~john/"],
  "cc": ["https://example.com/~erik/followers",
         "https://www.w3.org/ns/activitystreams#Public"]
}

6.2 Update Activity

The Update activity is used when updating an already existing object. The side effect of this is that the object MUST be modified to reflect the new structure as defined in the update activity, assuming the actor has permission to update this object.

6.3 Delete Activity

The Delete activity is used to delete an already existing object. The side effect of this is that the server MAY replace the object with a Tombstone of the object that will be displayed in activities which reference the deleted object. If the deleted object is requested the server SHOULD respond with either the HTTP 410 Gone status code if a Tombstone object is presented as the response body, otherwise respond with a HTTP 404 Not Found.

A deleted object:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://example.com/~alice/note/72",
  "type": "Tombstone",
  "published": "2015-02-10T15:04:55Z",
  "updated": "2015-02-10T15:04:55Z",
  "deleted": "2015-02-10T15:04:55Z",
}

6.4 Follow Activity

The Follow activity is used to subscribe to the activities of another user.

The side effect of receiving this in an outbox is that the server SHOULD add the object to the actor's following Collection.

6.5 Add Activity

Upon receipt of an Add activity into the outbox, the server SHOULD add the object to the collection specified in the target property, unless:

• the target is not owned by the receiving server, and thus they are not authorized to update it.
• the object is not allowed to be added to the target collection for some other reason, at the receiving server's discretion.

6.6 Remove Activity

Upon receipt of a Remove activity into the outbox, the server SHOULD remove the object from the collection specified in the target property, unless:

• the target is not owned by the receiving server, and thus they are not authorized to update it.
• the object is not allowed to be removed from the target collection for some other reason, at the receiving server's discretion.

6.7 Like Activity

The Like activity indicates the actor likes the object.

The side effect of receiving this in an outbox is that the server SHOULD add the object to the actor's liked Collection.

6.8 Block Activity

The Block activity is used to indicate that the posting actor does not want another actor (defined in the object property) to be able to interact with objects posted by the actor posting the Block activity. The server SHOULD prevent the blocked user from interacting with any object posted by the actor.

Servers SHOULD NOT deliver Block Activities to their object.

6.9 Undo Activity

The Undo activity is used to undo a previous activity. See the Activity Vocabulary documentation on Inverse Activities and "Undo". For example, Undo may be used to undo a previous Like or Follow. The undo activity and the activity being undone MUST both have the same author. Side effects should be undone, to the extent possible. For example, if undoing a Like, any counter that had been incremented previously should be decremented appropriately.

There are some exceptions where there is an existing and explicit "inverse activity" which should be used instead. Create based activities should instead use Delete, and Add activities should use Remove.

6.10 Delivery

Federated servers MUST perform delivery on all Activities posted to the outbox according to outbox delivery.

6.11 Uploading Media

ActivityPub supports uploading document types to be referenced in activites, such as images, video or other binary data, and servers MAY implement this feature. To accomplish this, a client MUST submit a multipart/form-data message to the user's uploadMedia endpoint on their ActivityStreams profile object. (Unlike most client to server interactions, using this endpoint does not involve submitting to the outbox.) A client should expect that it must be properly authenticated in order to be able to upload media.

The submitted form data should contain two parts / fields:

file

The media file file being uploaded.

object

A shell of an ActivityStreams object, which will be finalized by the server.

Assuming that the server accepts the request and that the user was appropriately authorized to upload media, servers MUST respond with a 201 Created if the object is immediately available or a 202 Accepted if the server is still processing the submitted media. The response MUST contain a Location header pointing to the new or to-be-created object's id.

The server, having done any appropriate processing on the received file and putting it in place, transforms the object that will be retrievable by the id. In particular, servers MUST append an id property to the object, and SHOULD include the uploaded and/or processed file paths in the object's url property. The server MAY wrap the shell object submitted by the user in a Create via 6.1.1 Object creation without a Create Activity if appropriate and present this as the object pointed to by the forementioned Location header in the post-media-upload response.

{"@context": "https://www.w3.org/ns/activitystreams",
 "type": "Person",
 "id": "https://chatty.example/ben/",
 "name": "Ben Bitdiddle",
 "preferredUsername": "ben",
 "summary": "Constantly fidgeting with ones and zeroes.",
 "inbox": "https://chatty.example/ben/inbox/",
 "outbox": "https://chatty.example/ben/collections/outbox/",
 "followers": "https://chatty.example/ben/collections/followers/",
 "following": "https://chatty.example/ben/collections/following/",
 "likes": "https://chatty.example/ben/collections/likes/",
 "endpoints": {
   "id": "https://chatty.example/ben/#endpoints",
   "uploadMedia": "https://chatty.example/ben/endpoints/uploadMedia/"}}

POST /ben/endpoints/uploadMedia/ HTTP/1.1
Host: chatty.example
Content-Type: multipart/form-data; boundary=bfe40faf4ef
Authorization: Bearer XXXXXXXXXXX
  
--bfe40faf4ef
Content-Disposition: form-data; name="object"
Content-Type: application/ld+json; profile="https://www.w3.org/ns/activitystreams"
  
{"@context": "https://www.w3.org/ns/activitystreams",
 "type": "Create",
 "actor": "https://chatty.example/ben/",
 "to": ["https://chatty.example/ben/collections/followers/",
        "https://www.w3.org/ns/activitystreams#Public"],
 "object": {
   "type": "Video",
   "name": "A wireworld computer!",
   "attributedTo": "https://chatty.example/ben/",
   "to": ["https://chatty.example/ben/collections/followers/",
          "https://www.w3.org/ns/activitystreams#Public"],
   "summary": "<p>My friend Conway and I went over to our friend
                  Silverman's place and saw the wireworld computer
                  he's been constructing.  Pretty crazy!</p>
               <p>Tomorrow we're going over to our friend Langton's
                  place and see that ant farm he's been working
                  on...</p>"}}
  
--bfe40faf4ef
Content-Disposition: form-data; name="file"; filename="wireworld.webm"
Content-Type: video/webm
  
... (binary data) ...
--bfe40faf4ef

{"@context": "https://www.w3.org/ns/activitystreams",
 "type": "Create",
 "id": "https://chatty.example/ben/posts/d4152a7c/",
 "actor": "https://chatty.example/ben/",
 "to": ["https://chatty.example/ben/collections/followers/",
        "https://www.w3.org/ns/activitystreams#Public"],
 "object": {
   "type": "Video",
   "id": "https://chatty.example/ben/posts/6e69f564/",
   "url": [
     {"type": "Link",
      "href": "https://chatty.example/media/6e69f564/wireworld-small.webm",
      "mediaType": "video/webm; codecs=\"vp8, vorbis\"",
      "name": "A wireworld computer! (small)",
      "width": 640,
      "height": 480},
     {"type": "Link",
      "href": "https://chatty.example/media/6e69f564/wireworld-large.webm",
      "mediaType": "video/webm; codecs=\"vp8, vorbis\"",
      "name": "A wireworld computer! (large)",
      "width": 1280,
      "height": 720},
   "name": "A wireworld computer!",
   "attributedTo": "https://chatty.example/ben/",
   "to": ["https://chatty.example/ben/collections/followers/",
          "https://www.w3.org/ns/activitystreams#Public"],
   "summary": "<p>My friend Conway and I went over to our friend
                  Silverman's place and saw the wireworld computer
                  he's been constructing.  Pretty crazy!</p>
               <p>Tomorrow we're going over to our friend Langton's
                  place and see that ant farm he's been working
                  on...</p>"}}

7.1 Delivery

The following is required by federated servers communicating with other federated servers only.

An activity is delivered to its targets (which are actors) by first looking up the targets' inboxes and then posting the activity to those inboxes. Targets for delivery are determined by checking the ActivityStreams audience targeting; namely, the to, bto, cc, bcc, and audience fields of the activity.

The inbox is determined by first retrieving the target actor's JSON-LD representation and then looking up the inbox property. If a recipient is a Collection or OrderedCollection, then the server MUST dereference the collection (with the user's credentials) and discover inboxes for each item in the collection. Servers MUST limit the number of layers of indirections through collections which will be performed, which MAY be one.

Servers MUST de-duplicate the final recipient list. Servers MUST also exclude actors from the list which are the same as the actor of the Activity being notified about. That is, users shouldn't have their own activities delivered to themselves.

An HTTP POST request (with authorization of the submitting user) is then made to to the inbox, with the Activity as the body of the request. This Activity is added by the receiver as an item in the inbox OrderedCollection. Attempts to deliver to an inbox on a non-federated server SHOULD result in a 405 Method Not Allowed response.

For federated servers performing delivery to a third party server, delivery SHOULD be performed asynchronously, and SHOULD additionally retry delivery to recipients if it fails due to network error. Servers SHOULD also take care not to overload servers with submissions, for example by using an exponential backoff strategy.

Note: Activities being distributed between users on the same origin may use any internal mechanism, and are not required to use HTTP.

7.2 Create Activity

Receiving a Create activity in an inbox has surprisingly few side effects; the activity should appear in the actor's inbox and it is likely that the server will want to locally store a representation of this activity and its accompanying object. However, this mostly happens in general with processing activities delivered to an inbox anyway.

7.3 Update Activity

For server to server interactions, an Update activity means that the receiving server SHOULD update its copy of the object of the same id to the copy supplied in the Update activity. Unlike the client to server handling of the Update activity, this is not a partial update but a complete replacement of the object.

The receiving server MUST take care to be sure that the Update is authorized to modify its object. At minimum, this may be done by ensuring that the Update and its object are of same origin.

7.4 Delete Activity

The side effect of receiving this is that (assuming the object is owned by the sending actor / server) the server receiving the delete activity SHOULD remove its representation of the object with the same id, and MAY replace that representation with a Tombstone object.

(Note that after an activity has been transmitted from an origin server to a remote server, there is nothing in the ActivityPub protocol that can enforce remote deletion of an object's representation.)

7.5 Follow Activity

The side effect of receving this in an inbox is that the server SHOULD add the actor to the object user's Followers Collection.

7.6 Add Activity

Upon receipt of an Add activity into the inbox, the server SHOULD add the object to the collection specified in the target property, unless:

• the target is not owned by the receiving server, and thus they can't update it.
• the object is not allowed to be added to the target collection for some other reason, at the receiver's discretion.

7.7 Remove Activity

Upon receipt of a Remove activity into the inbox, the server SHOULD remove the object from the collection specified in the target property, unless:

• the target is not owned by the receiving server, and thus they can't update it.
• the object is not allowed to be removed to the target collection for some other reason, at the receiver's discretion.

7.8 Like Activity

The side effect of receving this in an inbox is that the server SHOULD increment the object's count of likes by adding the received activity to the likes collection if this collection is present.

7.9 Announce Activity (sharing)

Upon receipt of an Announce activity in an inbox, a server SHOULD increment the object's count of likes by adding the received activity to the shares collection if this collection is present.

7.10 Undo Activity

The Undo activity is used to undo the side effects of previous activities. See the ActivityStreams documentation on Inverse Activities and "Undo". The scope and restrictions of the Undo activity are the same as for the Undo activity in the context of client to server interactions, but applied to a federated context.