ActivityPub Note: Streams, Collections, and Endpoints

This article is an attempt to disentangle some of the ActivityPub specification terminology. First, some definitions.

• Collection — an aggregation of values with membership; its order may be fixed or unspecified. In ActivityPub, these are the Collection or the OrderedCollection and their page-related subtypes.
• Stream — a sequence of values read or written one at a time as they arrive, normally consumed once. Using this definition, there are no streams in ActivityPub (or, ironically, in Activity Streams). Although the values may be stored in collection for later retrieval, the collection is a historical record of values, not a stream itself.
• HTTP endpoint — the pairing of an HTTP method with a URI. The URI specifies a network endpoint for performing the HTTP request. Other variants of HTTP endpoints exist, such as WebSocket and Server-sent Events (SSE). However, the ActivityPub specification only uses HTTP request-reply endpoints. In this article, the word endpoint will refer to an HTTP endpoint (rather than a general network endpoint).

The specification uses these terms inconsistently, imprecisely or inaccurately. This leads to unnecessary protocol debates and interoperability issues. The following examples show how the text can be interpreted more clearly.

Examples

Objects are often wrapped in Activities and are contained in streams of Collections, which are themselves subclasses of Objects. — Section 3

This sentence is difficult to interpret. There are no streams (as defined earlier) in ActivityPub and there are no streams of Collections.

streams — A list of supplementary Collections which may be of interest. — Section 4.1

The name and the definition of this actor property are not consistent. This is unfortunate because in future versions of ActivityPub, there might be a need to define extension streams (actual streams, like notification or event streams, rather than collections). There may be a need to specify extension collections, including unordered Collection types that are not streams in any sense of the word. These might be used for bookmark or media collections, for example.

Using a "list" for the stream items (possibly meaning a JSON array) implies ordering, but it's not clear why this collection (of either collections or streams) would need to be ordered. Given the ActivityPub JSON-LD context, it would be unordered set of URIs in that context.

sharedInbox endpoints SHOULD also be publicly readable OrderedCollection objects — Section 4.1

An endpoint is not a collection. An endpoint can be used to retrieve a collection.

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

The word outbox is used in several ways in this sentence. The outbox endpoint (or URI) is discovered through the outbox property. Dereferencing the outbox URI returns an OrderedCollection.

The outbox stream contains activities the user has published, ... — Section 5.1

An outbox collection contains those activities. There is no outbox stream.

The outbox accepts HTTP POST requests — Section 5.1

The outbox endpoint accepts the POST requests.

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

The same comment applies to the outbox discovery.

The inbox stream contains all activities received by the actor. — Section 5.2

The inbox collection contains those activities. There is no inbox stream.

In addition to [ActivityStreams] collections and objects, Activities may additionally be addressed to the special "public" collection, — Section 5.6

The "public" URI is an addressing value, used for visibility control, not a collection.

Client to server interaction takes place through clients posting Activities to an actor's outbox — Section 6

This only makes sense if posting an activity to an actor's outbox endpoint.

The receiving outbox can then perform delivery — Section 6.1

This doesn't make sense given any of the potential meanings of "outbox". And outbox has no behavior. Servers have behavior.

Clients submitting the following activities to an outbox MUST provide ... — Section 6.1

This refers to submitting to an outbox endpoint. No collection is necessary.

Servers communicate with other servers and propagate information across the social graph by posting activities to actors' inbox endpoints. — Section 7

Correct. The posts are to the endpoints rather than to inbox collections. This works even without a collection. Mastodon has no inbox collection, for example.

Servers performing delivery to the inbox or sharedInbox properties of actors — Section 7

Of course, nothing is delivered to properties.

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 ... — Section 7.1

Delivery is to inbox endpoints. The inbox collections are optional.

The inbox is determined by first retrieving the target actor's JSON-LD representation and then looking up the inbox property — Section 7.1

The inbox endpoint (or URI) is determined.

An HTTP POST request (with authorization of the submitting user) is then made 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. — Section 7.1

The POST is made to the inbox endpoint. The specification overreaches by saying the item is added to the inbox collection. There may be no inbox collection.

When objects are received in the outbox (for servers which support both Client to Server interactions and Server to Server Interactions), the server MUST target and deliver to ... — Section 7.1.1

Objects are received by (POSTed to) the outbox endpoint. The outbox collection doesn't necessarily exist.

When Activities are received in the inbox, the server needs to forward these ... — Section 7.1.2

It's the same for the inbox. Activities are POSTed to the inbox endpoint. An inbox collection is not necessary.

Mastodon Note

Mastodon, the most common server implementation in the Fediverse, has no internal inbox or outbox collections. It only implements the related endpoints. An inbox endpoint cannot be dereferenced. An outbox endpoint can be, but the resulting OrderedCollection is synthesized on-demand.