Proposed last year by @darius in Documenting federation behavior in a semi-standard way? proposed the FEDERATION.md convention, and discussed in SocialCG 2020-02-08 was the convention to have a FEDERATION.md in the root of code repositories of a federated application project, to describe in what ways the app implements its federated messages.
FEDERATION.md was a concession. With it the interoperability capabilities of a federated apps can be described by:
- NodeInfo: A per-server machine-readable definition, with basic metadata about the server
- FEDERATION.md: Hand-written doc to describe interoperability in detail, side effects, business logic, etc.
Standardizing full capability negotiation in a machine-readable format was deemed too complex.
Since then a handful of projects have committed to the convention:
As fedi developers we need to know how Fediverse evolves, which AS/AP extensions are in use, and preferably adopt them ourselves or even standardize them (using the Fediverse Enhancement Proposals process.
Ideally we want to have a clear overview of all interoperability designs, both standards-based and custom extensions, in use today without having to hop around and search for info across the web.
Even if there is a FEDERATION.md document, they are all formatted differently, and it is unclear whether they are kept up-to-date at all. This makes maintaining of a directory hard and time-consuming.
The FEDERATION.md convention is not known by most AP devs, can be streamlined, and provide more incentives to adhere to it.
A possible solution that goes a step further than informal FEDERATION.md documents, but still stays well away from tackling the complexity of a machine-readable capability negotiation standard, is to use the Murmurations Protocol to describe how federation is implemented in each app.
Primary goal is to deliver consistent documentation on how interop can be achieved, in the form of a document template.
Secondary goal is to make it easy to discover this documentation, regardless of where an implementation keeps track of it.
The document template could be set up in such way that it can be read as a checklist by someone implementing a compliant app, describing side-effects, validation and other rules.
Define a JSON-LD Murmurations Profile that is document template to describe AP interoperability support.
Fediverse projects maintain their own profile, and register it with The Murmurations Index.
- They can use it for their own website to generate reference documentation from it.
A SocialHub-affiliated website functions as the Murmurations Aggregator and generates a Directory of docs.
By creating a profile there is assurance that all projects deliver consistent content. There can be a bunch of additional metadata in it, such as ‘Last updated’ or ‘Release Version’ to gauge relevance. And ‘Issue Tracker’, ‘Repositories’, ‘Project lead’ and other project metadata to ease inquiries and contributions. Etcetera.
This topic has been split, see also: Federating the Murmurations Protocol