== Directory System Specification [[NKBIP-04]], a NEP based upon [[NKBIP-01]] This NIP defines the basic structure for building a directory system out of Nostr events, so that events can be organized as _files_ and _folders_. The basic structure consists of a drive event `kind:30042`, where the top-level directory shall be mounted, and any directory `kind:30045` events (similar to the index `kind:30040`, but with a different purpose) contained therein, that are the root folder-events in the drive. This creates a forward-tracing directory structure, which is the minimal implementation. Kind 30041 is the default file kind and is defined in NKBIP-01, but any kind can be contained in a directory. Directories MAY be nested. All of these events are addressable and replaceable, and MUST contain an `d` tag. A backward-tracing structure, with full directory functionality and optimal performance, can be created by adding: * tracebacks: `kind:30043` event, which is related to a `kind:30045`, and contains the parent-directory link * symlinks: `kind:30044` event, which is a symbolic link to a particular file or directory. Hard symbolic links are to `e` tagged events, and soft symbolic links are to `a` tagged events. The difference being that addressable events (those with `d` tags and 3xxxxx kind numbers) can be replaced, without breaking the link. image::https://i.nostr.build/cJLZaqtqKiUlRcs4.png[diagram of Nostr filestystem events] *Event Structure* Drive event: * The `a` tags MUST be an ordered list of root `30045` index events. * The `content` field MUST be empty. [source, json] ---- { "kind": 30042, "pubkey": "<drive-owner-pubkey>", "tags": [ ["d", "<drive-identifier>"], ["description", "<human readable description of the content of the drive>"], ["a", "<30045:pubkey:dtag>", "<relay hint>"], ["a", "<30045:pubkey:dtag>", "<relay hint>"], ["a", "<30045:pubkey:dtag>", "<relay hint>"], ["a", "<30045:pubkey:dtag>", "<relay hint>"], ], "content": "" } ---- Directory event: * Contains `a` and/or `e` tags of the files and subdirectories contained therein * The `content` field MUST be empty. * The order is the default for the initial display, but MUST NOT be essential to any functionality, so that sorting the directory content doesn't break any use case. [source, json] ---- { "id": "<event_id>", "pubkey": "<event_originator_pubkey>", "created_at": 1725087283, "kind": 30045, "tags": [ ["d", "<directory-identifier>"], ["a", "<kind:pubkey:dtag>", "<relay hint>", "<event id>"], ["a", "<kind:pubkey:dtag>", "<relay hint>", "<event id>"], ["e", "<original_event_id>", "<relay_url>", "<pubkey>"], ["a", "<30045:pubkey:dtag>", "<relay hint>", "<event id>"], ], "sig": "<event_signature>" } ---- Traceback event: * The `a` tag MUST be a `30045` index event, to which the traceback is linked. * The `A` tag MUST be a `30045` index event, which is the parent event of the linked index. * The `content` field MUST be empty. [source, json] ---- { "kind": 30043, "pubkey": "<drive-owner-pubkey>", "tags": [ ["d", "<traceback-identifier>"], ["a", "<30045:pubkey:dtag>", "<relay hint>", "link"], ["A", "<30045:pubkey:dtag>", "<relay hint>", "parent"], ], "content": "" } ---- Symlink event: * The first `a` or `e` tag MUST be the event, that is the target of the symlink. * The `A` tag MUST be the 30045, that contains the event context, and MAY be the same event as the first. * The second `A` tag MUST be the `30042` drive event, that the symlink should begin at. * The `content` field MUST be empty. [source, json] ---- { "kind": 30044, "pubkey": "<drive-owner-pubkey>", "tags": [ ["d", "<symlink-identifier>"], ["a", "<30041:pubkey:dtag>", "<relay hint>", "target"], ["A", "<30045:pubkey:dtag>", "<relay hint>", "context"], ["A", "<30042:pubkey:dtag>", "<relay hint>", "drive"], ], "content": "" } ----