NKBIP-04: Directories

This spec describes a Nostr directory system, modeled after kind 30040 publication indexes and inspired by UNIX directories.

UNIX directory system

On UNIX, a directory is a list of names that point at files. Some of those files are themselves directories, so the lists nest into a tree. Opening a directory "folder" means reading that list; a nested directory is just another name in that list.

Kind 30045 is that list on Nostr. It uses the same structure as a 30040 from [[NKBIP-01]]: empty content, a d tag, a title tag, and child a / e tags. Nested directories are 30045s listed in those tags.

Directory Event#

Kind 30045 MUST:

• have empty content
• contain a d tag unique for kind + pubkey, normalized to a [[NIP-54]] style slug. This is the directory ID.
• contain a title tag, the display name shown on the directory
• events MUST NOT refer to themselves with a-tags or e-tags

MAY have zero or more child tags, using the standard [[NIP-01]] tag format, followed by an optional, human-readable label.

• Use a tags for addressable children and subdirectories.
• Use a tags without d-tags for replaceable events, such as profile kind 0.
• Use e tags for events that are not replaceable (e.g. external files or short text notes).
• Any kind MAY be a child. A kind 30045 child is a subdirectory.
• Tag order is the default display order, but your client may choose to display them in a different order or allow sorting by the label or created_at timestamp.

{
  "kind": 30045,
  "pubkey": "f7234bd4c1394dda46d09f35bd384dd30cc552ad5541990f98844fb06676e9ca",
  "content": "",
  "tags": [
    ["d", "planning-2026"],
    ["title", "Alice's Spring 2026 Planning"],
    ["a", "30045:f7234bd4c1394dda46d09f35bd384dd30cc552ad5541990f98844fb06676e9ca:planning-january", "wss://relay.example.com", "January"],
    ["a", "30045:f7234bd4c1394dda46d09f35bd384dd30cc552ad5541990f98844fb06676e9ca:planning-february", "wss://relay.example.com", "February"],
    ["a", "30045:f7234bd4c1394dda46d09f35bd384dd30cc552ad5541990f98844fb06676e9ca:planning-march", "wss://relay.example.com", "March"],
    ["a", "30045:f7234bd4c1394dda46d09f35bd384dd30cc552ad5541990f98844fb06676e9ca:planning-april", "wss://relay.example.com", "April"],
    ["e", "5c83da77af1dec6d7289834998ad7aafbd9e2191396d75ec3cc27f5a77226f36", "wss://relay.example.com", "f7234bd4c1394dda46d09f35bd384dd30cc552ad5541990f98844fb06676e9ca", "Spring Overview"],
    ["a", "0:f7234bd4c1394dda46d09f35bd384dd30cc552ad5541990f98844fb06676e9ca:", "wss://relay.example.com", "My vacation profile"]
  ]
}

Client Recommendations#

• Walk nested directories with a cycle/depth guard.
• Refer to external files with kind 1063 file metadata events.
• Link to websites with kind 39701 web bookmarks.
• Render directories in GUIs as a tree of directory and file icons, but differentiate between Nostr-native events and external files that are merely referenced in an event.