Add event examples and address review comments

Signed-off-by: jpcshka <189279532+jpcshka@users.noreply.github.com>

content/client-server-api/modules/image_packs.md

@@ -8,7 +8,7 @@ collections and share them with others.
 An **emoticon** (also called an emote) is a custom image sent inline within a
 message, analogous to emoji but defined outside the Unicode standard. A
 **sticker** is a standalone image sent as an [`m.sticker`](#msticker) event.
-Image packs provide a distribution mechanism for both.
+Image packs provide a distribution and discovery mechanism for both.
 
 {{% boxes/note %}}
 Emoticons are distinct from the [`m.emote`](#mroommessage-msgtypes) message
@@ -34,7 +34,7 @@ Where `ALPHA` and `DIGIT` are as defined in
 [RFC 5234](https://datatracker.ietf.org/doc/html/rfc5234). Shortcodes are
 case-sensitive. The length of a shortcode MUST NOT exceed 100 bytes.
 
-The `:` character is excluded because it is widely used across messaging
+The `:` character is specifically excluded because it is widely used across messaging
 platforms as a delimiter for triggering emote search (for example, typing
 `:cat` to search for an emote named `cat`). The `/` character is excluded
 because clients MAY use it to separate a shortcode from a pack name in
@@ -57,6 +57,8 @@ when creating or editing image packs.
 
 {{% event event="m.room.image_pack" %}}
 
+#### Account data
+
 {{% event event="m.image_pack.rooms" %}}
 
 #### Image properties
@@ -82,6 +84,22 @@ To make a room's image pack available globally across all rooms, a user adds
 a reference to the pack in their `m.image_pack.rooms` account data event. The
 reference consists of the room ID and the `state_key` of the pack.
 
+For example, to enable two packs from different rooms:
+
+```json
+{
+  "rooms": {
+    "!someroom:example.org": {
+      "": {}
+    },
+    "!anotherroom:example.org": {
+      "": {},
+      "sticker_pack": {}
+    }
+  }
+}
+```
+
 #### Space image packs
 
 Clients SHOULD surface image packs defined in the canonical space of the
@@ -100,7 +118,7 @@ packs in the following order:
 2. Packs defined in the current room's state.
 3. Packs from the canonical space hierarchy of the current room.
 
-The ordering of images *within* a pack is left to a future specification.
+The ordering of images *within* a pack is currently up to implementations.
 
 #### Client behaviour
 
@@ -140,7 +158,7 @@ The `title` attribute SHOULD be present and set to the shortcode of the
 emote. Clients MAY display this as a tooltip.
 
 The `height` attribute MUST be present for backwards compatibility with
-clients that do not support custom emotes. Clients SHOULD set this to `32`.
+clients that do not support custom emotes. Clients SHOULD set this to "32".
 Clients implementing image pack support SHOULD override this value when
 rendering based on the user's font size or other environmental factors. The
 `width` attribute SHOULD be omitted to preserve the image's aspect ratio.

data/event-schemas/examples/m.image_pack.rooms.yaml

@@ -0,0 +1,15 @@
+{
+  "$ref": "core/event.json",
+  "type": "m.image_pack.rooms",
+  "content": {
+    "rooms": {
+      "!someroom:example.org": {
+        "": {}
+      },
+      "!anotherroom:example.org": {
+        "": {},
+        "sticker_pack": {}
+      }
+    }
+  }
+}

data/event-schemas/examples/m.room.image_pack.yaml

@@ -0,0 +1,29 @@
+{
+  "$ref": "core/state_event.json",
+  "type": "m.room.image_pack",
+  "state_key": "",
+  "content": {
+    "images": {
+      "cat_wave": {
+        "url": "mxc://example.org/abc123",
+        "body": "a waving cat",
+        "info": {
+          "mimetype": "image/png",
+          "w": 512,
+          "h": 512,
+          "size": 84400
+        }
+      },
+      "cat_nap": {
+        "url": "mxc://example.org/def456",
+        "body": "a sleeping cat"
+      }
+    },
+    "pack": {
+      "display_name": "Cats",
+      "avatar_url": "mxc://example.org/abc123",
+      "usage": ["emoticon"],
+      "attribution": "drawn by @alice:example.org"
+    }
+  }
+}

data/event-schemas/schema/m.room.image_pack.yaml

@@ -18,6 +18,9 @@ properties:
           A map from a [shortcode](#shortcode-grammar) to an image object.
           Each entry defines one image available in this pack.
         type: object
+        propertyNames:
+          type: string
+          pattern: '^[A-Za-z0-9_-]{1,100}$'
         additionalProperties:
           title: ImagePackImage
           type: object
@@ -68,7 +71,7 @@ properties:
             pattern: "^mxc:\\/\\/"
           usage:
             description: |-
-              The intended usages for this pack. The defined values are
+              The intended usage(s) for this pack. The defined values are
               `emoticon` (images intended to be sent inline in messages) and
               `sticker` (images intended to be sent as standalone sticker
               events). If absent or empty, all usage types are assumed.
@@ -83,15 +86,14 @@ properties:
                 - sticker
           attribution:
             description: |-
-              An attribution string for the pack, for example crediting the
-              original author or source.
+              An attribution string for the pack. For crediting the
+              original author or source, for example.
             type: string
     required:
       - images
   state_key:
     description: |-
-      A unique identifier for this image pack within the room. This is not
-      intended to be surfaced to users.
+      A unique identifier for this image pack within the room.
     type: string
   type:
     enum: