nips/74.md

NIP-74: Nostr Link Lists

draft optional author:vveerrgg

This NIP defines a standardized format for sharing curated lists of links on Nostr. The NIP number 74 was chosen as it represents the ASCII character 'L' (for Links).

Abstract

Link lists are collections of URLs with associated metadata that users can share, curate, and discover. This NIP defines a standard format for link list events that enables interoperability between different Nostr clients and promotes consistent handling of link-sharing features.

Motivation

Link sharing and curation are fundamental activities in online communities. While users can share individual links in text notes or save them privately using NIP-51 bookmarks, there's a need for a standardized format specifically designed for public, curated link collections. This NIP enables:

• Public sharing of curated link collections (e.g., "link-in-bio" style lists)
• Better organization and discovery of related resources
• Consistent metadata across implementations
• Support for internationalization
• Improved user experience through specialized UI
• Interoperability between different clients

The distinction from personal bookmarks (NIP-51) is intentional - while bookmarks serve as private reading lists, NIP-74 link lists are designed for public sharing and discovery, enabling users to curate and share collections of resources with their community.

Event Format

Kind: 30011

Link list events use kind 30011. This number was chosen because:

1. The "11" in 30011 visually resembles "ll" for "link list"
2. It falls within the addressable event range (30000-39999) as defined in NIP-01
3. Maintains separation from other list-type events (30000-30009)
4. Avoids conflict with previously used kind numbers

As an addressable event (NIP-01), for each combination of kind, pubkey, and d tag value, only the latest event will be stored by relays, allowing for efficient updates to link lists.

Content

The content field MUST be empty. All data is stored in tags.

Tags

Required tags:

• ll ["list"] - Identifies this as a link list event
• d [identifier] - Identifier and title of the list
• nl [url, description, language?, direction?] - One or more link entries
  • url: The URL being shared (must follow protocol requirements)
  • description: Text description of the link (must be non-empty)
  • language: Optional ISO 639-1 language code
  • direction: Optional text direction ("ltr" or "rtl")

Optional tags:

• lang [code] - Default language for the list (ISO 639-1)
• dir [direction] - Default text direction ("ltr" or "rtl")
• t [topic] - Topics/hashtags for discovery
• summary [text] - Additional description of the list
• image [url] - Cover image for the list

URL Protocol Support

The format supports various URL protocols to accommodate different types of resources:

Standard Web Protocols:

• http://, https:// - Standard web URLs
• ftp://, sftp:// - File transfer protocols

Special Protocols:

• magnet: - BitTorrent magnet links
• ipfs:// - IPFS content
• nostr: - Nostr protocol links
• dat:// - Dat protocol
• git:// - Git repository links
• ssh:// - Secure shell links

Extended Protocols:

• mailto: - Email addresses
• tel: - Phone numbers
• sms: - Text message links
• geo: - Geographic locations

URL Validation and Security

1. Protocol Validation:

   • URLs MUST start with one of the supported protocols
   • Custom protocols MAY be supported by clients but MUST be clearly marked
   • Clients SHOULD implement appropriate security measures for each protocol

2. Protocol-Specific Metadata:

   {
     "kind": 30011,
     "tags": [
       ["ll", "list"],
       ["d", "Mixed Protocol Resources"],
       ["nl", "https://example.com", "Web Resource"],
       ["nl", "magnet:?xt=urn:btih:...", "Linux ISO Torrent", null, null, "torrent"],
       ["nl", "ipfs://Qm...", "IPFS Document", null, null, "ipfs"],
       ["nl", "nostr:npub1...", "Nostr Profile", null, null, "nostr"]
     ],
     "content": ""
   }
   

3. Client Handling:

   • Clients MUST verify protocol support before attempting to open links
   • Clients SHOULD display appropriate icons/indicators for different protocols
   • Clients MAY implement protocol-specific preview features
   • Clients SHOULD warn users when opening non-HTTP protocols

Examples

1. Basic link list with default language:

{
  "kind": 30011,
  "tags": [
    ["ll", "list"],
    ["d", "Favorite Programming Resources"],
    ["lang", "en"],
    ["dir", "ltr"],
    ["nl", "https://example.com/tutorial", "Great Python Tutorial"],
    ["t", "programming"]
  ],
  "content": ""
}

2. Multilingual list with mixed content:

{
  "kind": 30011,
  "tags": [
    ["ll", "list"],
    ["d", "Global Dev Resources"],
    ["lang", "en"],
    ["dir", "ltr"],
    ["nl", "https://example.com/docs", "Documentation"],
    ["nl", "https://arabic-example.com/tutorial", "شرح البرمجة", "ar", "rtl"],
    ["nl", "https://japanese-site.com/guide", "プログラミング入門", "ja"],
    ["t", "programming"],
    ["t", "tutorials"]
  ],
  "content": ""
}

Relationship to Other NIPs

This NIP builds upon and complements several existing NIPs:

1. NIP-01 provides the basic protocol structure we build upon
2. NIP-23 demonstrates handling of longer-form content
3. NIP-51 defines lists, including bookmarks (kind:10003) which are primarily for personal use - saving posts, articles, and URLs for later reading. While NIP-51's bookmarks serve as a private reading list, NIP-74 focuses on public, shareable collections designed for distribution and discovery:
   • Curated collections meant to be shared (like "link-in-bio" lists)
   • Rich metadata for the collection as a whole
   • Consistent theme or purpose across all links
   • Enhanced internationalization support
   • Protocol-specific handling for various link types
   • Collection-level discovery and organization

For example:

• NIP-51 Bookmark: "Save this article to read later" (personal use)
• NIP-74 Link List: "My public collection of resources about Nostr" (sharing with others)

This separation of concerns allows:

• NIP-51 to handle personal, private bookmarking for later reading
• NIP-74 to focus on public, curated collections meant for sharing
• Users to have both private reading lists and public resource collections

Finding Link Lists

To discover a user's link lists:

1. Filter for events by the user's pubkey
2. Filter for events with kind 30011
3. Filter for events with the tag ["ll", "list"]

Client Behavior

Required Behavior

Clients MUST:

• Include the ["ll", "list"] tag in all link list events
• Validate URLs to ensure they:
  • Start with http:// or https://
  • Have a non-empty description
  • Support Unicode domains (IDN/Punycode)
• Handle both profile-level and link-level language settings
• Support RTL text rendering when specified

Recommended Behavior

Clients SHOULD:

• Display link lists in a way that makes their curated nature clear
• Respect language and text direction settings
• Provide ways to discover lists by topic/hashtag
• Support Unicode normalization for non-Latin text
• Handle bidirectional text properly

Clients MAY:

• Fetch link previews (titles, descriptions, images)
• Provide specialized UI for different types of links
• Support list organization features
• Implement list sharing and discovery features

Implementation Notes

1. Language Support

   • Use ISO 639-1 two-letter codes (e.g., "en", "es", "ar", "ja")
   • Default to profile language if not specified per link
   • Support both LTR and RTL text rendering
   • Handle mixed-language content appropriately

2. URL Handling

   • Validate URLs before displaying
   • Support IDN/Punycode domains
   • Consider implementing preview safety measures

3. Backward Compatibility

   • Default to "en"/"ltr" when language/direction not specified
   • Support legacy formats during transition
   • Handle missing optional tags gracefully

Extensions

Future extensions might include:

• Link categorization within lists
• Collaborative list editing
• List versioning
• Enhanced metadata for specific link types
• Integration with other NIPs (e.g., reactions, comments)

References

• NIP-01: Basic protocol flow description
• NIP-23: Long-form Content
• NIP-51: Lists