This document is not complete. Please check back soon for updates.
com.atproto.handle.resolve()
API. Often a PDS.ATP uses a light wrapper over HTTPS called XRPC. XRPC uses Lexicon, a global schema system, to unify behaviors across hosts. The atproto.com lexicons enumerate all XRPC methods used in ATP.
The following identifiers are used in ATP:
Identifier | Usage |
---|---|
Domain names | A unique global identifier which weakly identify repositories. |
DID | A unique global identifier which strongly identify repositories. |
NSID | A unique global identifier which identifies record types and XRPC methods. |
TID | A timestamp-based ID which identifies records. |
Domain names (aka "handles") weakly identify repositories. They are a convenience which should be used in UIs but rarely used within records to reference data as they may change at any time. The repo DID is preferred to provide a stable identifier.
DIDs are unique global identifiers which strongly identify repositories. They are considered "strong" because they should never change during the lifecycle of a user. They should rarely be used in UIs, but should always be used in records to reference data.
ATP supports two DID methods:
did:web
). Should be used only when the user is "self-hosting" and therefore directly controls the domain name & server. May also be used during testing.did:plc
). A method developed in conjunction with ATP to provide global secure IDs which are host-independent.DIDs resolve to "DID Documents" which provide the address of the repo's host and the public key used to sign the repo's updates.
ATP uses the at://
URI scheme (specified here). Some example at
URLs:
Repository | at://alice.host.com |
Repository | at://did:plc:bv6ggog3tya2z3vxsub7hnal |
Collection | at://alice.host.com/io.example.song |
Record | at://alice.host.com/io.example.song/3yI5-c1z-cc2p-1a |
Record Field | at://bob.com/io.example.song/3yI5-c1z-cc2p-1a#/title |
ATP uses strict schema definitions for XRPC methods and record types. These schemas are identified using NSIDs and defined using Lexicon.
A "repository" is a collection of signed records.
It is an implementation of a Merkle Search Tree (MST). The MST is an ordered, insert-order-independent, deterministic tree. Keys are laid out in alphabetic order. The key insight of an MST is that each key is hashed and starting 0s are counted to determine which layer it falls on (5 zeros for ~32 fanout).
This is a Merkle tree, so each subtree is referred to by its hash (CID). When a leaf is changed, every tree on the path to that leaf is changed as well, thereby updating the root hash.
The repository data layout establishes the units of network-transmissible data. It includes the following three major groupings:
Grouping | Description |
---|---|
Repository | Repositories are the dataset of a single "user" in the ATP network. Every user has a single repository which is identified by a DID. |
Collection | A collection is an ordered list of records. Every collection is identified by an NSID. Collections only contain records of the type identified by their NSID. |
Record | A record is a key/value document. It is the smallest unit of data which can be transmitted over the network. Every record has a type and is identified by a TID. |
Every node is an IPLD object (dag-cbor to be specific) which is referenced by a CID hash.
Node Type | Description |
---|---|
Signed Root ("commit") |
The Signed Root, or “commit”, is the topmost node in a repo. It contains:
|
Root |
The Root node contains:
|
MST Node |
The Merkle Search Tree Nodes contain:
|
MST Entry |
The Merkle Search Tree Entries contain:
|
All data in the repository is encoded using CBOR. The following value types are supported:
null
|
A CBOR simple value (major type 7, subtype 24) with a simple value of 22 (null). |
boolean
|
A CBOR simple value (major type 7, subtype 24) with a simple value of 21 (true) or 20 (false). |
integer
|
A CBOR integer (major type 0 or 1), choosing the shortest byte representation. |
float
|
A CBOR floating-point number (major type 7). All floating point values MUST be encoded as 64-bits (additional type value 27), even for integral values. |
string
|
A CBOR string (major type 3). |
list
|
A CBOR array (major type 4), where each element of the list is added, in order, as a value of the array according to its type. |
map
|
A CBOR map (major type 5), where each entry is represented as a member of the CBOR map. The entry key is expressed as a CBOR string (major type 3) as the key. |
Repo records are CBOR-encoded objects (using only JSON-compatible CBOR types). Each record has a "type" which is defined by a lexicon. The type defines which collection will contain the record as well as the expected schema of the record.
ATP uses dollar ($
) prefixed fields as system fields. The following fields are given a system-meaning:
Field | Usage |
---|---|
$type |
Declares the type of a record. (Required) |
$ext |
Contains extensions to a record's base schema. |
$required |
Used by extensions to flag whether their support is required. |
$fallback |
Used by extensions to give a description of the missing data. |
The client-to-server API drives communication between a client application and the user's PDS. The APIs are dictated by the lexicons implemented by the PDS. It's recommended that every PDS support the full atproto.com lexicon. Application-level lexicons such as bsky.app are also recommended.
The com.atproto.* lexicons provides the following behaviors:
For ATP to be practically useful, it needs to support a variety of sophisticated queries and behaviors. While these sophisticated behaviors could be implemented on the user device, doing so would perform more slowly than on the server. Therefore, the PDS is expected to implement lexicons which provide higher-level APIs. The reference PDS created by Bluesky implements the bsky.app lexicon.
The server-to-server APIs enable federation, event delivery, and global indexing. They may also be used to provide application behaviors such as mail delivery and form submission.
The AT Protocol will launch soon.
Join the waitlist to try the beta before it's publicly available.