Extensions

Versia’s core provides users, subscriptions, and the rules for exchanging entities between instances. Everything else comes from extensions, which add entities, fields and behavior without any changes to the core. Posts, for example, come from the Social extension.

Extensions can be implemented in any combination that meets their requirements.

Extensions SHOULD be standardized and publicly documented.

Documented Extensions

These extensions are documented on this site, and all use the pub.versia namespace and are at version 1. See Naming for how their names are formed.

• Custom Emojispub.versia:custom_emojis

  Adds custom emojis to any entity with text content.

• Decorationspub.versia:decorations

  Adds a User's header image, images around their avatar, a profile background and a profile sound.

• Delegationpub.versia:delegation

  Lets users show their actions under another user's name.

• Domain Handlespub.versia:domain_handles

  Lets users be shown by a domain they own, such as @joe.example.

• Groupspub.versia:groups

  Organizes users and notes into communities.

• Instance Messagingpub.versia:instance_messaging

  Lets instances send each other federation debug messages.

• Interaction Controlspub.versia:interaction_controls

  Lets users control who can interact with their notes.

• Likespub.versia:likes

  Lets users like and dislike notes.

• Migrationpub.versia:migration

  Lets users move their subscribers and subscriptions to another instance.

• Pollspub.versia:polls

  Lets users create and vote on polls.

• Profilepub.versia:profile

  Adds a User's bio, custom fields, pronouns, birthday, location and time zone.

• Reactionspub.versia:reactions

  Lets users react to notes with emojis.

• Reportspub.versia:reports

  Reports content to the moderators or administrators of a remote instance for review.

• Sharepub.versia:share

  Lets users share notes with others.

• Socialpub.versia:social

  Lets users post notes, with visibility, mentions, replies, quotes and a collection of each user's notes.

An extension does not need to be listed here to be used. To propose one for this list, open an issue.

Handling Unsupported Extensions

When an extension is not supported by an Implementation, it can be ignored. This means that the extension is not processed, and its data is not used. Implementations MUST NOT throw an error when encountering an unsupported extension, as long as the rest of the entity is valid. An entity whose type comes from an unsupported extension is answered with a 2xx status code and dropped.

Extensions MUST NOT be designed in a way that makes them required to understand or process core entities, or the entities of an extension that does not require them.

Requirements

An extension can build on another, for example by adding interactions to entities that the other extension defines. It then requires that extension. Its page lists the extensions it requires, each with a version. For example, pub.versia:likes@1 requires pub.versia:social@1, because likes are given to Notes, which Social defines.

An Instance that lists an extension in compatibility.extensions MUST also list every extension it requires, at the required version. An extension MUST NOT require itself, directly or through other extensions.

Naming

Versia extension names are composed of two parts:

• The domain name of the extension author, in reverse order. Example: pub.versia
• The extension name, separated by a colon, in snake_case. Example: likes

pub.versia:likes

Entity Names

Custom entities are named in the same way, but with an additional part:

• The entity name, separated by a slash, in PascalCase. Example: Like

pub.versia:likes/Like

Versions

An extension’s version is a whole number that starts at 1, and goes up only when a change is incompatible. Extension keys, entity types and endpoints do not include it.

Instances list what they support in compatibility.extensions, as the extension name and version joined by @. They MAY list several versions of an extension.

pub.versia:likes@1

Two instances that both list an extension use the highest version they have in common. If they have none in common, the sender MUST leave out that extension’s data: its key in extensions, its entity types and its collections. The same applies when the version they would use requires an extension that they do not have in common at the required version.

Extension Definition

Extensions can add any of the following:

• Custom functionality on an existing entity, through its extensions property.
• New entity types, as custom entities.
• Collections on an entity.
• Endpoints.
• Interaction types.

Entity Extension

{
    "type": "pub.versia:groups/Group",
    "id": "033j6qrwzt002",
    "created_at": "2021-01-01T00:00:00Z",
    "open": true,
    "extensions": {
        "com.example:gps": {
            "location": {
                "latitude": 37.7749,
                "longitude": -122.4194
            },
            "accuracy": 10,
            "name": "San Francisco"
        }
    }
}

Custom Entity

{
    "type": "com.example:bookmarks/Bookmark",
    "id": "033fsr7ggg004",
    "author": "example.com:033wv9k6n0007",
    "created_at": "2021-01-01T00:00:00Z",
    "target": "example.com:033qtdbdkj006",
    "label": "Read later"
}

Collections

An extension’s collections are named like its custom entities, for example pub.versia:likes/Likes.

Endpoints

An extension’s endpoints MUST be under /.versia/v0.X/extensions/{extension_name}/. This keeps them from colliding with core endpoints or with other extensions. The extension name is not percent-encoded.

/.versia/v0.7/extensions/pub.versia:instance_messaging/messaging