export const metadata = {
    title: 'Collection',
    description: 'Definition of the Collection structure',
}

# 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. {{ className: 'lead' }}

<Note>
    As Collections are independent and not part of a larger entity (like [ContentFormat](/structures/content-format)), they should have a valid [Signature](/signatures).
</Note>

## Entity Definition

<Row>
    <Col>
        <Properties name="Collection">
            <Property name="author" type="URI | null" required={true} typeLink="/types#uri">
                Author of the collection. Usually the user who owns the collection. [Can be set to `null` to represent the instance](/entities/instance-metadata#the-null-author).
            </Property>
            <Property name="total" type="number" required={true} numberType="u64">
                Total number of entities in the collection, across all pages.
            </Property>
            <Property name="items" type="Entity[]" required={true}>
                Collection contents. Must be an array of entities.
            </Property>
        </Properties>
    </Col>

    <Col sticky>

    ```jsonc {{ 'title': 'Example Collection' }}
    {
        "author": "https://versia.social/users/018ec082-0ae1-761c-b2c5-22275a611771",
        "total": 46,
        "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!"
                    }
                }
            }
        ]
    }
    ```

    </Col>
</Row>

## URI Collection

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. {{ className: 'lead' }}

<Row>
    <Col>
        <Properties name="URICollection">
            <Property name="author" type="URI | null" required={true} typeLink="/types#uri">
                Author of the collection. Usually the user who owns the collection. [Can be set to `null` to represent the instance](/entities/instance-metadata#the-null-author).
            </Property>
            <Property name="total" type="number" required={true} numberType="u64">
                Total number of entities in the collection, across all pages.
            </Property>
            <Property name="items" type="URI[]" required={true}>
                Collection contents. Must be an array of URIs.
            </Property>
        </Properties>
    </Col>

    <Col sticky>

    ```jsonc {{ 'title': 'Example URI Collection' }}
    {
        "author": "018ec082-0ae1-761c-b2c5-22275a611771",
        "total": 46,
        "items": [
            "versia.social:f8b0d4b4-d354-4798-bbc5-c2ba8acabfe3",
            "social.bob.com:2B27E62snga763"
        ]
    }
    ```

    </Col>
</Row>