Re: "ActivityPub at one glance" diagram

> I do not think that we can explain ActivityPub in its entirety in one glance.

Agreed, but "in its entirety" is scope creep. That's what
specifications should be for. A diagram provides a high-level overview
of outboxes and inboxes.

> I think that far more useful than something technically complete and accurate but overwhelming is a diagram that is simplified but gets the point across and perhaps has a note that says "simplified, please see diagram X for the full map".

I would hardly call two lines "overwhelming", as this is already the
"simplified" view. The "please see X" link should refer to the
specification.

> The problem with
>
> https://activitypub.rocks/static/images/ActivityPub-tutorial-image.png
>
> is that it is correct but not very useful. The problem with a diagram that shows you can post straight to outboxes bypassing federation is that it doesn't describe ActivityPub in use today by 99% of message volume.

Posting to outbox isn't "bypassing federation", though? It's something
that (generally) happens *before* posting to the inbox (although you
can POST to inbox directly). That "POST to inbox" is the basis for
federation, but is a separate dimension than federation; federation
involves multiple authorities. "POST to inbox" becomes federation when
that inbox exists on a remote service outside of your local network
(local host, local domain, etc). ActivityPub can be used without
federation if all the outboxes and inboxes exist within a single
"local" service. In networks generally, this concept is known as
"local area network" (LAN) and "wider area network" (WAN). You have
authority locally, but the wider network operates on consensus
(typically rooted in the IANA, which manages things like IP addresses
and DNS names).

> Perhaps what Johannes is looking for is a diagram of "How ActivityPub can work in a federation context". Federation is the hardest part to get across to people, and one of the issues is that federation itself is not specified by ActivityPub, or indeed ANYWHERE. ActivityPub is a spec that supports federation, and federation is left as an exercise to the reader.

Is this what a visitor of activitypub.rocks is looking for, when
visiting a website ostensibly about a specification that they want to
learn more about? If the website were something like federation.rocks
or fediverse.rocks, this kind of goal would make sense. But the
website is activitypub.rocks, and should therefore be about
ActivityPub. There are other protocols that enable federation, like
IRC, SMTP, and XMPP. We have federated phone networks and federated
physical mailing. Per Johannes in the original email, the goal is to

> help communicate what ActivityPub is and how it is different from other protocols

, so "a general explanation of how federation works" might be useful
in general but not for specifically explaining what ActivityPub is or
how it works.

In https://lists.w3.org/Archives/Public/public-swicg/2025Sep/0064.html
I described two possible sections of the website's landing page, based
on the goal that a visitor might have. To repeat:

> it's possible for the website to have two sections immediately following
> each other, where the first section talks about the spec and the second
> section talks about what people have built inspired by it
>
> h1: "ActivityPub: A standard for the social web"
> p: "Specification by the World Wide Web Consortium (W3C) for publishing and
> subscribing to social activities"
>
> h2: "Follow what's happening across the web, and notify your audience of
> what you're doing"
> p: "ActivityPub works by defining a Follow activity, which allows you to
> signal interest in an actor's activities. When that actor publishes
> activities to their outbox, they can distribute those activities as
> notifications to a chosen audience. Activities sent to their followers will
> arrive in your inbox."
> cta: "Read the specification"
>
> h2: "Connect to a variety of social software and talk to an existing
> userbase"
> p: "ActivityPub has inspired a community of software developers to develop
> social software that comprises a loosely distributed network known as the
> Fediverse. These softwares differ in experience, but can interoperate with
> each other where there is overlap.
> cta: "See a list of implementations"

The distinction between "the ActivityPub specification" and "what
people have built inspired by it" is important to maintain, unless the
ActivityPub specification is to be deprecated entirely and replaced
with a living standard, which seems far outside the remit of the
Social CG to decide. It happened to HTML with the W3C and the WHATWG,
and it could happen to ActivityStreams and ActivityPub (if a "FediWG"
were to spring up), but that's up to implementers. I don't think it
does good to muddy the waters between de jure and de facto, unless we
want to also formalize a version of the Mastodon API, or Lemmy's usage
of Announce activities, or any number of other implementation-specific
"protocol" choices (in terms of whatever is required to communicate
without being misunderstood, that is). One would hope that they align
or converge over time, and that errors get fixed or cleaned up, but
the framing matters when talking about "what ActivityPub is". Although
it has been said that "the medium is the message", that is not exactly
true. Here, ActivityPub is the medium, and the message is whatever
various softwares might send over it. In terms of ActivityPub, we only
say "the message is an Activity", and then those softwares place
additional requirements. It is a monumental task to map out what those
requirements are for different softwares and different versions, which
is why I have in the past proposed exploration of this:

- https://lists.w3.org/Archives/Public/public-swicg/2024Nov/0010.html
- https://lists.w3.org/Archives/Public/public-swicg/2025Jun/0044.html

Really, we can go further and say that this applies to any received
message that we expect to trigger certain behaviors (usually, we call
this message a "method invocation" or "procedure call"). In
https://www.w3.org/TR/ldn/ we have a more general definition of an
inbox, which ActivityPub reuses while placing some additional
restrictions (LDN, but the payload is only an AS2 JSON-LD document
containing a single Activity). ActivityPub then defines its own
outbox, which allows publishing activities. The outbox activities can
then be delivered as Linked Data Notifications to the outbox. If many
softwares use their own proprietary APIs instead of POST to outbox,
then that doesn't mean ActivityPub "is" those proprietary APIs. That
just means those softwares are in fact monolithic ActivityPub
client-servers, where the outbox gets "POSTed" to internally, and then
that software will POST to inbox all the same -- from the outside, you
can generally treat this entire process as opaque.

But of course, this is all too much to put in a single "at a glance"
diagram, which is why I advocate that the diagram should follow the
two basic flows of information across outboxes and inboxes:

actor --> POST --> outbox --> POST --> inbox <-- GET <-- actor
actor --> POST --> outbox <-- GET <-- actor

Feel free to draw bounding boxes around any subset of this, but this
is what is logically happening, and this is what the original/current
activitypub.rocks diagram elided as the "rest of the world" magenta
cloud. for everything to the right of the outbox (or the inbox, if you
look at it in reverse:)

actor --> GET --> inbox <-- POST <-- [rest of the world]

The "rest of the world" on the receiving end can absolutely be any
HTTP agent capable of sending a POST request, although ActivityPub
generally assumes activities that arrive in your inbox were *probably*
posted to someone else's outbox first, so "rest of the world"
typically means "someone else's outbox delivery algorithm worker",
although in practice the HTTP request can come from anywhere or
anything, not necessarily an outbox. (I would argue that this is more
LDN than AP, but that's a very fine distinction since AP uses
ldp:inbox as previously mentioned.)

Received on Tuesday, 23 December 2025 23:37:05 UTC