docs/app/entities/users/page.mdx

export const metadata = {
    title: 'Users',
    description: 'Definition of the User entity',
}

# Users

The `User` entity represents an account on a Lysand instance. Users can post [Notes](/entities/notes), follow other users, and interact with content. Users are identified by their `id` property, which is unique within the instance. {{ className: 'lead' }}

## Addresses

Users may be represented by a shorthand address, in the following formats:

```
@username@instance
@id@instance
```

For example:

```
@jessew@social.lysand.org
@018ec082-0ae1-761c-b2c5-22275a611771@social.lysand.org
```

This is similar to an email address or an ActivityPub address.

### Identifier

Identifier **must** be either a valid `username` or a valid `id`. It should have the same username/id as the user's profile.

<Note>
Usernames can be changed by the user, so it is recommended to use `id` for long-term references.
</Note>

### Instance

Instance **must** be the host of the instance the user is on (hostname with optional port).

## Entity Definition

<Row>
  <Col>

    <Properties>
        <Property name="avatar" type="ContentFormat" required={true} typeLink="/structures/content-format">
            The user's avatar. Must be an image format (`image/*`).
        </Property>
        <Property name="bio" type="ContentFormat" required={true} typeLink="/structures/content-format">
            Short description of the user. Must be text format (`text/*`).
        </Property>
        <Property name="display_name" type="string" required={false}>
            Display name, as shown to other users. May contain emojis and any Unicode character.
        </Property>
        <Property name="fields" type="Field[]" required={false}>
            Custom key/value pairs. For example, metadata like socials or pronouns. Must be text format (`text/*`).

            ```typescript
            type Field = {
                key: ContentFormat;
                value: ContentFormat;
            }
            ```
        </Property>
        <Property name="username" type="string" required={true}>
            Alpha-numeric username. Must be unique within the instance. **Must** be treated as changeable by the user.

            Can only contain the following characters: `a-z` (lowercase), `0-9`, `_` and `-`. Should be limited to reasonable lengths.
        </Property>
        <Property name="header" type="ContentFormat" required={false} typeLink="/structures/content-format">
            A header image for the user's profile. Also known as a cover photo or a banner. Must be an image format (`image/*`).
        </Property>
        <Property name="public_key" type="PublicKey" required={true}>
            The user's public key. Must follow the [Lysand Public Key](/signatures) format. `actor` may be a URI to another user's profile, in which case this key may allow the user to act on behalf of the other user (see [delegation](/delegation)).

            ```typescript
            type URI = string;

            type PublicKey = {
                actor: URI;
                public_key: string;
            }
            ```
        </Property>
        <Property name="manually_approves_followers" type="boolean" required={true}>
            If `true`, the user must approve any new followers manually. If `false`, followers are automatically approved. This does not affect federation, and is meant to be used for clients to display correct UI.
        </Property>
        <Property name="indexable" type="boolean" required={true}>
            User consent to be indexed by search engines. If `false`, the user's profile should not be indexed.
        </Property>
        <Property name="inbox" type="URI" required={true} typeLink="/types#uri">
            The user's federation inbox. Refer to the [federation documentation](/federation).

            Some instances may have a shared inbox, in which case that should be used instead. Refer to [Server Metadata](/entities/server-metadata) for more information.
        </Property>
        <Property name="collections.outbox" type="URI" required={true} typeLink="/types#uri">
            The user's federation outbox. Refer to the [federation documentation](/federation).
        </Property>
        <Property name="collections.followers" type="URI" required={true} typeLink="/types#uri">
            User's followers. URI must resolve to a [Collection](/structures/collection) of [User](/entities/users) entities.
        </Property>
        <Property name="collections.following" type="URI" required={true} typeLink="/types#uri">
            Users that the user follows. URI must resolve to a [Collection](/structures/collection) of [User](/entities/users) entities.
        </Property>
        <Property name="collections.likes" type="URI" required={true} typeLink="/types#uri">
            User's likes. URI must resolve to a [Collection](/structures/collection) of [Like](/entities/likes) entities.
        </Property>
        <Property name="collections.dislikes" type="URI" required={true} typeLink="/types#uri">
            User's dislikes. URI must resolve to a [Collection](/structures/collection) of [Dislike](/entities/dislikes) entities.
        </Property>
        <Property name="collections.featured" type="URI" required={true} typeLink="/types#uri">
            [Notes](/entities/notes) that the user wants to feature (also known as "pin") on their profile. URI must resolve to a [Collection](/structures/collection) of [Note](/entities/notes) entities.
        </Property>
    </Properties>

  </Col>
  <Col sticky>

    ```jsonc {{ 'title': 'Example User' }}
    {
        "id": "018ec082-0ae1-761c-b2c5-22275a611771",
        "type": "User",
        "uri": "https://social.lysand.org/users/018ec082-0ae1-761c-b2c5-22275a611771",
        "created_at": "2024-04-09T01:38:51.743Z",
        "avatar": { // [!code focus:100]
            "image/png": {
                "content": "https://avatars.githubusercontent.com/u/30842467?v=4"
            }
        },
        "bio": {
            "text/html": {
                "content": "<p>🌸🌸🌸</p>"
            },
            "text/plain": {
                "content": "🌸🌸🌸"
            }
        },
        "collections": {
            "dislikes": "https://social.lysand.org/users/018ec082-0ae1-761c-b2c5-22275a611771/dislikes",
            "featured": "https://social.lysand.org/users/018ec082-0ae1-761c-b2c5-22275a611771/featured",
            "followers": "https://social.lysand.org/users/018ec082-0ae1-761c-b2c5-22275a611771/followers",
            "following": "https://social.lysand.org/users/018ec082-0ae1-761c-b2c5-22275a611771/following",
            "likes": "https://social.lysand.org/users/018ec082-0ae1-761c-b2c5-22275a611771/likes",
            "outbox": "https://social.lysand.org/users/018ec082-0ae1-761c-b2c5-22275a611771/outbox",
        },
        "display_name": "April The Pink (limited Sand Edition)",
        "extensions": {
            "org.lysand:custom_emojis": {
                "emojis": []
            }
        },
        "fields": [
            {
                "key": {
                    "text/html": {
                        "content": "<p>Pronouns</p>"
                    }
                },
                "value": {
                    "text/html": {
                        "content": "<p>It/its</p>"
                    }
                }
            }
        ],
        "header": null,
        "inbox": "https://social.lysand.org/users/018ec082-0ae1-761c-b2c5-22275a611771/inbox",
        "indexable": false,
        "manually_approves_followers": false,
        "public_key": {
            "actor": "https://social.lysand.org/users/018ec082-0ae1-761c-b2c5-22275a611771",
            "public_key": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
        },
        "username": "aprl"
    }
    ```

  </Col>
</Row>