Request for Authoritative Documentation of Moderation Labels

[spencerthayer]

Summary:

Docs: Publish an authoritative list of all moderation-label values (current & planned)
Duplicate issue posted in atproto.

---

What’s missing

There is no single, official document that enumerates:

1. Every labels[].val string currently emitted by the core labeler @moderation.bsky.app (did:plc:ar7c4by46qjdydhdevvrndac), and
2. Additional values produced by first-party partner labelers such as @blacksky.app (did:plc:d2mkddsbmnrgr3domzg5qexf), plus any other labelers Bluesky formally endorses.

Developers are forced to reverse-engineer label names from UI strings, client source code, or scattered blog posts. That is brittle, error-prone, and undermines transparency.

---

Why it matters

Impact area	Consequence of missing docs
Developer integrations	Incomplete or incorrect filtering: clients can’t reliably map human-readable toggles to the actual val strings.
Moderation UX & accessibility	Users cannot meaningfully adjust safety settings without knowing what each label precisely covers.
Trust & transparency	Public clarity around safety tooling is table-stakes for any federated social network that aspires to open standards.
Future-proofing	As new labels (e.g., misogynoir, antiblack-harassment) roll out, lack of documentation creates breaking changes for third-party clients, bridges, and analytics tools.
Legal & policy compliance	Regulators and watchdogs increasingly expect platforms to disclose content-classification criteria.

---

Proposed solution

• Create docs/labels.md in this repo (or expand an existing page) containing:
  • A canonical table with the columns: Display name, val string, scope (post / account), description, owning labeler.
  • A short rationale for each label and how Bluesky expects clients to surface it (blur, warn, etc.).
  • A changelog section noting when labels are added, renamed, or retired.
• Expose a machine-readable endpoint (even a static JSON file in the repo) so client authors can programmatically keep in sync.
• Socialize a lightweight “label registry” process for first-party partner labelers: before deployment, new values get an entry in the doc and a version bump.

---

Reference table (current as of 2025-04-28)*

Below is a single master table that merges the built-in labels from @moderation.bsky.app (the official Bluesky labeler, DID did:plc:ar7c4by46qjdydhdevvrndac) with the two additional anti-harassment labels from @blacksky.app (DID did:plc:d2mkddsbmnrgr3domzg5qexf).

Display name (UI)	JSON val string (lower-case kebab)	Notes (what it flags)	Scope†	Labeler service (handle / DID)
Adult Content	porn	Explicit 18 + sexual content / pornography	post ✦ / account	@moderation.bsky.app  did:plc:ar7c4by46qjdydhdevvrndac
Sexually Suggestive	sexual	Erotic but not explicit	post ✦ / account	@moderation.bsky.app
Non-sexual Nudity	nudity	Artistic or non-erotic nudity	post ✦ / account	@moderation.bsky.app
Sexually Suggestive (Cartoon)	sexual-cartoon	Erotic drawings / animation	post ✦	@moderation.bsky.app
Graphic Media	graphic-media	Gore, violent or otherwise shocking imagery	post ✦	@moderation.bsky.app
Self-Harm	self-harm	Suicide or self-injury content	post ✦	@moderation.bsky.app
Sensitive	sensitive	Potentially disturbing, but not graphic	post ✦	@moderation.bsky.app
Extremist	extremist	Support or propaganda for extremist orgs	post ✦ / account	@moderation.bsky.app
Intolerance	intolerance	Hate- or protected-class harassment	post ✦ / account	@moderation.bsky.app
Threats	threats	Credible violent or doxxing threats	post ✦ / account	@moderation.bsky.app
Rude	rude	General harassment / uncivil language	post ✦	@moderation.bsky.app
Illicit	illicit	Advice or facilitation of illegal activity	post ✦	@moderation.bsky.app
Security Concerns	security	Phishing, malware, credential theft, etc.	post ✦ / account	@moderation.bsky.app
Unsafe Link	unsafe	URL known for malware or shocking content	post ✦	@moderation.bsky.app
Impersonation	impersonation	Pretending to be another real person/org	account	@moderation.bsky.app
Misinformation	misinformation	Provably false public-interest claims	post ✦	@moderation.bsky.app
Scam	scam	Advance-fee, crypto, pyramid, etc.	post ✦ / account	@moderation.bsky.app
Engagement Farming	engagement-farming	Low-quality “bait” solely for metrics	post ✦	@moderation.bsky.app
Spam	spam	Bulk unsolicited or automated posts	post ✦ / account	@moderation.bsky.app
Misleading	misleading	Deceptive commercial or manipulative content	post ✦	@moderation.bsky.app
Inauthentic Account	inauthentic	Coordinated or automated persona	account	@moderation.bsky.app
Misogynoir	misogynoir	Harassment uniquely targeting Black women	post ✦ / account	@blacksky.app did:plc:d2mkddsbmnrgr3domzg5qexf
Antiblack Harassment	antiblack-harassment	Anti-Black hate or slurs	post ✦ / account	@blacksky.app did:plc:d2mkddsbmnrgr3domzg5qexf

^{† Scope: “post ✦” means the label can be applied to individual posts; “account” means it can mark entire profiles. Many labels (e.g., Extremist, Spam) are used in both scopes, depending on the detecting service. If you see a label value that isn’t in this list, it likely originates from a third-party labeler—handle unknown values gracefully in your code.}

(This list may already be incomplete—another reason formal docs are needed!)

---

Acceptance criteria

• A merged PR that publishes the canonical label doc.
• A documented commit/release procedure for future label additions or changes.

Thanks for considering—a central, authoritative spec will make life easier for client devs, moderators, researchers, and everyday users alike and underscore Bluesky’s commitment to an open, interoperable protocol.

[bnewbold]

Labels are authoritatively defined in each moderation service's "labeler declaration record". You can read more about how this works in the "Labels and Moderation" guide: https://docs.bsky.app/docs/advanced-guides/moderation

For the Bluesky Moderation service (@moderation.bsky.app), the relevant record is at://did:plc:ar7c4by46qjdydhdevvrndac/app.bsky.labeler.service/self, which you can read as JSON at: https://astrolabe.at/at/did:plc:ar7c4by46qjdydhdevvrndac/app.bsky.labeler.service/self

For the Blacksky moderation service (@blacksky.app), the relevant record is at://did:plc:d2mkddsbmnrgr3domzg5qexf/app.bsky.labeler.service/self, which you can read as JSON at: https://astrolabe.at/at/did:plc:d2mkddsbmnrgr3domzg5qexf/app.bsky.labeler.service/self

Because that is the canonical source, I don't think we should manually re-document here in the docs website. The best way for most folks to find this information is in the Bluesky app itself, which dynamically fetches and renders these records.