TL;DR, please check out FEDERATION.md and tell me what you think about it.
Context: I am in the process of federating an existing service for organizing events and meetups called gath.io. The federated currently version lives at events.tinysubversions.com, and the source code for my branch is available here.
Because I’m building a federated service, I felt like I should add the documentation that I wish other federated services had: namely, something that describes how the server responds to and generates ActivityPub activities!
As a first pass, I have created a FEDERATION.md file that lives in the root of the repo. It is divided into three main sections:
I would like to see other implementations write up something similar to this. Maybe putting it in a FEDERATION.md file in the root could be a de facto standard.
Any thoughts on this? What’s missing that other ActivityPub implementors would like to know about the server? (I’m sure plenty is missing, as I just wrote this up in an hour.)
I very much agree that we need a solid place where we discuss the Codes and Codices of Interoperability.
For me this is the goal of the ActivityPub Events series itself.
If you read my 36c3 reflection there are some hints.
My personal opinion is to have it face to face or at least voice to voice.
My fear is about the balance of power :
History proved that when big players step in they try to set the Codices.
/me still suffering from a virus after a hackerconf but for sure I will write the same for redaktor – thank You.
This looks really cool! One high-level thing I noticed is that it might make more sense to start with the activities triggered by the web application (after the short federation philosophy/intro section), and then move into Inbox behavior. This makes the document flow better from a user-centric perspective, I think, which has two main benefits: 1) gath.io implementors reading it who may not be entirely familiar with federation have concrete user actions to ground them, and 2) activitypub implementors who may not be familar with gath.io have a clearer idea of the scope/scale of expected user behaviors.
The second thing that strikes me about gath’s federation (and this may be in complete contradiction to my first paragraph) is that it’s almost a “server-to-client” model—that is, you’re using the limited vocabulary of some existing federated clientservers to take tangible actions as a user on another application. That is, you’re almost using federation as a pure “front end” for gathio. This is interesting, and it’s something I’ve thought about doing before, but it’s definitely something not considered by any of the specs we have and even kind of flies in contradiction to the idealized activitypub “specialized clients, generic servers” model. I don’t think this is a bad decision! it seems like a logical but awkward conclusion to the world of specialized servers we’ve found ourselves in, and it definitely has value in the world today. I just wanted to note it as a point of general discussion.
(this is in contradiction to what I said above because if activitypub is a “front end” client for the imagined gath user, then incoming and outgoing actions are both user behaviors, so it doesn’t make as much difference which one comes first)
On specifics, the only thing I noticed that seemed kind of weird is the usage of Create/Note to denote replies to the event—most people have been using an Announce activity to handle “posting to a group” or similar events. What are your thoughts there? Why not just boost the original reply instead of duplicating it?
This is great and I think every federated service needs to do this. I will do this too. I have some questions however.
Is Event an actor after all? I’ve only ever seen it in the wild in Friendica, and there it’s used as an attachment to a post. I was going to have events myself so representing them in ActivityPub is still an open question. I personally was thinking about a Group with an Event in its attachments. Event isn’t an actor as per the spec, it’s an “object”.
How is this going to work with implementations that deliberately don’t support direct messages, like mine? As of yesterday’s update, I return 400 Bad Request to any Create{Note} that doesn’t contain as:Public in either to or cc.
Also since I was going to have events and the spec specifies the proper way of RSVPing to events (Invite{Event} and then Accept/Reject/TentativeAccept{Invite}), are there any plans to support that?
An Event is not an actor in my implementation. I try to be careful in the document about capital-E Event per the spec, versus an “event”, which is the thing that gathio describes. So:
an Event is an Object that is attached to an Activity and conforms to the AP spec
an event-the-thing-that-people-attend is an Actor; in this case I am representing it the actor as a Person because I don’t see a better choice (though maybe Service? I’m not sure that most implementations know how to represent that right now)
at this juncture I choose to interpret Person as an individual agent, rather than as an “individual person” per the AS Vocab spec
Great question. I’ll have to think about that. Right now your actors could still follow my actor and get normal public updates. But some correspondence between the human-actor and the event-actor should be private. I think they would simply have to go to the page and manually RSVP rather than doing it via federation.
Yes, definitely.
I will add the Accept/Reject/TentativeAccept Invite as a TODO to my list, along with the boosting that nightpool mentioned above.
Yes, I saw the commit and already updated Guide for new ActivityPub implementers that has a list of impls with a FEDERATION.md (or similar) And I added Smithereen earlier. If anyone else has one, pls update the wiki post.
I’m thinking about a FEP formalizing FEDERATION.md file. Here’s how it might look like:
# FEP-67ff: FEDERATION.md
## Summary
`FEDERATION.md` is a file containing information necessary for achieving interoperability with a federated service.
## Requirements
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 [RFC-2119](https://tools.ietf.org/html/rfc2119.html).
## Structure
The `FEDERATION.md` file can have arbitrary structure and content. The only requirements are:
- It MUST be a valid Markdown document.
- It MUST be located in the root of a project's code repository. If project's documentation is located in another place, the `FEDERATION.md` file may contain a link to that location.
- It SHOULD include a list of implemented federation protocols.
- It SHOULD include a list of supported Fediverse Enhancement Proposals (FEPs).
## Implementations
- [gathio](https://github.com/lowercasename/gathio/blob/a75aad783c117aaef2ec19b6b434be0f0d7e57de/FEDERATION.md)
What do you think? @darius Since this was your idea, perhaps you will be interested in submitting such proposal?
This looks like a decentralized version of @gabek 's nascent https://fedidocs.org/ site. Gabe, should we consider making that site fetch and ingest FEDERATION.md files and be a central rendering clearinghouse?
Yes, it may help encourage the practice. Though FEDERATION.md is up for further improvement… maybe starting with having a template for it, for sake of consistency in documentation. There may be a few more impls. I update Guide for new ActivityPub implementers when I encounter one (but I didn’t revisit to see if they all still exist).
And I added Smithereen earlier. If anyone else has one, pls update the wiki post.