Skip to content
Versiav0.7.0

Social Extension

The Social extension lets Users post Notes: text, images and other media, which other users can reply to and quote. It also gives each user a collection of their notes and a list of featured notes.

Notes are not just limited to microblogging. They can be used for any kind of content, such as forum posts, blog posts, image posts, video posts, audio posts, and even messaging.

Other extensions build on it, such as Likes, Share, Reactions, Polls, Groups and Interaction Controls.

Definition

Note

A Note is a piece of content posted by a User.

Type
"pub.versia:social/Note"
Fetch
GET /.versia/v0.7/entities/pub.versia:social/Note/{id}
Collections

Fields

type string Required

MUST be pub.versia:social/Note.

attachments Media[] Required

Media attachments to the note. Any media type is allowed. The content can place attachments inside the text.

author Reference Required

Reference to the User considered the author of the note.

category Category

Category of the note. Useful for clients to render notes differently depending on their intended purpose.

"microblog"
Short posts, like Twitter or Mastodon
"forum"
Threaded discussions, like Reddit
"blog"
Long articles, like WordPress or Medium
"image"
Image posts, like Instagram
"video"
Video posts, like YouTube or PeerTube
"audio"
Audio posts, like SoundCloud or Spotify
"messaging"
Chat messages, like Discord, Element or Signal

A receiver MUST treat an unknown value as if category were left out.

content RichText

The content of the note. It can place the note’s attachments inside its text with img, video and audio. Every user named in a mention in it MUST also be listed in mentions.

device Device

Device used to post the note. Useful for showing which app posted the note.

name string Required
version string
url string
visibility "public" | "subscribers" | "mentions" Required

Who can see the note, besides its author:

  • public: Anyone.
  • subscribers: The author’s subscribers, the users mentioned in the note, and the authors of the Notes it replies to.
  • mentions: Only the users mentioned in the note, and the authors of the Notes it replies to.
is_sensitive boolean Required

Whether the note contains “sensitive content”. This can be used with subject as a “content warning” feature.

mentions Reference[] Required

References to Users mentioned by the note. The content can also contain mentions, however only the mentions in this field SHOULD trigger notifications.

previews LinkPreview[] Required

Previews for any links in the publication. This is to avoid the stampeding mastodon problem where a link preview is fetched by every instance that sees the publication, creating an accidental DDOS attack.

Implementations SHOULD NOT trust previews, as a malicious remote instance could fake them to redirect users to malicious links.

title string Required
description string
image string
icon string
quoting Reference

Reference to the note that this note is quoting, if any. Quoting is similar to replying, but does not notify the author of the quoted note.

replies_to Reference

Reference to the note that this note is a reply to, if any.

subject string

A subject for the note. Useful for clients to display a “content warning” or “spoiler” feature, such as on Mastodon. MUST be plain text, not RichText.

url URI

Address of the note’s page on its instance, for people to open in a browser. Software that shows the note elsewhere can link to it.

Inherited from Entity: id, created_at, updated_at, extensions
{
    "id": "0341e147rp002",
    "type": "pub.versia:social/Note",
    "created_at": "2024-06-19T01:07:44Z",
    "attachments": [
        {
            "url": "https://cdn.example.com/29e810bf4707fef373d886af322089d5db300fce66e4e073efc26827f10825f6/image.png",
            "media_type": "image/png",
            "size": 221275,
            "hash": "967b8e86d8708c6283814f450efcbd3be94d3d24ca9a7ab435b2ff8b51dcbc21",
            "thumbhash": "1QcSHQRnh493V4dIh4eXh1h4kJUI",
            "width": 639,
            "height": 960
        },
        {
            "url": "https://cdn.example.com/68c02dd11c179ef4d170b05393f6e72133dd0ad733f40d41b42363d8784e8d5d/fire.txt",
            "media_type": "text/plain",
            "size": 8,
            "hash": "68c02dd11c179ef4d170b05393f6e72133dd0ad733f40d41b42363d8784e8d5d"
        }
    ],
    "author": "versia.example:033nrcdtky006",
    "category": "microblog",
    "content": "<p>In the next versia-fe update: account settings, finally!</p>",
    "device": {
        "name": "Example Client",
        "version": "1.0.0",
        "url": "https://client.example"
    },
    "extensions": {
        "pub.versia:custom_emojis": {
            "emojis": []
        }
    },
    "visibility": "public",
    "is_sensitive": false,
    "mentions": [],
    "previews": [],
    "subject": "Versia development",
    "url": "https://versia.example/notes/0341e147rp002"
}

Delivery and Access

A sender MUST deliver a Note to the instances hosting these users:

NoteDelivered to
visibility is publicThe author’s subscribers, the users it mentions, and the authors of the Notes it replies to and quotes
visibility is subscribersThe author’s subscribers, the users it mentions, and the authors of the Notes it replies to
visibility is mentionsThe users it mentions and the authors of the Notes it replies to

These instances may fetch a Note:

NoteMay be fetched by
visibility is publicAny instance
visibility is subscribersInstances hosting a subscriber of the author, a mentioned user, or the author of a Note it replies to
visibility is mentionsInstances hosting a mentioned user or the author of a Note it replies to

Notes Collection

Every user has a pub.versia:social/Notes collection (at /.versia/v0.7/entities/User/{id}/collections/pub.versia:social/Notes). It is a Collection of the Notes that the user has authored, and plays the role that an outbox plays in other protocols.

It MUST list only the Notes the requesting instance may fetch. For example, if Alice sends a Note whose visibility is mentions and that only mentions Bob, Alice’s instance MUST return it in response to a request from Bob’s instance, and MUST NOT list it in Alice’s collection in response to a request from Joe’s instance.

This collection is very useful for “backfilling” data when a new instance joins the network. By resolving the collections of all new users it encounters, a new instance can quickly catch up on all old notes.

User Collections

The Social extension adds the following collections to the User entity:

  • pub.versia:social/Notes: Collection of notes authored by the user, described under Notes Collection.
  • pub.versia:social/Featured: Reference Collection of notes that the user wants to feature on their profile (“pinned” notes).

Interaction Types

This extension registers the following interaction types:

  • pub.versia:social/reply, for sending a Note whose replies_to is the Note.
  • pub.versia:social/quote, for sending a Note whose quoting is the Note.

The Social extension adds the following Versia Link actions:

  • notes/{instance}/{id}: Open a note.
  • reply/{instance}/{id}: Open the composer to reply to a note.
  • quote/{instance}/{id}: Open the composer to quote a note.
  • compose/{text}: Compose a new note. Text passed at the end will be added in the note compose field. Used for “Share with Versia” buttons on websites. It has no {instance}.
web+versia://notes/jim.example/0341e147rp002
web+versia://reply/bob.example/0341e147rp002