kb-fediverse-federation-md

Stars8

Forks0

UpdatedMarch 13, 2026 at 03:15

Background knowledge about FEP-67ff FEDERATION.md, the convention for documenting federation behavior in Fediverse projects. Covers the specification requirements (valid Markdown, repository root location), suggested template sections (protocols, FEPs, ActivityPub details), machine-readable discovery via NodeInfo 2.1 software.repository, the companion FEP-c893 (DOAP JSON-LD for automated capability discovery), the origin story (Darius Kazemi's 2020 proposal, WriteFreely as first adopter), the interoperability documentation gap FEDERATION.md solves, real-world examples from Mastodon and WordPress, and the 40+ implementations that have adopted it. Load when the user asks about FEDERATION.md; how to document federation behavior; FEP-67ff; what protocols or FEPs a project supports; how to create interoperability documentation for a Fediverse project; how other projects document their ActivityPub implementation; or machine-readable federation capability discovery with DOAP.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

reiver

reiver/vibefed

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Computer Occupations, All OtherComputer and Mathematical Occupations·SOC 15-1299

Software DevelopersSOC 15-1252

SKILL.md

readonly

More from this repository

same repository

kb-mastodon

reiver/vibefed

Background knowledge about Mastodon, the dominant federated microblogging platform and de facto reference implementation for ActivityPub social networking. Covers Mastodon's JSON-LD @context structure (three-element array: activitystreams, security/v1, inline object defining toot: http://joinmastodon.org/ns# with Emoji/discoverable/featured/featuredTags/ blurhash/votersCount/indexable/memorial/suspended/attributionDomains, schema: http://schema.org# with PropertyValue/value, as: with Hashtag/manuallyApprovesFollowers/movedTo/sensitive), content-type and Accept header requirements (application/activity+json or application/ ld+json with ActivityStreams profile, content negotiation for actor discovery), HTTP signature requirements (RSA-SHA256, Digest header mandatory for POST, signed headers include request-target/host/date/ digest), authorized fetch / secure mode (AUTHORIZED_FETCH env var, requires signatures on GET requests too, breaks unsigned federation), supported object types (Note and Question first-class

2026-03-238

kb-writefreely

reiver/vibefed

Background knowledge about WriteFreely, the open-source federated blogging platform written in Go (AGPL-3.0) by Matt Baer / Musing Studio. Covers the origin story (Write.as anonymous writing platform launched 2014, open-sourced as WriteFreely November 2018 after adding ActivityPub), the write-only/broadcast federation model (blogs can be followed but cannot follow others, no incoming comments/replies displayed, no moderation), the actor model (each blog/collection is a Person actor with handle @blog@instance.com), the Article vs Note object type distinction (double-line break heuristic, notes_only config option), supported activities (outbound Create/Update/Delete, inbound Follow/Undo/Like), RSA-SHA256 HTTP signatures with per-blog keypairs, the tech stack (Go/MySQL or SQLite/single binary deployment/256 MB RAM/Raspberry Pi), configuration (single-user vs multi-user modes, federation toggle, .ini config file), NodeInfo with WriteFreely-specific metadata, the RESTful API (Posts/Collections/Users with token aut

2026-03-148

kb-mbin

reiver/vibefed

Background knowledge about Mbin, the federated content aggregator and microblogging platform (active community fork of Kbin). Covers the hybrid dual content model (threads as Page + microblogs as Note in one platform), magazines as Group actors with Announce relay, the three actor types (Application instance actor at /i/actor, Person user at /u/username, Group magazine at /m/name), the full activity reference (Create, Update, Delete, Like, Dislike, Announce, Follow, Accept, Block, Flag, Lock, Add, Remove), the voting system (Like for upvotes, Dislike for downvotes with historical federation issues, Announce for boosts — boosts and votes are separate unlike Lemmy), the hybrid thread+microblog model and why it enables superior Mastodon integration, the tech stack (PHP 8.3+/Symfony 7.4/ PostgreSQL/RabbitMQ/Redis, AGPL-3.0), the async message processing architecture (Symfony Messenger with 15 inbox + 15 outbox message types), the REST API with OAuth2 and Swagger docs, the Mbin fork history (forked from Kbin Octob

2026-03-148

kb-nodebb

reiver/vibefed

Background knowledge about NodeBB, the modern open-source forum software built on Node.js with native ActivityPub federation (core feature since v4.0.0, January 2025). Covers the three actor types (Person user at /u/username, Group category at /category/<cid> implementing FEP-1b12 Group Federation with Announce relay pattern, Application instance actor), the two-level content hierarchy (category as audience → topic as context → post), how topics map to resolvable OrderedCollection contexts per FEP-7888 and posts are Note/Article objects, extensive FEP support (12 implemented: FEP-1b12 Group Federation, FEP-7888 context property, FEP-f228 Backfilling Conversations, FEP-4f05 Soft Deletion, FEP-9098 Custom emojis, FEP-b2b8 Long-form Text, FEP-fe34 Origin-based security, FEP-ae0c Relay Protocols, FEP-11dd Context Ownership, FEP-f15d Context Relocation, FEP-fb2a Actor metadata, FEP-0151 NodeInfo), the tech stack (Node.js/WebSocket/Socket.IO/ MongoDB or Redis or PostgreSQL, GPL-3.0), content discovery (follow- base

2026-03-138

kb-kbin

reiver/vibefed

Background knowledge about Kbin and its active community fork Mbin, the decentralized content aggregator and microblogging platform for the Fediverse (Reddit + Mastodon hybrid). Covers the dual content model (threads/link aggregation via Page objects + microblogging via Note objects in a single platform), magazines as Group actors with Announce relay (same pattern as Lemmy communities), the three actor types (Application instance actor at /i/actor, Person user at /u/username, Group magazine at /m/name), supported activities (Follow, Like, Announce, Create, Update, Delete, Block, Flag, Lock, Add, Remove), the critical detail that downvotes do NOT federate, content object mapping (threads as Page, microblogs as Note, comments as Note with inReplyTo, private messages as ChatMessage), the tech stack (PHP 8.2+/Symfony/PostgreSQL/RabbitMQ/Redis, AGPL-3.0), the REST API with OAuth2 and Swagger docs at /api/docs, the Mbin fork history (Kbin discontinued after creator Ernest Wisniewski's absences, Mbin forked October

2026-03-138

kb-piefed

reiver/vibefed

Background knowledge about PieFed, the federated link aggregation and discussion platform (Python-based Reddit/Lemmy alternative in the Threadiverse). Covers PieFed's tech stack (Python/Flask, PostgreSQL, Celery/Redis, htmx, Jinja2, AGPL-3.0), the Lemmy-compatible ActivityPub implementation (Community as Group, Post as Page, Comment as Note, Like/Dislike voting, Announce relay pattern, ChatMessage for DMs), the unique Feed actor type (FEP-1d80 for federated multi- community collections), private/anonymous voting via proxy user profiles, additional activity types (EmojiReact, PollVote, ChooseAnswer for Q&A mode, Event objects with startTime/endTime), the 95%-Lemmy-compatible REST API (/api/alpha/ with Swagger docs, enabling Voyager/Interstellar/Blorp/Summit mobile apps), custom JSON-LD extensions (genAI, nsfl, flair, postingWarning, interactionPolicy, lemmy:tagsForPosts compatibility), the federation architecture (Celery async processing, Redis dedup with 90s TTL, RSA-SHA256 HTTP signatures, LD signature fallb

2026-03-138

name	kb-fediverse-federation-md
description	Background knowledge about FEP-67ff FEDERATION.md, the convention for documenting federation behavior in Fediverse projects. Covers the specification requirements (valid Markdown, repository root location), suggested template sections (protocols, FEPs, ActivityPub details), machine-readable discovery via NodeInfo 2.1 software.repository, the companion FEP-c893 (DOAP JSON-LD for automated capability discovery), the origin story (Darius Kazemi's 2020 proposal, WriteFreely as first adopter), the interoperability documentation gap FEDERATION.md solves, real-world examples from Mastodon and WordPress, and the 40+ implementations that have adopted it. Load when the user asks about FEDERATION.md; how to document federation behavior; FEP-67ff; what protocols or FEPs a project supports; how to create interoperability documentation for a Fediverse project; how other projects document their ActivityPub implementation; or machine-readable federation capability discovery with DOAP.
user-invocable	false

FEDERATION.md (FEP-67ff) — Complete Reference

Overview

FEDERATION.md is a convention for documenting how a project implements federation protocols. Formalized as FEP-67ff (authored by silverpill, status FINAL, finalized 2024-09-22), it provides a standardized location and format for interoperability documentation — analogous to README.md for project description or CONTRIBUTING.md for contributor guidelines.

The convention originated in January 2020 when Darius Kazemi (creator of gath.io) proposed a standard documentation file after struggling to understand how other servers handled federation. It grew organically to 12+ implementations before silverpill formalized it as a FEP in April 2023. Over 40 projects have now adopted it, including Mastodon, Pixelfed, Lemmy, WordPress ActivityPub, GoToSocial, and PeerTube.

1. Specification Requirements (RFC 2119)

Only two hard requirements:

It MUST be a valid Markdown document
It MUST be located in the root of a project's code repository (or, if documentation is located elsewhere, contain a link to that location)

Soft requirements (SHOULD):

It SHOULD enumerate implemented federation protocols and standards
It SHOULD list supported Fediverse Enhancement Proposals (FEPs)

The file "can have arbitrary structure and content" — the spec deliberately avoids mandating a rigid format, allowing each project to document what matters most for its federation behavior.

2. Suggested Template

The specification provides a reference template with these sections:

Supported Federation Protocols and Standards

List the protocols the project implements:

## Supported federation protocols and standards

- [ActivityPub](https://www.w3.org/TR/activitypub/) (Server-to-Server)
- [WebFinger](https://webfinger.net/)
- [HTTP Signatures](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures)
- [NodeInfo](https://nodeinfo.diaspora.software/)

Supported FEPs

List adopted Fediverse Enhancement Proposals:

## Supported FEPs

- [FEP-67ff: FEDERATION.md](https://codeberg.org/fediverse/fep/src/branch/main/fep/67ff/fep-67ff.md)
- [FEP-f1d5: NodeInfo in Fediverse Software](https://codeberg.org/fediverse/fep/src/branch/main/fep/f1d5/fep-f1d5.md)

ActivityPub-Specific Documentation

Detailed sections covering:

Profiles / actors
Posts / objects
Addressing and delivery
Content limits
Non-standard extensions
Known interoperability quirks

3. The Problem FEDERATION.md Solves

ActivityPub is a protocol specification that leaves many implementation details up to individual servers. Different implementations make different choices about:

Which Activity types they handle (some ignore Like, some ignore Announce)
How they represent custom content (BookWyrm reviews, Lemmy votes, Pixelfed photos)
What non-standard extensions they require (Mastodon's HTTP Signature requirements)
How they handle edge cases (username changes, content limits, private posts)

Before FEDERATION.md, the only way to understand another implementation's behavior was to read their source code, reverse-engineer through testing, or ask on forums. This was particularly painful because the Fediverse has dozens of implementations in different programming languages.

FEDERATION.md provides a single, predictable file location where developers can find all federation-relevant documentation. By placing it at the repository root as a Markdown file, it follows established open-source conventions (like README.md, CONTRIBUTING.md, LICENSE) and is immediately accessible via any code hosting platform.

4. Real-World Examples

Mastodon's FEDERATION.md

Mastodon's file documents:

Protocols: ActivityPub (S2S), WebFinger, HTTP Signatures, NodeInfo
FEPs: FEP-67ff, FEP-f1d5, FEP-8fcf, FEP-5feb, FEP-044f, and others
Detailed sections: profiles/actors, posts, addressing, content limits, non-standard extensions
Notes that Mastodon "largely follows the ActivityPub server-to-server specification but makes use of some non-standard extensions, some of which are required for interacting with Mastodon at all"

WordPress ActivityPub Plugin's FEDERATION.md

Documents support for:

ActivityPub S2S, WebFinger, HTTP Signatures, NodeInfo
Various FEPs including FEP-67ff itself and FEP-3b86 (Activity Intents)
Notes that it "largely follows ActivityPub's server-to-server specification, but makes use of some non-standard extensions"

Both files follow a similar structure — protocols section, FEPs section, then detailed ActivityPub documentation — but neither uses a rigid template. They adapted the convention to their needs.

5. Machine-Readable Discovery

Via NodeInfo 2.1

FEDERATION.md files can potentially be discovered automatically via NodeInfo 2.1's software.repository field, which points to the project's source code repository. A crawler could follow this link and look for FEDERATION.md at the repository root.

{
  "software": {
    "name": "mastodon",
    "version": "4.3.0",
    "repository": "https://github.com/mastodon/mastodon"
  }
}

From this, a tool can construct: https://github.com/mastodon/mastodon/blob/main/FEDERATION.md

Limitation

This approach requires the software.repository field (added in NodeInfo 2.1) and depends on the repository being publicly accessible. Many instances run forks or customized versions where the repository URL may not point to the right FEDERATION.md.

6. The DOAP Companion: FEP-c893

FEP-c893 (by AvidSeeker, status DRAFT, received July 2024) proposes a doap.jsonld file as a machine-readable companion to FEDERATION.md.

What DOAP Provides

A JSON-LD file using the DOAP (Description of a Project) vocabulary:

{
  "@context": {
    "doap": "http://usefulinc.com/ns/doap#",
    "foaf": "http://xmlns.com/foaf/0.1/"
  },
  "@type": "doap:Project",
  "doap:name": "Example Server",
  "doap:homepage": "https://example.com",
  "doap:description": {
    "@language": "en",
    "@value": "A federated social media server"
  },
  "doap:implements": [
    "https://www.w3.org/TR/activitypub/",
    "https://webfinger.net/"
  ],
  "doap:supportedFEPs": [
    "https://codeberg.org/fediverse/fep/src/branch/main/fep/67ff/fep-67ff.md"
  ],
  "doap:maintainer": {
    "@type": "foaf:Person",
    "foaf:name": "Alice Developer"
  }
}

Key Fields

Field	Purpose
`doap:name`	Project name
`doap:homepage`	Project website
`doap:description`	Multilingual description
`doap:repository`	Repository URLs
`doap:release`	Version and date information
`doap:implements`	Federation protocols supported
`doap:supportedFEPs`	Adopted FEPs
`doap:maintainer`	Project maintainers

Relationship to FEP-67ff

FEP-c893 is the machine-readable counterpart to FEP-67ff's human-readable FEDERATION.md. Together they provide both developer documentation and automated capability discovery. This pairing was inspired by XMPP's XEP-0453, which uses the same DOAP vocabulary for capability reporting.

7. Writing a FEDERATION.md

Step-by-Step Guide

Create the file at the root of your project repository
List supported protocols:
- ActivityPub (specify Server-to-Server, Client-to-Server, or both)
- WebFinger
- HTTP Signatures (specify draft version)
- NodeInfo (specify schema version)
- Any other protocols (Diaspora, Zot, OStatus, etc.)
List supported FEPs with links to the FEP specifications
Document ActivityPub behavior — this is the most valuable section:
- What Activity types your server sends and accepts
- What Object types your server creates and understands
- How inbox processing works for each Activity type
- Non-standard extensions or properties your server uses
- Known interoperability issues with specific implementations
Document addressing and delivery:
- How public/followers-only/direct addressing works
- Shared inbox support
- Relay support
Note known limitations:
- Activity types that are silently ignored
- Content types that receive degraded display
- Extension requirements for full interoperability

Best Practices

Keep it updated — outdated documentation is worse than no documentation, because it misleads implementers
Be specific about non-standard behavior — if your server requires something not in the ActivityPub spec (like Mastodon's HTTP Signature requirements), document it prominently
Include wire-format examples — JSON examples of actual activities your server sends and expects are more useful than prose descriptions
Document what you ignore — knowing that a server silently drops Like activities (like Lemmy does with standard Likes) saves implementers debugging time

8. Origin and History

Darius Kazemi's 2020 Proposal

In January 2020, Darius Kazemi (creator of gath.io, a federated event organizing service, and Fellow at the Berkman Klein Center for Internet & Society) proposed FEDERATION.md on SocialHub. He had been implementing federation for gath.io and felt implementers needed better documentation on server behavior.

His original FEDERATION.md had three sections:

Federation philosophy
Inbox behavior (what the server does when receiving various activities)
Web application-triggered activities (what the server sends in response to user actions)

Early Adoption Timeline

Date	Event
January 5, 2020	Darius Kazemi proposes FEDERATION.md on SocialHub
January 9, 2020	WriteFreely becomes first adopter
February 4, 2020	Zot (Hubzilla family) adopts
February 8, 2020	Discussed at W3C Social CG meeting
March–October 2020	tavern, Smithereen, Lemmy adopt
April 2023	silverpill proposes FEP-67ff (~12 implementations)
September 5, 2023	FEP-67ff received as DRAFT
September 22, 2024	FEP-67ff achieves FINAL status
Present	40+ implementations

Key Observation

The convention grew organically for over 3 years before being formalized as a FEP. This "convention first, spec second" approach means FEP-67ff codified existing practice rather than inventing new requirements — a pattern that contributed to its successful adoption and FINAL status.

9. Implementations

Over 40 projects have adopted FEDERATION.md, including:

Project	Category
Mastodon	Microblogging
Pleroma / Akkoma	Microblogging
GoToSocial	Microblogging
Pixelfed	Photo sharing
PeerTube	Video sharing
Lemmy	Link aggregation
BookWyrm	Book reviews
WriteFreely	Long-form writing
Friendica	Social networking
Hubzilla	Social networking
Funkwhale	Music sharing
WordPress ActivityPub	Blogging plugin
Mitra	Microblogging
Smithereen	Social networking
Bonfire	Social networking

10. Capability Discovery Landscape

FEDERATION.md addresses documentation but not machine-readable discovery. Several other FEPs tackle the machine-readable side:

FEP	Approach	Machine-readable?	Status
FEP-67ff	FEDERATION.md documentation	No (human only)	FINAL
FEP-c893	DOAP JSON-LD companion file	Yes	DRAFT
FEP-6481	IRI list in NodeInfo metadata	Yes	WITHDRAWN
FEP-9fde	Reverse-FQDN operations in NodeInfo	Yes	DRAFT
FEP-eb22	Type lists in NodeInfo	Yes	DRAFT
FEP-844e	Capability URIs on AP actors	Yes	DRAFT

FEP-67ff is the only capability-related FEP to reach FINAL status. Its success is partly because it focused on the simplest possible requirement (a Markdown file) rather than trying to solve machine-readable discovery.

11. Known Issues

No standard structure — every project formats their FEDERATION.md differently, making automated parsing impossible. This is by design (the spec explicitly allows arbitrary structure) but limits tooling.
Freshness problem — there is no mechanism to verify whether a FEDERATION.md is up-to-date. Some files document features from years ago that may have changed.
Discovery gap — finding a project's FEDERATION.md requires knowing the repository URL. NodeInfo 2.1's software.repository field helps but is not universally implemented.
No machine-readable companion at scale — FEP-c893 (DOAP) exists as a DRAFT but has limited adoption. The Murmurations protocol was proposed as an alternative in 2021 but was not adopted.
Fork divergence — many Fediverse instances run forks or customized versions. The upstream FEDERATION.md may not accurately describe a particular instance's behavior.