docs/app/entities/page.mdx

export const metadata = {
    title: 'Entities',
    description:
        'Entities are simple JSON objects that represent the core data structures in Versia.',
}

# Entities

Entities are the foundation of the Versia protocol. They are similar to: {{ className: 'lead' }}

- [ActivityStreams](https://www.w3.org/TR/activitystreams-core/) objects
- [Matrix](https://matrix.org/) events.

## Definition

An entity is a simple JSON object that represents a core data structure in Versia. Entities are used to represent various types of data, such as users, notes, and more. Each entity has a unique `id` property that is used to identify it within the instance.

Any field in an entity not marked as `required` may be set to `null`. These fields **must not** be omitted: they must be present with a `null` value if not set.

<Row>
  <Col>

    <Properties name="Entity">
        <Property name="id" type="string" required={true}>
            Unique identifier for the entity. Must be unique within the instance. Can be any string with the following character sets:

            - `a-z`
            - `A-Z`
            - `0-9`
            - `-`, `_`

            Not present on [Transient Entities](#transient-entities).
        </Property>
        <Property name="type" type="string" required={true}>
            Type of the entity. Custom types must follow [Extension Naming](/extensions#naming).
        </Property>
        <Property name="created_at" type="RFC3339" required={true} typeLink="/types#rfc-3339">
            Date and time when the entity was created. Must be an [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) timestamp.

            <Note>
            Handling of dates that are valid but obviously incorrect (e.g. in the future) is left to the Implementation's discretion. Sending a [Note](/entities/note) created on `13-12-1337` is very funny, but don't be surprised if it is rejected.
            </Note>
        </Property>
        <Property name="$schema" type="string" required={false}>
            URL of any JSON Schema that the entity adheres to.

            <Note>
                This is for human use only, and not to be used by either clients or servers as a way to validate the entity.
            </Note>
        </Property>
        <Property name="extensions" type="Extensions" required={false} typeLink="/types#extensions">
            Extensions to the entity. Use this to add custom properties to the entity.

            Each custom property must be namespaced with the organization's reversed domain name, followed by the property name. Extensions should be used sparingly and only when necessary.
        </Property>
    </Properties>
  </Col>
  <Col sticky>

    ```jsonc {{ 'title': 'Example Entity' }}
    {
        "id": "3e7e4750-afd4-4d99-a256-02f0710a0520",
        "type": "pub.versia:likes/Like",
        "created_at": "2021-01-01T00:00:00.000Z",
        "author": "6e0204a2-746c-4972-8602-c4f37fc63bbe",
        "liked": "otherexample.org:fmKZ763jzIU8"
    }
    ``` 

    ```jsonc {{ 'title': 'With Extensions' }}
    {
        "id": "f0aacf0b-df7a-4ee5-a2ba-6c4acafd8642",
        "type": "org.space:Zlorbs/Zlorb",
        "created_at": "2023-04-13T08:00:00Z",
        "extensions": { // [!code focus:100]
            "org.space:zlorbs": {
                "zlorb_type": "giant",
                "zlorb_size": "huge"
            },
            "pub.versia:location": {
                "latitude": 37.7749,
                "longitude": -122.4194
            }
        }
    }
    ```
    </Col>
</Row>

## Transient Entities

Some entities are **transient**, meaning they cannot be fetched using the [Federation API](/api/endpoints). These entities are used for actions that do not require a permanent record, such as deletions or migrations. Transient Entities do not have an `id` field.

Implementations **must not** rely on other implementations to store transient entities in their database.