Tag: r

Overview

The r tag serves two distinct purposes in the Nostr ecosystem:

1. In general use, it represents a reference to a web URL that an event is referring to in some way.
2. In kind:10002 (Relay List Metadata) events, it represents a relay URL with optional read/write markers.

Specification

Property	Value
Tag Name	r
Defined in	[NIP-24], [NIP-65]
Required for	Kind 17 (reactions to websites), Kind 10002 (relay list metadata)

Format

General URL reference format:

["r", "<web_url>"]

Relay list metadata format:

["r", "<relay_url>", "<optional_marker>"]

Usage Description

General URL reference (NIP-24)

When using the r tag in general contexts, the value should be a web URL that the event is referring to in some way. This allows events to reference external resources.

Website reactions (NIP-25)

When used in kind:17 events (reactions to a website), the r tag MUST include the website's URL. URLs SHOULD be normalized according to RFC 3986 so that reactions to the same website are not omitted from queries. A fragment MAY be attached to the URL to react to a specific section of the page.

Relay list metadata (NIP-65)

In replaceable events using kind:10002, the r tag is used to advertise relays where the user generally writes to and relays where the user generally reads mentions. The tag includes a relay URL as the value and an optional "read" or "write" marker. If the marker is omitted, the relay is considered both for read and write operations.

Examples

URL Reference Example

["r", "https://example.com/article"]

Website Reaction Example

{
  "kind": 17,
  "content": "⭐",
  "tags": [
    ["r", "https://example.com/"]
  ],
  // other fields...
}

Relay List Metadata Examples

["r", "wss://alicerelay.example.com"]
["r", "wss://expensive-relay.example2.com", "write"]
["r", "wss://nostr-relay.example.com", "read"]

Complete event example:

{
  "kind": 10002,
  "tags": [
    ["r", "wss://alicerelay.example.com"],
    ["r", "wss://brando-relay.com"],
    ["r", "wss://expensive-relay.example2.com", "write"],
    ["r", "wss://nostr-relay.example.com", "read"]
  ],
  "content": "",
  // other fields...
}

Client Behavior

For general URL references

Clients SHOULD display URL references in an appropriate way depending on the context of the event.

For website reactions

Clients SHOULD normalize URLs when processing reactions to websites so that reactions to the same URL are grouped together. Clients MAY display reactions with fragments separately from reactions to the base URL.

For relay list metadata

When downloading events from a user, clients SHOULD use the write relays of that user.

When downloading events about a user, where the user was tagged (mentioned), clients SHOULD use the user's read relays.

When publishing an event, clients SHOULD:

• Send the event to the write relays of the author
• Send the event to all read relays of each tagged user

Clients SHOULD guide users to keep kind:10002 lists small (2-4 relays of each category).

Clients SHOULD spread an author's kind:10002 event to as many relays as viable, paying attention to relays that serve as well-known public indexers for these relay lists.

Relay Behavior

Relays don't have special behavior for the r tag itself, but they should efficiently index and serve events that contain r tags to support client queries.

References

• NIP-24: Extra metadata fields and tags
• NIP-25: Reactions
• NIP-65: Relay List Metadata
• RFC 3986: URI Generic Syntax, Section 6: Normalization

Related Tags

• e: Event reference tag
• p: Pubkey reference tag
• a: Addressable event reference tag

Notes

1. The dual purpose of the r tag (web URL reference vs. relay URL) is determined by the context of the event in which it appears.

2. For relay list metadata (kind:10002), the marker parameter ("read" or "write") is optional. If omitted, the relay should be considered both for reading and writing.

3. In the context of website reactions (kind:17), it's important to normalize URLs to ensure consistent reaction grouping.

4. When using r tags to reference URLs, clients should be careful about automatically loading or displaying content from those URLs to prevent security or privacy issues.