# Versia Links

How Versia Links work and how they are used in the Versia Protocol.

Versia Links are a way to reference entities in the Versia Protocol, in a way that can be handled by browsers and applications. They function the same way as `mailto:` links, but for Versia entities.

> Matrix has `matrix:` URIs and matrix.to links for the same purpose. ActivityPub has no equivalent. See [Other Protocols](/other-protocols#concepts).

## Syntax

**Parts**

- `scheme` (`string`, required): **MUST** be `web+versia://` so that browsers and applications can recognize it.

  An IANA registration for the `versia://` scheme will be requested in the future.

- `action` (`string`, required): Action to take on the entity. Can have multiple slashes as a way to segment the action.

  Possible actions:

  - `users/{instance}/{id}`: Open a user profile.
  - `users/{instance}/@{username}`: Open a user profile by username, [resolved through WebFinger](/federation/discovery).

  [Extensions](/extensions) can add actions, which their pages list. [Social](/extensions/social#versia-links) adds `notes`, `reply`, `quote` and `compose`, [Share](/extensions/share#versia-links) adds `share`, and [Groups](/extensions/groups#versia-links) adds `groups`.

- `instance` (`Domain`): Instance hosting the referenced content. **MUST** be present on every action whose definition includes `{instance}`.

An `{id}` is the entity's `id`, which cannot contain `@`, so a segment that starts with `@` always marks a username. Any other value in an action, such as the `{text}` of Social's `compose`, **MUST** be percent-encoded as a URI path segment.

```text title="Viewing a user profile"
web+versia://users/bob.example/0345pq3gy8004
```

```text title="Viewing a user profile by username"
web+versia://users/bob.example/@alice
```

## Handling

Versia clients **SHOULD** register themselves as handlers for the `web+versia://` scheme in the user's operating system. When a Versia Link is clicked, the client **SHOULD** open the entity in the client's interface.

The default web client ("frontend") on a Versia instance **SHOULD** also display Versia links for logged-out users on:

- Profiles
- The entities of extensions that add an action for them, such as Notes and Groups

This could be used for easier subscribing to users from remote instances.

Clients **SHOULD** ask users to confirm any action that is not a simple view action, such as replying to a note or sharing a note.