diff --git a/fep/9098/fep-9098.md b/fep/9098/fep-9098.md index abfaf89..cf9c977 100644 --- a/fep/9098/fep-9098.md +++ b/fep/9098/fep-9098.md @@ -13,7 +13,7 @@ trackingIssue: https://codeberg.org/fediverse/fep/issues/648 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 [ActivityPub] network. +This document describes how custom emojis are implemented in the [ActivityPub] network. ## History @@ -28,12 +28,12 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S 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 `Emoji` string. -- `name` (REQUIRED): the [shortcode][Shortcode] of the custom emoji (the name of the emoji, enclosed in colons). +- `type` (REQUIRED): the literal string `Emoji`. +- `name` (REQUIRED): the [shortcode][Shortcode] of the custom emoji (the name of the emoji, enclosed in colons; see [Microsyntax](#microsyntax) section). - `updated` (OPTIONAL): the date when custom emoji was updated, formatted as [RFC-3339] date and time string. -- `icon` (REQUIRED): `Image` object describing emoji image. - - `type` (REQUIRED): the `Image` string. - - `url` (REQUIRED): the URL of the emoji image. +- `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 `icon` property in ActivityStreams Vocabulary recommends an aspect ratio of one to one, but in practice custom emojis have varied aspect ratios. @@ -57,35 +57,28 @@ Example: 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 `id` is not guaranteed to be globally unique, it MUST be omitted. +If a publisher doesn't guarantee that emoji `id` is globally unique, it MUST NOT add this property. ### Accessibility The short description of a custom emoji can be specified with the `alternateName` property (the full IRI is `http://schema.org/alternateName`). -### Compatibility - -In order to be compatible with as many servers as possible, implementations SHOULD comply with the following additional requirements: - -- Name contains at least two characters ([Mastodon](https://github.com/mastodon/mastodon/blob/v4.3.7/app/models/custom_emoji.rb#L28)). -- Name matches the regular expression `^[a-zA-Z0-9_]+$` ([Mastodon](https://github.com/mastodon/mastodon/blob/v4.3.7/app/models/custom_emoji.rb#L30)). -- Image media type is `image/png`, `image/gif` or `image/webp` ([Mastodon](https://github.com/mastodon/mastodon/blob/v4.3.7/app/models/custom_emoji.rb#L37)). -- Image size is not greater than 256 KB ([Mastodon](https://github.com/mastodon/mastodon/blob/v4.3.7/app/models/custom_emoji.rb#L27)). -- Image is a square (some clients may display non-squre emojis with a wrong aspect ratio). - ## Using custom emojis ### Microsyntax -Custom emojis can be inserted into textual representations of an object using [shortcodes][Shortcode] (shortcode is a name of an emoji enclosed in colons: `:emojiname:`). These textual representations are often specified with `name`, `summary` and `content` properties. +In text a custom emoji is represented by its [shortcode][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. -The corresponding `Emoji` objects are added to the `tag` array of the object. +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: ```json { "type": "Note", + "id": "https://social.example/notes/1234", "content": "

:blobcat:

", "tag": [ { @@ -101,9 +94,21 @@ Example: } ``` +### Right-to-left text + +Custom emoji shortcodes are always written left-to-right, even in right-to-left text. + ### Rendering -Applications typically replace custom emoji shortcodes with `` HTML tags and render the output as HTML. +#### General client considerations + +The aspect ratio of an image SHOULD be preserved. The maximum width of an image MAY be limited. + +Shortcodes inside `` and `
` HTML elements MUST NOT be replaced.
+
+#### Web client considerations
+
+Web applications typically replace custom emoji shortcodes with `` HTML tags and render the output as HTML.
 
 To prevent [Cross-Site Scripting (XSS)][XSS] attacks, implementers MUST ensure that:
 
@@ -111,9 +116,16 @@ To prevent [Cross-Site Scripting (XSS)][XSS] attacks, implementers MUST ensure t
 - When HTML content (e.g. `summary`, `content`) is processed, shortcodes are replaced only inside [Text][DOM-Text] nodes.
 - Reserved HTML characters in text are escaped before replacing shortcodes.
 
-The aspect ratio of the image SHOULD be preserved.
+## Compatibility
 
-Shortcodes inside `` and `
` HTML elements MUST NOT be replaced.
+In order to be compatible with as many servers as possible, implementations SHOULD comply with the following additional requirements:
+
+- Name contains at least two characters ([Mastodon](https://github.com/mastodon/mastodon/blob/v4.3.7/app/models/custom_emoji.rb#L28)).
+- Name matches the regular expression `^[a-zA-Z0-9_]+$` ([Mastodon](https://github.com/mastodon/mastodon/blob/v4.3.7/app/models/custom_emoji.rb#L30)).
+- Image media type is `image/png`, `image/gif` or `image/webp` ([Mastodon](https://github.com/mastodon/mastodon/blob/v4.3.7/app/models/custom_emoji.rb#L37)).
+- Image size is not greater than 256 KB ([Mastodon](https://github.com/mastodon/mastodon/blob/v4.3.7/app/models/custom_emoji.rb#L27)).
+- Image is a square (some clients may display non-squre emojis with a wrong aspect ratio).
+- Within a repeated run of emojis (e.g., `:blobcat: :blobcat: :blobcat:`) each shortcode is separated by at least one character that is not in the case-insensitive set `a-z0-9:` ([Mastodon](https://github.com/mastodon/mastodon/blob/v4.4.2/app/models/custom_emoji.rb#L32-L34), see also issue [#7364](https://github.com/mastodon/mastodon/issues/7364)).
 
 ## Implementations