An open convention for structured alert and information bots on Bluesky, enabling client-side filtering and personalization.
Disaster information, weather alerts, and breaking news bots face a fundamental tension on social media: post too much, and you flood timelines; post too little, and you miss critical information for someone, somewhere.
A weather bot that posts every advisory for an entire country quickly becomes noise. But for the person in the path of a tornado, that single post is the most important thing in their feed.
Current solutions force a choice:
- One global bot → Timeline overload, most posts irrelevant to any given user
- Regional bots → Fragmented ecosystem, users must find and follow the right accounts
- Platform-specific features → Lock-in, not portable across clients
BSAF (Bluesky Structured Alert Feed) is an open convention that separates concerns:
| Layer | Responsibility | Who builds it |
|---|---|---|
| Bots | Collect and post alerts with structured metadata | Bot developers (per country/source) |
| Convention | Shared tag format for machine-readable filtering | This specification |
| Clients | Filter and display posts based on user preferences | Client developers |
Bots post broadly. Clients filter locally. Users see only what matters to them.
┌─────────────────────────────┐
│ Bluesky Network │
│ │
┌──────────┐ │ Posts with BSAF tags │ ┌──────────────┐
│ 🇯🇵 JMA Bot │────▶│ │◀────│ Any Bluesky │
│ 🇺🇸 NWS Bot │────▶│ Searchable, filterable │◀────│ Client │
│ 🇪🇺 EU Bot │────▶│ machine-readable │◀────│ (kazahana, │
│ 🌍 Anyone │────▶│ metadata │◀────│ etc.) │
└──────────┘ └─────────────────────────────┘ └──────────────┘
│
▼
┌──────────────┐
│ User sees: │
│ Only relevant│
│ alerts for │
│ their target │
│ & preferences│
└──────────────┘
BSAF is a universal bot parsing system, not limited to disaster alerts. The convention is designed to be fully domain-agnostic: disaster bots, sports score bots, news bots, traffic alert bots — anything that benefits from structured, filterable metadata can adopt BSAF.
The core tags use intentionally generic names (type, value, target) rather than domain-specific terms, ensuring the protocol works across all content domains without modification.
{
"$type": "app.bsky.feed.post",
"text": "🔴 Earthquake Info\nFeb 15, 11:52 — Ibaraki, Japan\nMagnitude: 5.2 (Depth: ~50km)\nMax intensity: Upper 5\nTsunami: None expected\n(Source: JMA)",
"tags": [
"bsaf:v1",
"type:earthquake",
"value:5+",
"time:2026-02-15T02:52:00Z",
"target:jp-kanto",
"source:jma"
],
"langs": ["en"],
"createdAt": "2026-02-15T02:55:54Z"
}The post text remains human-readable. The tags enable machine filtering.
| Slot | Tag | Description | Required |
|---|---|---|---|
| 1 | bsaf:v1 |
Protocol identifier | ✅ |
| 2 | type:{category} |
Information category | ✅ |
| 3 | value:{scale} |
Scale / magnitude / weight | ✅ |
| 4 | time:{ISO8601} |
Source event timestamp (UTC) | ✅ |
| 5 | target:{target} |
Target subject / audience | ✅ |
| 6 | source:{authority} |
Originating authority / data source | ✅ |
| 7 | (reserved) | Optional | |
| 8 | (reserved) | Optional |
6 required tags + 2 reserved slots for future extensions.
📄 BSAF Specification v1 (English) — Complete protocol specification
📄 BSAF仕様書 v1 (日本語) — 完全なプロトコル仕様書
Every BSAF bot publishes a Bot Definition JSON file that describes available filter options. Users import this JSON into a BSAF-compatible client to register the bot and auto-generate filter settings UI.
→ See full specification for schema details.
When multiple bots cover the same data source, clients detect duplicates by comparing type + value + time + target across posts from different bot accounts, and collapse them with an indicator.
→ See full specification for details.
When developing a new BSAF bot covering the same data source as an existing bot, the new bot MUST use identical value and target values from the existing bot's Bot Definition JSON.
→ See full specification for details.
A BSAF bot has four jobs:
- Collect — Monitor an official data source (e.g., JMA XML feeds, NWS CAP alerts)
- Format — Create a human-readable post text with source attribution + BSAF tags
- Post — Publish to Bluesky via AT Protocol API
- Publish — Maintain a Bot Definition JSON file for client registration
→ See full specification for implementation guide, code examples, and available data sources.
Any Bluesky client can support BSAF:
- Bot Registration — User imports Bot Definition JSON → auto-follow + generate filter UI
- Filter Settings — Dynamic multi-select UI generated from the JSON's
filtersarray - Filtering Logic — Check each post's
tagsagainst user's enabled options - Duplicate Collapsing — Detect and collapse duplicate posts from multiple bots
→ See full specification for implementation guide and pseudocode.
| Country | Source | Format | Access | Notes |
|---|---|---|---|---|
| 🇯🇵 Japan | JMA XML Feed | Atom/XML | Free, no registration | Updated every minute |
| 🇺🇸 USA | NWS CAP Alerts | CAP/Atom | Free, no registration | Real-time |
| 🇪🇺 EU | MeteoAlarm | CAP/RSS | Free | 30+ European countries |
| 🇦🇺 Australia | BOM Warnings | RSS/XML | Free | |
| 🇹🇼 Taiwan | CWA Open Data | JSON/XML | Free, registration required | |
| 🇰🇷 Korea | KMA Data Portal | JSON/XML | Free, registration required | |
| 🇨🇦 Canada | ECCC Alerts | CAP/Atom | Free | |
| 🇳🇿 New Zealand | MetService Warnings | RSS | Free | |
| 🌍 Global | GDACS | RSS/CAP | Free | Major disasters only |
- Publish BSAF specification v1
- Launch reference bot: Japan disaster alerts (10 types including earthquake, tsunami, eruption, weather warnings, and more)
- Implement BSAF filtering in kazahana as reference client (11 languages)
- Publish Bot Definition JSON for reference bot
- Community-contributed bots for US (NWS), EU (MeteoAlarm), and others
- Bot Definition JSON directory / registry
- BSAF tag validation tool for bot developers
- Adoption by additional Bluesky clients
- BSAF v2 specification (based on community feedback)
- Support for media attachments (alert maps, radar images)
- Rich embed cards with structured alert data
- Integration with AT Protocol's labeling system
Feed generators run server-side and require hosting infrastructure for each personalized feed. BSAF filtering runs entirely client-side with zero server cost per user. Bot developers only need to host the bot itself.
Hashtags clutter the post text and are prone to typos and inconsistencies. The tags field is invisible to users but machine-readable, keeping posts clean while enabling precise filtering.
Absolutely. BSAF is a universal bot parsing system designed to be fully domain-agnostic. News bots, sports score bots, traffic alert bots — anything that benefits from structured, filterable metadata can adopt BSAF. Simply define appropriate type: and value: options for your domain in your Bot Definition JSON.
Clients detect duplicates by comparing type + value + time + target across posts from different bot accounts. The time tag uses the original source event timestamp (not the bot's posting time), ensuring identical events produce identical time values regardless of which bot processes them.
CAP is a comprehensive XML standard for emergency alerts used by national agencies. BSAF is a lightweight convention for social media posts on Bluesky. A typical BSAF bot consumes CAP data from national sources and produces Bluesky posts with BSAF tags. They're complementary, not competing.
We welcome contributions of all kinds:
- 🤖 Build a bot for your country's disaster alerts or any information domain
- 📋 Publish a Bot Definition JSON for your bot
- 🐛 Report issues with the specification
- 📝 Improve documentation and translations
- 💡 Propose features for BSAF v2
See CONTRIBUTING.md for guidelines.
- Bot: bsaf-jma-bot — Japan disaster alerts (earthquake, tsunami, eruption, weather warnings, and more) — live on Bluesky as @jma-alert-bot.bsky.social
- Bot: bsaf-kikikuru-bot — JMA new R06 weather warnings & advisories (heavy rain, landslide, storm-surge, wind, wave, snow, and other phenomena; VPWW55–61) — live on Bluesky as @bsaf-kikikuru-bot.bsky.social
- Client: kazahana — Bluesky desktop client with BSAF filtering support (11 languages)
This specification is released under CC BY 4.0. You are free to adopt, modify, and redistribute it with attribution.
Reference implementations are licensed under MIT License.
If you find BSAF useful, consider supporting its development:
BSAF is an open community effort. Built for safety. Designed for everyone.