Activity Streams/Primer/Collections
The Collection model describes how collections of Activity Streams objects should be treated. However, there are some ambiguities on how the properties and types are used.
This page shows some best practices for publishers and consumers.
Publishers
- For unordered collections:
- use the
Collectiontype for the collection - use the
CollectionPagetype for the collection pages - use the
itemsproperty ofCollectionorCollectionPagefor items in the collection
- use the
- For ordered collections:
- use the
OrderedCollectiontype for the collection - use the
OrderedCollectionPagetype for the collection pages - use the
orderedItemsproperty ofOrderedCollectionorOrderedCollectionPagefor items in the collection
- use the
Publishers should not include both the items and orderedItems properties in the same Activity Streams 2.0 object.
Consumers
Ideally, publishers would use the above framework. However, in practice, publishers may use different combinations of these types and properties. Consumers will need to make assumptions about the ordering of items in these mixed situations. Here are best practices for assuming ordering.
As a general principle, if the publisher has expressed intent to order the items through the type of the collection, the collection page, or the property holding the items, you should assume order. This table shows some possible combinations of collection type, collection page type if any, and property.
| Collection type | Page type | property | treat as ordered? |
|---|---|---|---|
| Collection | (none) | items | no |
| Collection | (none) | orderedItems | yes |
| Collection | CollectionPage | items | no |
| Collection | CollectionPage | orderedItems | yes |
| Collection | OrderedCollectionPage | items | yes |
| Collection | OrderedCollectionPage | orderedItems | yes |
| OrderedCollection | (none) | items | yes |
| OrderedCollection | (none) | orderedItems | yes |
| OrderedCollection | CollectionPage | items | yes |
| OrderedCollection | CollectionPage | orderedItems | yes |
| OrderedCollection | OrderedCollectionPage | items | yes |
| OrderedCollection | OrderedCollectionPage | orderedItems | yes |
In addition, if the collection is otherwise defined to be ordered, it should be treated as ordered. For example, the `inbox` and `outbox` properties of an actor in ActivityPub are defined as ordered in reverse chronological order in the ActivityPub spec. Even if the representation is a `Collection` with an `items` property, it should still be treated as ordered.
If a collection or collection page includes both the items and orderedItems properties, use the property that matches the ordering aspect of the object, and ignore the other property. For example, given a CollectionPage (unordered) with an items (unordered) and an orderedItems (ordered), a consumer should use the items property and ignore the orderedItems property.
Canonicalization
Documents that have been canonicalized by JSON-LD may lose ordering of the `items` or `orderedItems` properties. Activity Streams 2.0 does not use the features of JSON-LD that allow for maintaining order in these properties.
Other intermediate processors may also lose ordering.
current property
The definition of the current property is:
In a paged Collection, indicates the page that contains the most recently updated member items.
The range is a CollectionPage or a Link.
If the value is a Link, it should link to a CollectionPage.
This is mostly useful for collections that are ordered chronologically. Typically, the current property will be equal to the last property (for chronologically-ordered collections) or the first property (for reverse-chronologically-ordered collections).
Collections that are not paged should not include this property.
Collections that are not ordered chronologically or reverse chronologically should not include this property.
The page referred to by the current property should be a page that's reachable by other means (such as starting with the first property and following each next property of each page.)