Entities

Entities are the foundation of the Versia protocol. They are similar to:

ActivityStreams objects
Matrix 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.

Name
id
Required
Required
Type
string
Description
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.
Name
type
Required
Required
Type
string
Description
Type of the entity. Custom types must follow Extension Naming.
Name
created_at
Required
Required
Type
RFC3339
Description
Date and time when the entity was created. Must be an RFC 3339 timestamp.
Handling of dates that are valid but obviously incorrect (e.g. in the future) is left to the Implementation's discretion. Sending a Note created on 13-12-1337 is very funny, but don't be surprised if it is rejected.
Name
$schema
Type
string
Description
URL of any JSON Schema that the entity adheres to.
This is for human use only, and not to be used by either clients or servers as a way to validate the entity.
Name
extensions
Type
Extensions
Description
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.

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"
}

With Extensions

{
    "id": "f0aacf0b-df7a-4ee5-a2ba-6c4acafd8642",
    "type": "org.space:Zlorbs/Zlorb",
    "created_at": "2023-04-13T08:00:00Z",
    "extensions": { 
        "org.space:zlorbs": {
            "zlorb_type": "giant",
            "zlorb_size": "huge"
        },
        "pub.versia:location": {
            "latitude": 37.7749,
            "longitude": -122.4194
        }
    }
}

Transient Entities

Some entities are transient, meaning they cannot be fetched using the Federation API. 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.