Users

The User entity represents an account on a Versia instance. Users can post Notes, follow other users, and interact with content. Users are identified by their id property, which is unique within the instance.

Addresses

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

@username@instance
@id@instance

For example:

@jessew@versia.social
@018ec082-0ae1-761c-b2c5-22275a611771@versia.social

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.

Instance

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

Entity Definition

  • Name
    avatar
    Type
    ContentFormat
    Description

    The user's avatar. Must be an image format (image/*).

  • Name
    bio
    Type
    ContentFormat
    Description

    Short description of the user. Must be text format (text/*).

  • Name
    display_name
    Type
    string
    Description

    Display name, as shown to other users. May contain emojis and any Unicode character.

  • Name
    fields
    Type
    Field[]
    Description

    Custom key/value pairs. For example, metadata like socials or pronouns. Must be text format (text/*).

    type Field = {
        key: ContentFormat;
        value: ContentFormat;
    }
    
  • Name
    username
    Required
    Required
    Type
    string
    Description

    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.

  • Name
    header
    Type
    ContentFormat
    Description

    A header image for the user's profile. Also known as a cover photo or a banner. Must be an image format (image/*).

  • Name
    public_key
    Required
    Required
    Type
    PublicKey
    Description

    The user's public key. Must follow the Versia Public Key format. actor may be a URI to another user's profile, in which case this key may allow the other user act on behalf of this user (see delegation).

    • algorithm: Must be ed25519 for now.
    • key: The public key in SPKI-encoded base64 (from raw bytes, not a PEM format). Must be the key associated with the actor URI.
    • actor: URI to a user's profile, most often the user's own profile.
    type URI = string;
    
    type PublicKey = {
        actor: URI;
        algorithm: string;
        key: string;
    }
    
  • Name
    manually_approves_followers
    Type
    boolean
    Description

    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. Defaults to false.

  • Name
    indexable
    Type
    boolean
    Description

    User consent to be indexed by search engines. If false, the user's profile should not be indexed. Defaults to true.

  • Name
    inbox
    Required
    Required
    Type
    URI
    Description

    The user's federation inbox. Refer to the federation documentation.

    Some instances may also have a shared inbox. Refer to Instance Metadata for more information.

  • Name
    collections
    Required
    Required
    Type
    UserCollections
    Description

    Collections related to the user. Must contain at least outbox, followers, following, and featured.

    type URI = string;
    
    type UserCollections = {
        outbox: URI;
        followers: URI;
        following: URI;
        featured: URI;
        // Same format as type on Extensions
        [key: ExtensionsKey]: URI;
    }
    

    All URIs must resolve to a Collection of the appropriate entities. Extensions may add additional collections.

    Outbox

    The user's federation outbox. Refer to the federation documentation.

    Followers

    User's followers. Collection of User entities.

    Following

    Users that the user follows. Collection of User entities.

    Featured

    Notes that the user wants to feature (also known as "pin") on their profile. Collection of Note entities.

Example User

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