NIP-94: File Metadata
Files need identity beyond a hosted URL
A file URL can disappear, mutate or hide important details. NIP-94 gives files a metadata event: kind 1063, with a description in content and tags for URL, MIME type, SHA-256 hash, original hash, size, dimensions, magnet link, torrent infohash, blurhash, thumbnails, summary, alt text and fallbacks.
The official text is careful. NIP-94 is not expected to be implemented by ordinary social clients that only handle short notes or long-form articles. It is for file-sharing, indexing, media libraries, portfolio clients, configuration distribution and similar use cases.
That boundary matters. NIP-94 describes files; it does not turn relays into blob stores.
Kind 1063 as a signed file descriptor
A NIP-94 event signs metadata around a file. The url tag points to the download location. The x tag identifies the file by SHA-256. The ox tag can preserve the original hash before transformations. Optional fields help clients display, verify or find alternate copies.
The service tag can indicate where the file is served, such as NIP-96. The fallback field lets a client try another source when the main URL fails.
NIP-92 reuses NIP-94 fields inline through imeta, which is why this page belongs at the center of Nostr media documentation.
File metadata evolved alongside media and storage debates
The file history reaches back through arthurfranca's NIP-96 work, Vitor Pamplona's encryption-tag cleanup, Jon Staab's imeta work and Kieran's video metadata work. That mixed history is exactly what you would expect from a standard that became a shared field vocabulary.
In May 2024, NIP-71 imeta work touched the file. Later edits mostly cleaned formatting and tags. The important product lesson is stable: file metadata is infrastructure for media clients, not the media hosting layer itself.
That distinction helps people understand why NIP-94 appears next to NIP-92, NIP-96 and NIP-B7.
Hash first, preview second
A file client needs to verify the x hash when it can, show MIME type and size before download, use thumbnails and blurhashes for safe previews, and preserve alt text for accessibility. If several fallback sources exist, the client can recover from dead hosts without losing the file identity.
For torrents and large files, magnet and i tags matter. For images and video, dimensions and preview images keep layouts stable.
NIP-94 works best as a sober file record. It must not hide the fact that actual storage, moderation and bandwidth happen elsewhere.
A signed descriptor can still point at hostile content
Hashes help identity, not judgment. A file can be malware, illegal content or simply misdescribed. Clients need safe preview behavior and moderation surfaces.
If upload servers transform files, the difference between x and ox needs to be handled clearly so users know what was actually downloaded.
Read NIP-94 in the wild
NIP-94 describes file metadata events. A file can be referenced as a signed object with hash, URL, MIME type and size rather than as a disposable link.
That matters for archives, media libraries and evidence. If the host changes but the hash and metadata remain, you can still reason about the object.
What changes when you actually use it
For you, NIP-94: File Metadata is felt when a post becomes a durable object: article, file, image, video, audio, bookmark, wiki entry or source reference. The question is whether the work still makes sense after one app, host or relay disappears. The concrete pieces kind 1, kind 30023, draft, kind:1, kind:30023, content decide whether the object carries enough context to survive.
What changes for builders and operators
For builders, NIP-94: File Metadata is context preservation. Store enough title, tag, author, hash, URL, media, preview and reference material that another interface can rebuild the object. If your feature depends on a private database to make sense, the NIP is not doing the portability work yet.
What the official file makes concrete
The official file is organized around Event format, Suggested use cases. Inspect kind 1, kind 30023, draft, kind:1, kind:30023, content, size, <width>x<height> because these are the pieces most likely to surface as product behavior. Read it beside NIP-96 before treating it as isolated.
NIP-94: File Metadata protects context. Titles, media, hashes, source links, timestamps and references decide whether work survives beyond one app.
Where it breaks
The failure mode in NIP-94: File Metadata is link rot with a nice interface. Media disappears, metadata lies, source URLs change, hashes are missing or an article loses its addressable identity. The page needs to make durability part of the feature, not an afterthought.
Where this appears outside the markdown
In the ecosystem, NIP-94: File Metadata is part of the creator and archive layer. It decides whether writing, media, files, bookmarks, wiki material or source references remain understandable after the first app disappears. That is why media standards need to talk about storage, provenance and recovery, not only presentation.
The nearby-standard trap
The nearby-standard trap in NIP-94: File Metadata is flattening every creative object into a note with a link. Articles, videos, files, torrents, highlights, images, wiki entries and bookmarks carry different metadata and storage pressure. Read NIP-96 so the product does not throw away the part that made the object portable.
Language that keeps the feature honest
Good product copy for NIP-94: File Metadata names the object and the storage. It says article, file, image, video, bookmark, wiki page, torrent, highlight or podcast episode, then tells you where the signed metadata ends and where external hosting begins.
What this page does not promise
NIP-94: File Metadata does not guarantee that published work survives forever. It can carry richer metadata, hashes, references or addressability, but files still need hosts, relays still need retention, and clients still need to render the object faithfully. Treat the NIP as the signed map of the work, then check where the actual bytes, previews and source links live.
Read it as a field test
Start NIP-94: File Metadata with the object you want to keep: article, file, media, bookmark, repository, torrent, wiki entry or podcast episode. Then trace which parts are signed, which parts are hosted, and which parts another client can reconstruct from kind 1, kind 30023, draft, kind:1, kind:30023, content. That is the difference between portable publishing and a pretty link preview.
Where the standard earns trust
The source links give you places to test the interpretation in public: NIP-94 Publisher Action, NIP-92 Media Attachments, NIP-96 HTTP File Storage. Use those links to move from the spec to live libraries, mirrors, pull requests, guides or products.
Official NIP-94 source is the anchor for exact wording, and NIP-94 commit history shows how that wording moved over time. The strongest secondary clues here are NIP-94 Publisher Action, NIP-92 Media Attachments, NIP-96 HTTP File Storage. Treat this evidence chain as part of the article, not as footnotes. A NIP page becomes useful when you can move from claim to source to working behavior without guessing.
Keep the chain visible for NIP-94: File Metadata: first the human promise, then kind 1, kind 30023, draft, kind:1, kind:30023, content, then the implementation record, then the real-world failure case. That order keeps NIP-94 useful without turning it into marketing copy or protocol trivia.
Three questions to carry forward
- Where do the signed metadata and the actual media or file bytes part ways?
- Can the object still be identified by hash, address, title, author and source if the first URL breaks?
- Does a second client know enough from
kind 1,kind 30023,draft,kind:1to render the work without private context?
What to verify before you rely on it
- Find
kind 1,kind 30023,draft,kind:1,kind:30023in the official file and check where the UI exposes the same concept. - Read NIP-96 as context before treating NIP-94 as a complete product story.
- Open at least one implementation, mirror, pull request or library source from the source links before trusting that the idea is mature.
- Test the unhappy path: missing relays, stale metadata, invalid signatures, blocked events, expired state, revoked permissions or unavailable media.
- Write the user-facing copy in plain language. If a standard changes authority, privacy, money, moderation or recovery, say that before the click.
Direct sources
Use these sources for NIP-94: File Metadata in that order: Official NIP-94 source for the current wording; NIP-94 commit history for the change record; NIP-94 Publisher Action, NIP-92 Media Attachments, NIP-96 HTTP File Storage for public context. The article gives you the consequence in plain language, but the source trail is where exact fields, status notes, unresolved debates and implementation proof stay checkable.
