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
Collection
type for the collection - use the
CollectionPage
type for the collection pages - use the
items
property ofCollection
orCollectionPage
for items in the collection
- use the
- For ordered collections:
- use the
OrderedCollection
type for the collection - use the
OrderedCollectionPage
type for the collection pages - use the
orderedItems
property ofOrderedCollection
orOrderedCollectionPage
for 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.)