# Versia

Versia is a federation protocol: signed JSON over HTTP, with a small core and namespaced extensions.

## Start

- [Introduction](/introduction.md): What the Versia Protocol covers, who this specification is for, and how to read it.
- [Principles](/principles.md): The core principles behind the design of the Versia protocol.
- [Other protocols](/other-protocols.md): How Versia's concepts map to ActivityPub and Matrix, for readers who know one of them.
- [Glossary](/glossary.md): The terms used in the Versia specification.
- [Security](/security.md): What Versia's security model protects, and what it leaves out.

## Foundations

- [Entities](/entities.md): The fields every entity has, how entities refer to each other, how they change and what transient entities are.
- [JSON](/json.md): The JSON rules that every Versia message follows.
- [Signatures](/signatures.md): How a message is signed and verified, and when a signature is required.

## Federation

- [Overview](/federation.md): How entities reach other instances: inboxes, delivery, access and ordering.
- [Discovery](/federation/discovery.md): How Versia instances can discover users, capabilities, and public keys.
- [Versions](/federation/versions.md): How Versia numbers protocol versions, and how instances choose one to talk to each other.
- [HTTP](/federation/http.md): How Versia uses the HTTP protocol for all communications between instances.
- [Endpoints](/federation/endpoints.md): Every route in Versia's federation API.

## Entities and structures

- [User](/entities/user.md): An account on an instance: its profile fields, address and username rules.
- [Subscribe](/entities/subscribe.md): How a User subscribes to another entity, such as a User: the Subscribe entity and the subscription's lifecycle.
- [SubscribeAccept](/entities/subscribe-accept.md): Accepts a pending Subscribe.
- [SubscribeReject](/entities/subscribe-reject.md): Rejects a pending Subscribe, or removes a subscriber.
- [Unsubscribe](/entities/unsubscribe.md): Ends a subscription, or cancels a pending subscription request.
- [Delete](/entities/delete.md): Tells other instances that an entity was deleted.
- [InstanceMetadata](/entities/instance-metadata.md): Metadata about a Versia instance, such as its capabilities and public key.
- [Collection](/structures/collection.md): Paginated lists of entities and of references to entities.
- [Media](/structures/media.md): How images, video, audio and other files are linked, with their media type and metadata.
- [RichText](/structures/rich-text.md): How formatted text is written: one HTML string, with a fixed set of elements that every receiver renders.

## Interoperability

- [Validation](/validation.md): What a receiver checks in an incoming entity, and what it answers when a check fails.
- [Example](/example.md): One note sent from one instance to another, step by step.
- [Links](/links.md): How Versia Links work and how they are used in the Versia Protocol.

## Extensions

- [Overview](/extensions.md): Extensions are a way to add custom functionality to Versia.
- [Custom Emojis](/extensions/custom-emojis.md): Adds custom emojis to any entity with text content.
- [Decorations](/extensions/decorations.md): Adds a User's header image, images around their avatar, a profile background and a profile sound.
- [Delegation](/extensions/delegation.md): Lets users show their actions under another user's name.
- [Domain Handles](/extensions/domain-handles.md): Lets users be shown by a domain they own, such as @joe.example.
- [Groups](/extensions/groups.md): Organizes users and notes into communities.
- [Instance Messaging](/extensions/instance-messaging.md): Lets instances send each other federation debug messages.
- [Interaction Controls](/extensions/interaction-controls.md): Lets users control who can interact with their notes.
- [Likes](/extensions/likes.md): Lets users like and dislike notes.
- [Migration](/extensions/migration.md): Lets users move their subscribers and subscriptions to another instance.
- [Polls](/extensions/polls.md): Lets users create and vote on polls.
- [Profile](/extensions/profile.md): Adds a User's bio, custom fields, pronouns, birthday, location and time zone.
- [Reactions](/extensions/reactions.md): Lets users react to notes with emojis.
- [Reports](/extensions/reports.md): Reports content to the moderators or administrators of a remote instance for review.
- [Share](/extensions/share.md): Lets users share notes with others.
- [Social](/extensions/social.md): Lets users post notes, with visibility, mentions, replies, quotes and a collection of each user's notes.

## Guides

- [Signing requests](/guides/signing-requests.md): A worked example of signing and verifying a Versia request.
- [Implementing a receiver](/guides/implementing-a-receiver.md): The checks an inbox runs on each request, with a link to the rule behind each one.

## Project

- [Changelog](/changelog.md): Changes to the Versia protocol since Working Draft 3, newest first.
- [SDKs](/sdks.md): The official Versia SDK, a TypeScript library for building Versia applications.