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
ISO8601
Description
Date and time when the entity was created. Must be an ISO 8601 formatted string.
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.
Some entity types may not need a URI. This will be specified in the entity's documentation.
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
        }
    }
}

Serialization

When serialized to a string, the JSON representation of an entity should follow the following rules:

Keys must be sorted lexicographically.
Should 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.