Kind 1063: File Metadata

Overview

Kind 1063 events provide metadata for files shared in the Nostr ecosystem. This kind enables the organization, classification, and discovery of shared files, allowing relays to filter and organize content in various ways. It supports multiple types of file-sharing applications and can be used for images, videos, documents, software, and other file types. Kind 1063 is particularly useful for specialized file-sharing clients rather than general social clients.

Specification

Property	Value
Kind Number	1063
Event Range	Regular
Defined in	NIP-94

Content Format

The content field contains a description or caption for the file.

Schema

"content": "My vacation photo from the beach in Hawaii"

Tags

Tag Name	Description	Format	Required
url	Download URL	["url", "<file-uri>"]	Yes
m	MIME type	["m", "<mime-type>"]	Yes
x	SHA-256 hash	["x", "<sha256-hex>"]	Yes
ox	Original file's SHA-256 hash	["ox", "<sha256-hex>"]	No
size	File size in bytes	["size", "<bytes>"]	No
dim	Dimensions in pixels	["dim", "<width>x<height>"]	No
magnet	Magnet URI	["magnet", "<magnet-uri>"]	No
i	Torrent infohash	["i", "<infohash>"]	No
blurhash	Blurhash for loading	["blurhash", "<blurhash-value>"]	No
thumb	Thumbnail URL	["thumb", "<thumbnail-uri>", "<sha256-hex>"]	No
image	Preview image URL	["image", "<preview-uri>", "<sha256-hex>"]	No
summary	Text excerpt	["summary", "<excerpt>"]	No
alt	Accessibility description	["alt", "<description>"]	No
fallback	Fallback file sources	["fallback", "<fallback-uri>"]	No
service	Service type	["service", "<service-type>"]	No

Client Behavior

Clients should:

1. Display file metadata in a user-friendly manner
2. Show thumbnails or previews when available
3. Provide download or streaming options for the file
4. Validate file integrity using the provided SHA-256 hash when downloading
5. Display appropriate fallback content if the primary URL is unavailable
6. Support filtering and organizing files based on MIME types and other metadata
7. Consider using blurhash for images while loading

Relay Behavior

Relays should:

1. Store and serve file metadata events
2. Optionally support filtering by MIME type, size, or other metadata attributes
3. Not be expected to store the actual file content (which is hosted externally)

Use Cases

• Creating Pinterest-like platforms for sharing visual content
• Distributing software updates and configurations
• Building decentralized file indexes
• Creating media galleries and portfolios
• Sharing documents and publications
• Indexing and organizing torrent files
• Building specialized file-sharing applications

Example

Image file example:

{
  "id": "4376c65d2f232afbe9b882a35baa4f6fe8667c4e684749af565f981833ed6a65",
  "pubkey": "79dff8f82963424e0bb02708a22e44b4980893e3a4be0fa3cb60a43b946764e3",
  "created_at": 1671217411,
  "kind": 1063,
  "tags": [
    ["url", "https://example.com/files/beach_sunset.jpg"],
    ["m", "image/jpeg"],
    ["x", "3a9a34a15b6cd1cb56741f47ea7c0e64c57fc8abb5a9b99e9f16c9c55115c56b"],
    ["ox", "3a9a34a15b6cd1cb56741f47ea7c0e64c57fc8abb5a9b99e9f16c9c55115c56b"],
    ["size", "1245678"],
    ["dim", "3840x2160"],
    ["blurhash", "LFC$yHwc8^$ysaR*J7V@_3NH%Mxu"],
    ["thumb", "https://example.com/thumbnails/beach_sunset_thumb.jpg", "57f23d0af2781ca94be5cb945fe22c3cca36b28bc06abb99e9f16c9c55115c56b"],
    ["alt", "Beautiful sunset over the ocean with orange and purple sky"],
    ["service", "nip96"]
  ],
  "content": "Breathtaking sunset from my vacation in Hawaii last week. The colors were absolutely incredible!",
  "sig": "908a15e46fb4d8675bab026fc230a0e3542bfade63da02d542fb78b2a8513fcd0092619a2c8c1221e581946e0191f2af505dfdf8657a414dbca329186f009262"
}

Video file example:

{
  "id": "fe8b1c9a37218cf5ce604a8dce596c9c3ae0c650df2336f3c60c78e61a7b2031",
  "pubkey": "f7234bd4c1394dda46d09f35bd384dd30cc552ad5541990f98844fb06676e9ca",
  "created_at": 1671217500,
  "kind": 1063,
  "tags": [
    ["url", "https://example.com/files/demo_video.mp4"],
    ["m", "video/mp4"],
    ["x", "7c93fbb58c9c6e4590cefe9a87b0124f03d9ab61a5db7e36b376be1f5c56e19d"],
    ["size", "24568791"],
    ["dim", "1920x1080"],
    ["thumb", "https://example.com/thumbnails/demo_video_thumb.jpg", "98a7b3c62dfc98a3d5e7ca9b18762b04b3e68d73a49d3f23e9e7d3a5ba98f4f7"],
    ["summary", "A short demonstration of the new product features"],
    ["alt", "Product demonstration showing new UI features and interactions"]
  ],
  "content": "Demo video of our latest product update. Check out the new interface and improved performance!",
  "sig": "a76f39224cebd44cf04eeebe01d5ab2e8f7a3e5e56c83cadd252e7bc5e2e34fd7ad7148cf7a2c7620d9490ccf2e1bac521995725f2e1f543159b8eb98bfdd405"
}

References

• NIP-94: File Metadata
• NIP-96: HTTP File Storage Integration (for context on file hosting)
• Blurhash (for image placeholder generation)

Related Kinds

• Kind 1: Short Text Note - For discussions about shared files
• Kind 1111: Comment - For structured comments on files
• Kind 2003: Torrent - Another approach to file sharing

Notes

• File metadata events don't contain the actual file content, only metadata and references
• Files are hosted externally at the specified URL
• The SHA-256 hash enables verification of file integrity
• The original hash (ox) is useful when the file is transformed by the hosting service
• Multiple distribution methods can be provided (direct URL, magnet link, torrent)
• Blurhash provides a compact placeholder representation for images
• This kind is intended for specialized file-sharing applications rather than general social clients