This proposal specifies semantic request routing for ActivityPub servers: an approach to dispatching incoming activities by following the relationships declared within ActivityStreams objects and dereferencing objects using opaque URIs rather than parsing or pattern-matching URL path segments. Semantic routing treats all ActivityPub URIs as opaque identifiers and decouples implementation behavior from any particular URI path structure.
Most existing servers implement “path-based routing,” where the handler and
target actor are determined from path segments such as /users/:username/inbox.
This tight coupling makes it hard to migrate between software implementations
without breaking URIs and violates the URI Opacity Axiom, since semantics
are inferred from paths that are implementation-dependent.
Semantic routing instead relies on dereferencing ActivityStreams objects and
using relationships to identify and validate inbox and outbox endpoints. This allows URIs to remain
stable across implementations, simplifying migration scenarios where the domain does not change.
ActivityPub federation works by looking up the target actor’s inbox and POSTing
activities to it. The Social API works by POSTing activities to an actor’s outbox. ActivityPub documents are dereferenced (GET) using their id (URI).
Most ActivityPub servers route these requests based on a predefined URI path structure. This path-based approach has several drawbacks.
URI lock-in: actor URIs minted by one implementation generally cannot be reused unchanged by another, because the new software expects different path shapes. Migrations either constrain software choice to preserve old paths or force new actor URIs, breaking links and federated state. Even when using a custom domain, it is generally not possible to migrate ActivityPub content from one implementation to another because of differing requirements for URI path shapes.
Violation of URI opacity: “The only thing you can use an identifier for is to refer to an object. When you are not dereferencing, you should not look at the contents of the URI string to gain other information. – Tim Berners-Lee, 1996 [ref]”
By shifting routing decisions from URI path analysis to graph traversal over ActivityStreams objects, semantic routing eliminates these problems and allows implementations to support flexible URI layouts.
This proposal:
The proposal does not modify ActivityPub or ActivityStreams. It adds constraints on implementation strategy while leaving the wire protocol unchanged.
This specification constrains only top-level request handling:
POST to an actor box (inbox, outbox, sharedInbox)GET resolve an ActivityPub/ActivityStreams object IDA POST to other URIs can use similar techniques, but since ActivityPub doesn’t define
these kinds of posts, it is outside the scope of this document.
Internal subhandler selection (for example, by activity type, recipient conditions, or local policy checks) is an implementation detail and is out of scope as long as it is not dependent on a specific URI structure.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119.
This specification defines requirements for one conformance class:
All of Section requirements are normative. All examples, notes, and sections explicitly labelled “non-normative” are informative.
Note: Implementations that satisfy the requirements in this document remain fully conformant with ActivityPub. The requirements here constrain how routing is performed, not what is placed on the wire.
In a typical fediverse server using path-based routing, a web framework (such as Rails, Django, Express, or Flask) is configured with a route table mapping URI path patterns to controller functions. When an ActivityPub activity arrives addressed to a local actor, the server:
https://social.example/users/alice/inbox./users/alice/inbox against the route pattern /users/:username/inbox.alice as the username.alice in the local database.alice’s database record.A representative path-based route table from a pseudocode web framework:
POST /users/:username/inbox → inbox_controller(username)
GET /users/:username/outbox → outbox_controller(username)
GET /users/:username → actor_controller(username)
GET /users/:username/followers → followers_controller(username)
GET /users/:username/following → following_controller(username)
The critical characteristic is that the username portion of the path is
authoritative for dispatch.
Because the routing table defines the valid URI patterns for actor endpoints, changing software means either:
Preserving the identical URI patterns: The new software must implement
the same path convention as the old software. This constrains software
selection and prevents adoption of implementations that use different path
structures such as /ap/actors/:id/inbox, /:username/inbox, or
/inbox/:uuid.
Minting new URIs: The actor gets a new id, breaking all federated
relationships. Every remote server that cached the old actor document now
holds a stale record. Followers are lost unless a manual re-follow campaign
is conducted.
Neither option is satisfactory. The ActivityPub specification provides no URI migration mechanism precisely because URIs are supposed to be stable, opaque identifiers.
Example: migration failure with path-based request routing:
A community server running SoftwareA uses actor URIs of the form
https://community.example/users/alice, with inbox at
/users/alice/inbox.
The community migrates to SoftwareB, which uses actor URIs of the
form https://community.example/alice, with inbox at
/inboxes/alice.
All existing actor URIs are now invalid. Remote servers that delivered
activities to /users/alice/inbox receive HTTP 404 responses.
The actor’s followers on remote servers reference the old actor id,
which no longer resolves.
If both SoftwareA and SoftwareB implemented semantic request routing, the migration would be a simple transfer of content with not changes to URIs.
URI opacity is the foundation of semantic routing. Routing decisions MUST NOT depend on the syntactic structure of a URI’s path, query, or fragment components.
A Semantically Routing Server MUST NOT parse the path, query string, or fragment of an incoming request URI to determine the identity of the target actor or the type of endpoint being accessed (inbox, outbox, etc.).
When a Semantically Routing Server receives an HTTP request, it MUST NOT depend on the syntactic structure of a URI’s path, query, or fragment components to handle it.
This section is non-normative.
Although it may be possible to implement semantic routing using other algorithms, this section shows pseudo-code for a possible implementation. This proposal does not include details like authorization or other security considerations that are not uniquely related to semantic request routing.
attributedTo, if present, orinbox or outbox reference to resource (conceptually, a graph search)inbox or outbox, dispatch to related handlertype and object.Example:
POST /x/9f3c1 HTTP/1.1
Host: social.example
Content-Type: application/activity+json
{
"@context": "https://www.w3.org/ns/activitystreams",
"id": "https://remote.example/activities/abcd",
"type": "Follow",
"actor": "https://remote.example/users/bob",
"object": "https://social.example/actors/alice"
}
Where https://social.example/x/9f3c1 is an opaque URI that happens to be Alice’s inbox,
the server can process the request semantically as follows:
https://social.example/x/9f3c1 to obtain the local inbox resource.attributedTo),
or by resolving reverse links from actor resources that reference this inbox.inbox equal to
https://social.example/x/9f3c1.type: Follow, authorization checks, policy checks,
delivery side-effects, and response status).This algorithm works regardless of whether the inbox URI looks like
/users/alice/inbox, /inbox/42, or /x/9f3c1.
The same procedure is used for POST requests to outbox URIs.
For sharedInbox POST, the algorithm is similar but applied to each local inbox URI targeted for delivery.
For sharedInbox GET, the opaque URI is used to identify the request target. The dereferencing or construction of the resulting OrderedCollection is implementation-dependent.
TODO
This section is non-normative.
The Solid Protocol similarly treats resource URIs as opaque and uses link relations to discover associated resources. Solid’s approach to data pods, where access control and resource discovery are driven by linked metadata rather than URI structure parallels the motivation for semantic routing in ActivityPub.
CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
To the extent possible under law, the authors of this Fediverse Enhancement Proposal have waived all copyright and related or neighboring rights to this work.