Collection

Collections are a way to represent paginated groups of entities. They are used everywhere lists of entities can be found, such as a user's outbox.

Pages should be limited to a reasonable number of entities, such as 20 or 80.

As Collections are independent and not part of a larger entity (like ContentFormat), they should have a valid Signature.

Entity Definition

Name
author
Required
Required
Type
URI | null
Description
Author of the collection. Usually the user who owns the collection. Can be set to null to represent the instance.
Name
first
Required
Required
Type
URI
Description
URI to the first page of the collection. Query parameters are allowed.
Name
last
Required
Required
Type
URI
Description
URI to the last page of the collection. Query parameters are allowed.
If the collection only has one page, this should be the same as first.
Name
total
Required
Required
Type
u64
Type
number
Description
Total number of entities in the collection, across all pages.
Name
next
Type
URI
Description
URI to the next page of the collection. Query parameters are allowed.
If there is no next page, this should be null.
Name
previous
Type
URI
Description
URI to the previous page of the collection. Query parameters are allowed.
If there is no previous page, this should be null.
Name
items
Required
Required
Type
Entity[]
Description
Collection contents. Must be an array of entities.

Example Collection

{
    "author": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771",
    "first": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771/outbox?page=1",
    "last": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771/outbox?page=3",
    "total": 46,
    "next": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771/outbox?page=2",
    "previous": null,
    "items": [
        {
            "id": "456df8ed-daf1-4062-abab-491071c7b8dd",
            "type": "Note",
            "uri": "https://versia.social/notes/456df8ed-daf1-4062-abab-491071c7b8dd",
            "created_at": "2024-04-09T01:38:51.743Z",
            "collections": {
                "replies": "https://versia.social/notes/456df8ed-daf1-4062-abab-491071c7b8dd/replies",
                "quotes": "https://versia.social/notes/456df8ed-daf1-4062-abab-491071c7b8dd/quotes"
            },
            "content": {
                "text/plain": {
                    "content": "Hello, world!"
                }
            }
        }
    ]
}

URI Collections are identical to regular collections, but they contain only URIs instead of full entities. They are useful for cases when remote entities need to be included in a collection, as those are typically not stored in implementation databases.

Name
author
Required
Required
Type
URI | null
Description
Author of the collection. Usually the user who owns the collection. Can be set to null to represent the instance.
Name
first
Required
Required
Type
URI
Description
URI to the first page of the collection. Query parameters are allowed.
Name
last
Required
Required
Type
URI
Description
URI to the last page of the collection. Query parameters are allowed.
If the collection only has one page, this should be the same as first.
Name
total
Required
Required
Type
u64
Type
number
Description
Total number of entities in the collection, across all pages.
Name
next
Type
URI
Description
URI to the next page of the collection. Query parameters are allowed.
If there is no next page, this should be null.
Name
previous
Type
URI
Description
URI to the previous page of the collection. Query parameters are allowed.
If there is no previous page, this should be null.
Name
items
Required
Required
Type
URI[]
Description
Collection contents. Must be an array of URIs.

Example URI Collection

{
    "author": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771",
    "first": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771/followers?page=1",
    "last": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771/followers?page=3",
    "total": 46,
    "next": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771/followers?page=2",
    "previous": null,
    "items": [
        "https://versia.social/users/f8b0d4b4-d354-4798-bbc5-c2ba8acabfe3",
        "https://social.bob.com/u/2B27E62snga763"
    ]
}