This document describes the current best practices for implementing and using ActivityPub collections.
Some parts of it are based on the implementation of collections in GoActivityPub.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC-2119.
Activity Streams 2.0: A collection is an object with Collection type or its subtype (e.g. OrderedCollection).
A collection SHOULD have an attributedTo property indicating the actor that created it.
Clients can create collections by publishing a Create activity where object is a collection. The server MUST ignore reserved collection properties such as items, totalItems and pagination properties.
Some special collections, such as inbox and outbox are created automatically by a server.
Servers MAY create collections automatically when the object of Create activity contains a property that points to a collection, such as likes, shares or replies. When the specified collection ID is local, the server MUST verify that the ID is valid, and MAY assign a different ID.
Clients MUST NOT attempt to create new collections by embedding non-anonymous collections in objects.
Collection IDs SHOULD NOT contain query parameters.
The contents of a collection (its items) are modified either directly by Add, Remove and Move activities, or indirectly by side-effects of other activities. If a collection has an updated property, its value SHOULD be changed whenever the contents are modified.
A client can update other properties of a collection by generating an Update activity. The server MUST NOT overwrite reserved collection properties such as items, totalItems and pagination properties.
[!NOTE]
Updateof a collection is not compatible with client-side signing (FEP-ae97) because partial updates are not supported there.
ActivityPub states that an OrderedCollection MUST be presented in reverse chronological order. In practice, however, some ordered collections are presented in forward chronological order, and an erratum was proposed that limits this requirement to collections defined in the ActivityPub specification (inbox, outbox, followers, following, liked, likes and shares).
Collections can be filtered.
Filters are specified using query parameters that are appended to a collection ID. A set of guidelines for using these parameters has been proposed in FEP-6606: ActivityPub client to server collections addressing conventions.
Pagination of collections is described in Activity Streams 2.0.
Collection page IDs are usually created by appending query parameters to a collection ID:
page (integer): the page number.after and before (percent-encoded URI): the item identifier for cursor based pagination.maxItems (integer): the maximum number of items in a page.Collection items MUST be filtered based on the permissions of an actor that tries to access the collection. If the actor is not authorized, only public items are returned.
A collection itself often doesn’t have an audience and is treated as public by default. However, if the audience is specified, regular access control procedures MUST be used.
An object can be addressed to a collection. When determining delivery targets and regulating access to an object, the server SHOULD expand collections by replacing them with actors they contain (if any).
Public collectionhttps://www.w3.org/ns/activitystreams#Public is a special collection ID that is used for public addressing. It is described in ActivityPub.
CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
To the extent possible under law, the authors of this Fediverse Enhancement Proposal have waived all copyright and related or neighboring rights to this work.