Activity Streams/Primer/Microsyntax for Mentions

from section 5.6 of Activity Streams 2.0 Vocabulary

Many social software systems use special text-based microsyntaxes that allow users to define special addressing for notifications, linking, or categorization within objects. For example, including text such as "@username" within an object's content will often route the object to a special "mentions" or "inbox" stream for a particular user. Likewise, including text such as " #topic" within the object's content will often mark the object as being related to the topic "topic". Such mechanisms are commonly referred to as "mentions" and "hashtags", respectively.

While such microsyntaxes may be used within the values of the content, name, and summary properties on an Activity Streams Object, implementations should not be required to parse the values of those properties in order to determine the appropriate routing of notifications, categorization or linking between objects. Instead, publishers should make appropriate use of the vocabulary terms provided specifically for these purposes.

For example, suppose that an author wishes to send a note of thanks to another user named "@sally" with a hashtag of "#givingthanks". A typical way this message would appear within the content of a note is shown below:

"Thank you @sally for all your hard work! #givingthanks" 

A typical social software implementation would typically render such a content such that "@sally" is replaced with a hyperlink to "@sally"'s social profile page and "#givingthanks" is replaced with a hyperlink to a listing of other notes that have been "tagged" with the same topic. Most implementations would also send a special notification to sally letting her know that a note mentioning her has been created.

The following illustrates an equivalent Activity Streams Note object:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "name": "A thank-you note",
  "type": "Note",
  "content": "Thank you <a href='http://sally.example.org'>@sally</a>
      for all your hard work!
      <a href='http://example.org/tags/givingthanks'>#givingthanks</a>",
  "to": {
    "name": "Sally",
    "type": "Person",
    "id": "http://sally.example.org"
  },
  "tag": {
    "id": "http://example.org/tags/givingthanks",
    "name": "#givingthanks"
  }
}

The to property indicates that the user "@sally" is to be considered part of the primary audience of the note and should therefore receive notification. The tag property associates the Note with a reference to " http://example.org/tags/givingthanks". Note that the content still includes the "@sally" and " #givingthanks" microsyntaxes but that consuming implementations are not required to parse those in order to make the appropriate associations.

In the case a publisher wishes to indicate a mention without an associated notification, the publisher can use the Mention object type as a value of the tag property.

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "name": "A thank-you note",
  "type": "Note",
  "content": "Thank you @sally for all your hard work! #givingthanks",
  "tag": [
    {
      "type": "Mention",
      "href": "http://example.org/people/sally",
      "name": "@sally"
    },
    {
      "id": "http://example.org/tags/givingthanks",
      "name": "#givingthanks"
    }
  ]
}

1. 1. In practice

Per Mastodon core dev nightpool, the distinction between including the Mention tag or not is ignored in Mastodon and perhaps other implementations. nightpool recommends the following code as a better example of current practice.

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "name": "A thank-you note",
  "type": "Note",
  "content": "Thank you <a href='http://sally.example.org'>@sally</a>
      for all your hard work!
      <a href='http://example.org/tags/givingthanks'>#givingthanks</a>",
  "to": {
    "name": "Sally",
    "type": "Person",
    "id": "http://example.org/people/sally"
  },
  "tag": [
    {
      "type": "Mention",
      "href": "http://example.org/people/sally",
      "name": "@sally"
    },
    {
      "id": "http://example.org/tags/givingthanks",
      "name": "#givingthanks"
    }
  ]
}