Nostr Kinds — Design and Schema
Load this skill when:
- Minting a new event kind for a Ditto feature.
- Extending an existing NIP with new tags.
- Deciding whether an existing NIP covers a use case or whether a custom kind is warranted.
- Documenting a custom kind or extension in
NIP.md.
Not this skill — if an existing NIP/kind covers your use case and you only need to render it in Ditto's UI, use the nostr-kind-rendering skill instead.
Choosing Between Existing NIPs and Custom Kinds
- Thorough NIP review first. Browse the NIP index, then read candidate NIPs in detail. The goal is to find the closest existing solution.
- Prefer extending existing NIPs over creating custom kinds, even at the cost of minor schema compromises. Custom kinds fragment the ecosystem.
- When an existing NIP is close but not perfect, use its kind as the base and add domain-specific tags. Document the extension in
NIP.md.
- Only mint a new kind when no existing NIP covers the core functionality, the data structure is fundamentally different, or the use case requires different storage characteristics (regular vs. replaceable vs. addressable).
- If a tool to generate a new kind number is available, you MUST call it. Never pick an arbitrary number.
- Custom kinds MUST include a NIP-31
alt tag with a human-readable description of the event's purpose.
Example decision:
Need: Equipment marketplace for farmers
Options:
1. NIP-15 (Marketplace) — too structured for peer-to-peer sales
2. NIP-99 (Classifieds) — good fit, extensible with farming tags
3. Custom kind — perfect fit, no interoperability
Decision: NIP-99 + farming-specific tags.
Kind Ranges
An event's kind number determines storage semantics:
- Regular (1000 ≤ kind < 10000) — stored permanently by relays. Notes, articles, etc.
- Replaceable (10000 ≤ kind < 20000) — only the latest event per
pubkey+kind is kept. Profile metadata, contact lists, mute lists.
- Addressable (30000 ≤ kind < 40000) — identified by
pubkey+kind+d-tag; only the latest per combo is kept. Long-form content, products, definitions.
Kinds below 1000 are "legacy"; storage is per-kind (e.g. kind 1 is regular, kind 3 is replaceable).
Tag Design Principles
Kind = schema, tags = semantics. Don't mint a new kind just to represent a different category of the same data.
Relays only index single-letter tags. Use t for categories so filters like '#t': ['electronics'] work at the relay level. Multi-letter tags (product_type, etc.) force inefficient client-side filtering.
Filter at the relay, not in JavaScript:
// ❌ Fetch everything, filter locally
const events = await nostr.query([{ kinds: [30402] }]);
const filtered = events.filter((e) => hasTag(e, 'product_type', 'electronics'));
// ✅ Filter at the relay
const events = await nostr.query([{ kinds: [30402], '#t': ['electronics'] }]);
For Ditto-specific niches (community apps, regional variants), tag events with a t value and query on it. Don't do this for generic platforms — it would silo content.
Content vs. Tags
content — large freeform text or existing industry-standard JSON (GeoJSON, FHIR, Tiled maps). Kind 0 is the one exception where structured JSON goes in content.- Tags — queryable metadata, structured data, anything you might filter on.
- Empty content is fine.
content: "" is idiomatic for tag-only events.
- If you need to filter by a field, it must be a tag — relays don't index content.
// ✅ Queryable
{ "kind": 30402, "content": "",
"tags": [["d", "product-123"], ["title", "Camera"], ["price", "250"], ["t", "photography"]] }
// ❌ Structured data buried in content
{ "kind": 30402, "content": "{\"title\":\"Camera\",\"price\":250}", "tags": [["d", "product-123"]] }
NIP.md
NIP.md documents Ditto's custom kinds and any extensions to existing NIPs. Whenever you mint a new kind or change a custom schema, create or update NIP.md with the tag list, content format, and intended usage. If a kind you add is effectively the same shape as an existing NIP, note the NIP reference rather than duplicating the spec.
Standard NIPs (like NIP-84 Highlights, NIP-23 Articles) do not go in NIP.md — only Ditto-custom kinds and Ditto-specific extensions.
After Designing — What's Next?
Once you've settled on a kind number and tag shape, you still need to render it in Ditto's UI. Load the nostr-kind-rendering skill for the full multi-location registration checklist (feed cards, detail pages, embedded previews, kind-label maps, notifications, feed-toggle registration).
1---2name: nostr-kind-design3description: Decide whether to reuse an existing NIP or mint a new kind, design tag structures that relays can index, choose what goes in content vs. tags, and document new kinds or extensions in NIP.md. Load when authoring a new schema — not when wiring up rendering for a kind that already exists (use nostr-kind-rendering for that).4---56# Nostr Kinds — Design and Schema78Load this skill when:910- Minting a new event kind for a Ditto feature.11- Extending an existing NIP with new tags.12- Deciding whether an existing NIP covers a use case or whether a custom kind is warranted.13- Documenting a custom kind or extension in `NIP.md`.1415**Not this skill** — if an existing NIP/kind covers your use case and you only need to render it in Ditto's UI, use the **`nostr-kind-rendering`** skill instead.1617## Choosing Between Existing NIPs and Custom Kinds18191. **Thorough NIP review first.** Browse the NIP index, then read candidate NIPs in detail. The goal is to find the closest existing solution.202. **Prefer extending existing NIPs** over creating custom kinds, even at the cost of minor schema compromises. Custom kinds fragment the ecosystem.213. **When an existing NIP is close but not perfect**, use its kind as the base and add domain-specific tags. Document the extension in `NIP.md`.224. **Only mint a new kind** when no existing NIP covers the core functionality, the data structure is fundamentally different, or the use case requires different storage characteristics (regular vs. replaceable vs. addressable).235. **If a tool to generate a new kind number is available, you MUST call it.** Never pick an arbitrary number.246. **Custom kinds MUST include a NIP-31 `alt` tag** with a human-readable description of the event's purpose.2526**Example decision:**2728```29Need: Equipment marketplace for farmers30Options:31 1. NIP-15 (Marketplace) — too structured for peer-to-peer sales32 2. NIP-99 (Classifieds) — good fit, extensible with farming tags33 3. Custom kind — perfect fit, no interoperability3435Decision: NIP-99 + farming-specific tags.36```3738## Kind Ranges3940An event's kind number determines storage semantics:4142- **Regular** (1000 ≤ kind < 10000) — stored permanently by relays. Notes, articles, etc.43- **Replaceable** (10000 ≤ kind < 20000) — only the latest event per `pubkey+kind` is kept. Profile metadata, contact lists, mute lists.44- **Addressable** (30000 ≤ kind < 40000) — identified by `pubkey+kind+d-tag`; only the latest per combo is kept. Long-form content, products, definitions.4546Kinds below 1000 are "legacy"; storage is per-kind (e.g. kind 1 is regular, kind 3 is replaceable).4748## Tag Design Principles4950- **Kind = schema, tags = semantics.** Don't mint a new kind just to represent a different category of the same data.51- **Relays only index single-letter tags.** Use `t` for categories so filters like `'#t': ['electronics']` work at the relay level. Multi-letter tags (`product_type`, etc.) force inefficient client-side filtering.52- **Filter at the relay**, not in JavaScript:5354 ```ts55 // ❌ Fetch everything, filter locally56 const events = await nostr.query([{ kinds: [30402] }]);57 const filtered = events.filter((e) => hasTag(e, 'product_type', 'electronics'));5859 // ✅ Filter at the relay60 const events = await nostr.query([{ kinds: [30402], '#t': ['electronics'] }]);61 ```6263- **For Ditto-specific niches** (community apps, regional variants), tag events with a `t` value and query on it. Don't do this for generic platforms — it would silo content.6465## Content vs. Tags6667- **`content`** — large freeform text or existing industry-standard JSON (GeoJSON, FHIR, Tiled maps). Kind 0 is the one exception where structured JSON goes in content.68- **Tags** — queryable metadata, structured data, anything you might filter on.69- **Empty content is fine.** `content: ""` is idiomatic for tag-only events.70- **If you need to filter by a field, it must be a tag** — relays don't index content.7172```json73// ✅ Queryable74{ "kind": 30402, "content": "",75 "tags": [["d", "product-123"], ["title", "Camera"], ["price", "250"], ["t", "photography"]] }7677// ❌ Structured data buried in content78{ "kind": 30402, "content": "{\"title\":\"Camera\",\"price\":250}", "tags": [["d", "product-123"]] }79```8081## `NIP.md`8283`NIP.md` documents Ditto's custom kinds and any extensions to existing NIPs. Whenever you mint a new kind or change a custom schema, **create or update `NIP.md`** with the tag list, content format, and intended usage. If a kind you add is effectively the same shape as an existing NIP, note the NIP reference rather than duplicating the spec.8485Standard NIPs (like NIP-84 Highlights, NIP-23 Articles) do **not** go in `NIP.md` — only Ditto-custom kinds and Ditto-specific extensions.8687## After Designing — What's Next?8889Once you've settled on a kind number and tag shape, you still need to render it in Ditto's UI. Load the **`nostr-kind-rendering`** skill for the full multi-location registration checklist (feed cards, detail pages, embedded previews, kind-label maps, notifications, feed-toggle registration).
soapbox-pub