Merge pull request #381 from arthurfranca/mention-alternative

3 files changed, 24 insertions, 1 deletions

diff --git a/08.md b/08.md
index 113cb53..2ab2b8f 100644
--- a/08.md
+++ b/08.md
@@ -1,3 +1,5 @@
+> __Warning__  `unrecommended`: deprecated in favor of NIP-27
+
 NIP-08
 ======
 
diff --git a/27.md b/27.md
new file mode 100644
index 0000000..f4e4629
--- /dev/null
+++ b/27.md
@@ -0,0 +1,20 @@
+NIP-27
+======
+
+Text Note References
+--------------------
+
+`draft` `optional` `author:fiatjaf` `author:scsibug` `author:arthurfranca`
+
+This document standardizes the treatment given by clients of inline references of other events and profiles inside the content of `text notes` (currently kinds 1 and 30023).
+
+Once a mention is identified by a client, for example, when an user pastes a NIP-19 nostr profile string inside the event content input field (or optionally by any other means the client may wish to support, such as selecting an user from a context menu or autocompleter), the client MUST replace it with the notation `nostr:nprofile1qqsw3dy8cpu...6x2argwghx6egsqstvg` as per NIP-21 before effectively creating the event. The client MAY add the corresponding pubkey to the `.tags` with the tag `p` if it wishes to notify mentioned user.
+
+The same process applies for referencing event IDs (using `nostr:nevent1...`), except that the client SHOULD NOT add the event id to the `.tags` with the tag `e` so to not negatively impact thread loading.
+Because `e` tags on `text notes` are usually considered ancestor events used to build a conversarion thread (as per NIP-10), it is advised to use inline references when mentioning events and NOT adding corresponding `e` tag to the `.tags` event key.
+
+Other nostr identifiers should be referenced similarly using NIP-21 URLs inside event content (e.g. `nostr:naddr1...` for parameterized replaceable events).
+
+Note that the usage of `nostr:npub1...` for profile mentions or `nostr:note1...` for event mentions is discouraged due to their lack of embedded relay recommendation.
+
+A reader client that receives a `text_note` event with such `nostr:...` mentions in its `.content` CAN do any desired context augmentation (for example, linking to the profile or showing a preview of the mentioned event contents) it wants in the process. If turning such mentions into links, they could become internal links, NIP-21 links or direct links to web clients that will handle these references.
diff --git a/README.md b/README.md
index 37b2fe4..9390916 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@ NIPs stand for **Nostr Implementation Possibilities**. They exist to document wh
 - [NIP-05: Mapping Nostr keys to DNS-based internet identifiers](05.md)
 - [NIP-06: Basic key derivation from mnemonic seed phrase](06.md)
 - [NIP-07: `window.nostr` capability for web browsers](07.md)
-- [NIP-08: Handling Mentions](08.md)
+- [NIP-08: Handling Mentions](08.md) – `unrecommended`: deprecated in favor of [NIP-27](27.md)
 - [NIP-09: Event Deletion](09.md)
 - [NIP-10: Conventions for clients' use of `e` and `p` tags in text events](10.md)
 - [NIP-11: Relay Information Document](11.md)
@@ -25,6 +25,7 @@ NIPs stand for **Nostr Implementation Possibilities**. They exist to document wh
 - [NIP-23: Long-form Content](23.md)
 - [NIP-25: Reactions](25.md)
 - [NIP-26: Delegated Event Signing](26.md)
+- [NIP-27: Text Note References](27.md)
 - [NIP-28: Public Chat](28.md)
 - [NIP-33: Parameterized Replaceable Events](33.md)
 - [NIP-36: Sensitive Content](36.md)