# Collection

Paginated lists of entities and of references to entities.

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 subscribers.

A Collection can only hold entities [authored on the instance serving it](/validation#authors-and-signers). To list entities from other instances, use a [Reference Collection](#reference-collection).

## Definition

**Fields**

- `total` (`number`, integer, required): Total number of entities in the collection that the requesting instance [may fetch](/federation#access), across all pages.
- `items` (`Entity[]`, required): Collection contents. **MUST** be an array of entities.

```jsonc title="Example Collection"
{
    "total": 46,
    "items": [
        {
            "id": "033mcbcsyt000",
            "type": "pub.versia:social/Note",
            "created_at": "2024-04-09T01:38:51Z",
            // ...
            "content": "<p>Hello, world!</p>",
            "visibility": "public"
        }
    ]
}
```

## Reference Collection

Reference Collections are identical to regular Collections, but their `items` are [References](/entities#reference) instead of full entities. Use them when a collection can include entities from other instances.

Neither kind of collection carries a field saying which kind it is. The page that names a collection states its kind and the type of its items, and that is how to read its `items`.

**Fields**

- `total` (`number`, integer, required): Total number of entities in the collection that the requesting instance [may fetch](/federation#access), across all pages.
- `items` (`Reference[]`, required): Collection contents. **MUST** be an array of [References](/entities#reference).

```jsonc title="Example Reference Collection"
{
    "total": 46,
    "items": [
        "versia.example:0350q3easp004",
        "bob.example:03441phjap000"
    ]
}
```