## Overview

There are two main categories of SSB URIs: **Canonical** and **Experimental**. The conceptual difference between these two is that canonical SSB URIs make use of the **path component** in the URI to specify the resource, while experimental SSB URIs use _only_ the **query component** to specify the resource.

The third category, **Deprecated**, is used to denote canonical SSB URIs that MUST still be supported by application, but SHOULD be avoided whenever possible.

### Canonical SSB URIs

These SSB URIs are to be considered stable and universally acceptable by all SSB applications that support SSB URIs. They utilize the path component to specify "refs", i.e. identifiers for resources. SSB messages, feeds, and blobs **SHOULD** follow the respective syntaxes:

```
ssb:message/classic/
ssb:message/bendybutt-v1/
ssb:message/gabbygrove-v1/
ssb:message/buttwoo-v1/
ssb:message/indexed-v1/
ssb:feed/classic/
ssb:feed/bendybutt-v1/
ssb:feed/gabbygrove-v1/
ssb:feed/buttwoo-v1/
ssb:feed/buttwoo-v1//
ssb:feed/indexed-v1/
ssb:blob/classic/
```

Where ``, ``, `` are _URI-safe Base64 encoded_ strings that identify those refs. URI-safe Base64 is equivalent to Base64 where `+` characters are replaced with `-`, and `/` characters are replaced with `_`.

In the special case of `ssb:feed/buttwoo-v1//`, the `` is the URI-safe Base64 encoded data of a buttwoo-v1 message URI (i.e. `` from `ssb:message/buttwoo-v1/`).

**Examples:**

```
ssb:message/classic/g3hPVPDEO1Aj_uPl0-J2NlhFB2bbFLIHlty-YuqFZ3w=
ssb:message/bendybutt-v1/PR2-btDEO1AjXuPl0TJ2N_hFB2bbFLIHlty0VF1ncty=
ssb:feed/classic/-oaWWDs8g73EZFUMfW37R_ULtFEjwKN_DczvdYihjbU=
ssb:feed/bendybutt-v1/APaWWDs8g73EZFUMfW37RBULtFEjwKNbDczvdYiRXtA=
ssb:feed/gabbygrove-v1/FY5OG311W4j_KPh8H9B2MZt4WSziy_p-ABkKERJdujQ=
ssb:blob/classic/sbBmsB7XWvmIzkBzreYcuzPpLtpeCMDIs6n_OJGSC1U=
```

There are also new concepts related to [Private Groups](https://github.com/ssbc/private-group-spec) which need identifiers, such as:

- `ssb:encryption-key/box2-dm-dh/`
- `ssb:identity/po-box/`

Where `` are _URI-safe Base64 encoded_ strings, similar to the previous canonical SSB URIs.

**Multiserver address:**

```
ssb:address/multiserver?multiserverAddress=
```

Where `` is a [multiserver address](https://github.com/ssbc/multiserver-address) string, but [percent-encoded according to RFC3986 2.1](https://tools.ietf.org/html/rfc3986#section-2.1), for example:

```
ssb:address/multiserver?multiserverAddress=net%3Awx.larpa.net%3A8008~shs%3ADTNmX%2B4SjsgZ7xyDh5xxmNtFqa6pWi5Qtw7cE8aR9TQ%3D
```

### Colon-separated canonical SSB URIs

Canonical SSB URIs **SHOULD** use `/` to separate the parts of the path component, but they **MAY** also use `:` to separate the parts. The following syntax is acceptable (and is currently what `ssb-uri` utilizes, exclusively):

```
ssb:message:classic:
ssb:message:bendybutt-v1:
ssb:feed:classic:
ssb:feed:bendybutt-v1:
ssb:blob:classic:
ssb:address:multiserver?multiserverAddress=
```

### Experimental SSB URIs

These SSB URIs are free-form and allow developers to pass any parameters to SSB applications without requiring consensus among the SSB applications. These URIs have an _empty authority_ component and path component always matching `experimental` (this is to support Firefox's handling of custom schemes) but have a _non-empty query_ component. The query parameters are the only mechanism through which information is conveyed. They satisfy the syntax below (any number of parameters allowed, but we show two, for illustration):

```
ssb:experimental?=
ssb:experimental?=&=
```

#### Known experimental SSB URIs

Experimental SSB URIs do not need to be included in this specification before they can be used, but we encourage developers to submit all known experimental SSB URIs depended by applications. This facilitates the future canonicalization of new SSB URIs. Please feel free to submit new entries here, as long as you know they are used in applications:

**Action to join a room:**

Some experimental SSB URIs have the query `action` to describe intents to perform certain tasks in the SSB application.

A `action=claim-http-invite` experimental URI is used to refer to the consumption of a [Rooms 2](https://github.com/ssb-ngi-pointer/rooms2) invite code, syntax as follows, which includes a `multiserverAddress` query like the canonical multiserver address URI has too:

```
ssb:experimental?action=claim-http-invite&invite=&multiserverAddress=`
```