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. A similar concept to entities are the [ActivityStreams](https://www.w3.org/TR/activitystreams-core/) objects, which are used to represent activities in the [ActivityPub](https://www.w3.org/TR/activitypub/) protocol. {{ className: 'lead' }}

## Entity 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 omitted or set to `null`.

<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#rfc3339">
            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.
            </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 refetched 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.

## Serialization

When serialized to a string, the JSON representation of an entity must follow the following rules:
- Keys must be sorted lexicographically.
- Must use UTF-8 encoding.
- Must be **signed** using the the [instance's private key](/entities/instance-metadata).
- Must use Unix-style `\n` line endings (LF).