A custom emoji is a small image used to express an idea or emotion. Custom emojis are different from Unicode emojis, which are sequences of characters.
This document describes how custom emojis are implemented in the ActivityPub network.
Custom emojis were introduced by Pleroma (commits) and Mastodon (PR) in 2017.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC-2119.
Custom emojis are represented as Emoji objects (the full type IRI is http://joinmastodon.org/ns#Emoji). The Emoji object has the following properties:
id (RECOMMENDED): the unique identifier of the custom emoji. Some implementations omit this property (i.e. the object is anonymous).type (REQUIRED): the literal string Emoji.name (REQUIRED): the shortcode of the custom emoji (the name of the emoji, enclosed in colons; see Microsyntax section).updated (OPTIONAL): the date when custom emoji was updated, formatted as RFC-3339 date and time string.icon (REQUIRED): the Image object describing the emoji image.
type (REQUIRED): the literal string Image.url (REQUIRED): the URI of the image to use as the emoji.[!NOTE] The definition of the
iconproperty in ActivityStreams Vocabulary recommends an aspect ratio of one to one, but in practice custom emojis have varied aspect ratios.
Example:
{
"id": "https://social.example/emoji/blobcat",
"type": "Emoji",
"name": ":blobcat:",
"updated": "1970-01-01T00:00:00Z",
"icon": {
"type": "Image",
"url": "https://social.example/media/blobcat.png"
}
}
The primary unique identifier of a custom emoji is a combination of its name and the domain name. The domain name can be extracted from the id of Emoji object or from the id of the object within which it is embedded.
If a publisher doesn’t guarantee that emoji id is globally unique, it MUST NOT add this property.
The short description of a custom emoji can be specified with the alternateName property (the full IRI is http://schema.org/alternateName).
In text a custom emoji is represented by its shortcode, which is a name of an emoji enclosed in colons (e.g. :blobcat:). This is also the value of the Emoji object’s name property.
These textual representations are often inserted into values of name, summary and content properties of the object that embeds the custom emoji. E.g., the content of a Note, or the name of an Actor.
The corresponding Emoji objects are added to the tag array of the object. Within that array custom emojis can appear in any order.
Example:
{
"type": "Note",
"id": "https://social.example/notes/1234",
"content": "<p>:blobcat:</p>",
"tag": [
{
"id": "https://social.example/emoji/blobcat",
"type": "Emoji",
"name": ":blobcat:",
"icon": {
"type": "Image",
"url": "https://social.example/media/blobcat.png"
}
}
]
}
Custom emoji shortcodes are always written left-to-right, even in right-to-left text.
The aspect ratio of an image SHOULD be preserved. The maximum width of an image MAY be limited.
Shortcodes inside <code> and <pre> HTML elements MUST NOT be replaced.
Web applications typically replace custom emoji shortcodes with <img> HTML tags and render the output as HTML.
To prevent Cross-Site Scripting (XSS) attacks, implementers MUST ensure that:
&<>"').summary, content) is processed, shortcodes are replaced only inside Text nodes.In order to be compatible with as many servers as possible, implementations SHOULD comply with the following additional requirements:
[a-zA-Z0-9_] set (Mastodon).image/png, image/gif or image/webp (Mastodon).This document is based on implementations of custom emojis in Pleroma, Mastodon, Misskey and Fedibird.
CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
To the extent possible under law, the authors of this Fediverse Enhancement Proposal have waived all copyright and related or neighboring rights to this work.