Entities

Entities are the foundation of the Versia protocol. A similar concept to entities are the ActivityStreams objects, which are used to represent activities in the ActivityPub protocol.

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.

Name
id
Required
Required
Type
string
Description
Unique identifier for the entity. Must be unique within the instance. Can be any string. Max of 512 UTF-8 characters.
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.
Name
uri
Required
Required
Type
URI
Description
URI of the entity. Should be unique and resolve to the entity. Must be an absolute URI.
Transient Entities do not require a URI.
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": "9a8928b6-2526-4979-aab1-ef2f88cd5700",
    "type": "Delete",
    "created_at": "2022-01-01T12:00:00Z",
    "author": "https://bongo.social/users/63a00ab3-39b1-49eb-b88e-ed65d2361f3e",
    "deleted_type": "Note",
    "deleted": "https://bongo.social/notes/54059ce2-9332-46fa-bf6a-598b5493b81b",
}

With Extensions

{
    "id": "f0aacf0b-df7a-4ee5-a2ba-6c4acafd8642",
    "type": "org.space:Zlorbs/Zlorb",
    "created_at": "2023-04-13T08:00:00Z",
    "uri": "https://space.org/zlorbs/f0aacf0b-df7a-4ee5-a2ba-6c4acafd8642",
    "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 do not have a URI. These entities are used for actions that do not require a permanent record, such as deletions or migrations.

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 relevant User's private key, or the instance's private key if the entity is not associated with a particular user.
Must use Unix-style \n line endings (LF).