From 5be0df02c59aff880d12d83b9c1d94f5560a65cb Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Thu, 14 Oct 2021 13:23:04 -0600
Subject: [PATCH] Start annotating which version of the spec added a thing
 (#3425)

* Introduce a new "added-in" template and use it on endpoints

* Use "added-in" on schema properties too

* Annotate sections of the spec with their added versions

* Demo of "added-in" on a room version (to be fleshed out)

* Use clearer versioning semantics

* Update and fix validator for Swagger custom properties

* Fix docs
---
 .gitignore                                    |   3 +-
 content/client-server-api/_index.md           |   8 +-
 .../modules/end_to_end_encryption.md          |   2 +
 .../client-server-api/modules/guest_access.md |   2 +-
 .../modules/instant_messaging.md              |  28 +-
 content/client-server-api/modules/secrets.md  |   2 +
 content/rooms/v7.md                           |   2 +-
 data/api/client-server/banning.yaml           |   2 +
 data/api/client-server/cross_signing.yaml     |   2 +
 data/api/client-server/inviting.yaml          |   1 +
 data/api/client-server/joining.yaml           |   2 +
 data/api/client-server/key_backup.yaml        |   3 +
 data/api/client-server/keys.yaml              |   2 +
 data/api/client-server/knocking.yaml          |   1 +
 data/api/client-server/leaving.yaml           |   1 +
 .../api/client-server/sso_login_redirect.yaml |   2 +
 data/api/client-server/whoami.yaml            |   1 +
 data/api/identity/versions.yaml               |   1 +
 .../event-schemas/m.device_list_update.yaml   |   1 +
 .../event-schemas/m.signing_key_update.yaml   |   1 +
 data/api/server-server/knocks.yaml            |   2 +
 data/api/server-server/user_keys.yaml         |   2 +
 data/event-schemas/schema/m.room.member.yaml  |   1 +
 layouts/partials/added-in.html                |  13 +
 layouts/partials/events/render-event.html     |   4 +
 .../partials/openapi/render-object-table.html |   2 +-
 .../partials/openapi/render-operation.html    |   4 +
 layouts/shortcodes/added-in.html              |   8 +
 layouts/shortcodes/definition.html            |   4 +
 openapi_extensions.md                         |   6 +
 scripts/package-lock.json                     | 287 ++++++++++++++++++
 scripts/package.json                          |   2 +-
 32 files changed, 380 insertions(+), 22 deletions(-)
 create mode 100644 layouts/partials/added-in.html
 create mode 100644 layouts/shortcodes/added-in.html
 create mode 100644 scripts/package-lock.json

diff --git a/.gitignore b/.gitignore
index 122c7c6e3..2a58c6c17 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,9 +1,8 @@
-/api/node_modules
+node_modules
 /assets
 /assets.tar.gz
 /data/msc
 /env*
-/node_modules
 /resources
 /scripts/gen
 /scripts/continuserv/continuserv
diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index 5b4cb5d81..04d20b520 100644
--- a/content/client-server-api/_index.md
+++ b/content/client-server-api/_index.md
@@ -1039,9 +1039,9 @@ This returns an HTML and JavaScript page which can perform the entire
 login process. The page will attempt to call the JavaScript function
 `window.onLogin` when login has been successfully completed.
 
-Non-credential parameters valid for the `/login` endpoint can be
-provided as query string parameters here. These are to be forwarded to
-the login endpoint during the login process. For example:
+{{% added-in v="1.1" %}} Non-credential parameters valid for the `/login`
+endpoint can be provided as query string parameters here. These are to be
+forwarded to the login endpoint during the login process. For example:
 
     GET /_matrix/static/client/login/?device_id=GHTYAJCE
 
@@ -1746,6 +1746,8 @@ The allowable state transitions of membership are:
 
 ##### Knocking on rooms
 
+{{% added-in v="1.1" %}}
+
 <!--
 This section is here because it's most similar to being invited/joining a
 room, though has added complexity which needs to be explained. Otherwise
diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md
index f1d4e91cf..1faa108c4 100644
--- a/content/client-server-api/modules/end_to_end_encryption.md
+++ b/content/client-server-api/modules/end_to_end_encryption.md
@@ -992,6 +992,8 @@ user-signing keys.
 
 ##### QR codes
 
+{{% added-in v="1.1" %}}
+
 Verifying by QR codes provides a quick way to verify when one of the parties
 has a device capable of scanning a QR code. The QR code encodes both parties'
 master signing keys as well as a random shared secret that is used to allow
diff --git a/content/client-server-api/modules/guest_access.md b/content/client-server-api/modules/guest_access.md
index 3805b3699..8b4c985c6 100644
--- a/content/client-server-api/modules/guest_access.md
+++ b/content/client-server-api/modules/guest_access.md
@@ -44,7 +44,7 @@ for retrieving events:
 -   [GET /rooms/:room\_id/event/:event\_id](#get_matrixclientv3roomsroomideventeventid)
 -   [GET /rooms/:room\_id/state/:event\_type/:state\_key](#get_matrixclientv3roomsroomidstateeventtypestatekey)
 -   [GET /rooms/:room\_id/messages](#get_matrixclientv3roomsroomidmessages)
--   [GET /rooms/:room\_id/members](#get_matrixclientv3roomsroomidmembers)
+-   {{% added-in v="1.1" %}} [GET /rooms/:room\_id/members](#get_matrixclientv3roomsroomidmembers)
 -   [GET /rooms/:room\_id/initialSync](#get_matrixclientv3roomsroomidinitialsync)
 -   [GET /sync](#get_matrixclientv3sync)
 -   [GET /events](#get_matrixclientv3events) as used for room previews.
diff --git a/content/client-server-api/modules/instant_messaging.md b/content/client-server-api/modules/instant_messaging.md
index ca2cb74a3..da6c6a475 100644
--- a/content/client-server-api/modules/instant_messaging.md
+++ b/content/client-server-api/modules/instant_messaging.md
@@ -15,7 +15,7 @@ room itself such as a room name and topic.
 
 {{% event event="m.room.message.feedback" %}}
 
-Usage of this event is discouraged for several reasons:  
+Usage of this event is discouraged for several reasons:
 -   The number of feedback events will grow very quickly with the number
     of users in the room. This event provides no way to "batch"
     feedback, unlike the [receipts module](#receipts).
@@ -62,25 +62,25 @@ listed for the tags below. Where `data-mx-bg-color` and `data-mx-color`
 are listed, clients should translate the value (a 6-character hex color
 code) to the appropriate CSS/attributes for the tag.
 
-`font`  
+`font`
 `data-mx-bg-color`, `data-mx-color`, `color`
 
-`span`  
-`data-mx-bg-color`, `data-mx-color`, `data-mx-spoiler` (see 
+`span`
+`data-mx-bg-color`, `data-mx-color`, `data-mx-spoiler` (see
 [spoiler messages](#spoiler-messages))
 
-`a`  
+`a`
 `name`, `target`, `href` (provided the value is not relative and has a
 scheme matching one of: `https`, `http`, `ftp`, `mailto`, `magnet`)
 
-`img`  
+`img`
 `width`, `height`, `alt`, `title`, `src` (provided it is a [Matrix
 Content (MXC) URI](#matrix-content-mxc-uris))
 
-`ol`  
+`ol`
 `start`
 
-`code`  
+`code`
 `class` (only classes which start with `language-` for syntax
 highlighting)
 
@@ -464,14 +464,16 @@ text should be `"sent a video."`. For `m.audio`, the text should be
 
 ##### Spoiler messages
 
-Parts of a message can be hidden visually from the user through use of spoilers. 
-This does not affect the server's representation of the event content - it 
-is simply a visual cue to the user that the message may reveal important 
+{{% added-in v="1.1" %}}
+
+Parts of a message can be hidden visually from the user through use of spoilers.
+This does not affect the server's representation of the event content - it
+is simply a visual cue to the user that the message may reveal important
 information about something, spoiling any relevant surprise.
 
-To send spoilers clients MUST use the `formatted_body` and therefore the 
+To send spoilers clients MUST use the `formatted_body` and therefore the
 `org.matrix.custom.html` format, described above. This makes spoilers valid on
-any `msgtype` which can support this format appropriately. 
+any `msgtype` which can support this format appropriately.
 
 Spoilers themselves are contained with `span` tags, with the reason (optionally)
 being in the `data-mx-spoiler` attribute. Spoilers without a reason must at least
diff --git a/content/client-server-api/modules/secrets.md b/content/client-server-api/modules/secrets.md
index 897ea1964..0d33464e2 100644
--- a/content/client-server-api/modules/secrets.md
+++ b/content/client-server-api/modules/secrets.md
@@ -5,6 +5,8 @@ weight: 110
 
 ### Secrets
 
+{{% added-in v="1.1" %}}
+
 Clients may have secret information that they wish to be made available
 to other authorised clients, but that the server should not be able to
 see, so the information must be encrypted as it passes through the
diff --git a/content/rooms/v7.md b/content/rooms/v7.md
index d9d01317d..477dd4920 100644
--- a/content/rooms/v7.md
+++ b/content/rooms/v7.md
@@ -26,7 +26,7 @@ Room version 7 adds new authorization rules for events to support knocking.
 [Room version 6](/rooms/v6) has details of other authorization rule changes,
 as do the versions v6 is based upon.
 
-For checks perfomed upon `m.room.member` events, the following conditions
+{{% added-in this=true %}} For checks perfomed upon `m.room.member` events, the following conditions
 are added in context:
 
     If type is `m.room.member`:
diff --git a/data/api/client-server/banning.yaml b/data/api/client-server/banning.yaml
index f9dee911f..b1ba4d026 100644
--- a/data/api/client-server/banning.yaml
+++ b/data/api/client-server/banning.yaml
@@ -60,6 +60,7 @@ paths:
                 type: string
                 description: The fully qualified user ID of the user being banned.
               reason:
+                x-addedInMatrixVersion: "1.1"
                 type: string
                 description: The reason the user has been banned. This will be supplied as the
                   `reason` on the target's updated [`m.room.member`](/client-server-api/#mroommember) event.
@@ -119,6 +120,7 @@ paths:
                 type: string
                 description: The fully qualified user ID of the user being unbanned.
               reason:
+                x-addedInMatrixVersion: "1.1"
                 type: string
                 description: |-
                   Optional reason to be included as the `reason` on the subsequent
diff --git a/data/api/client-server/cross_signing.yaml b/data/api/client-server/cross_signing.yaml
index 721f6344c..603d88fdc 100644
--- a/data/api/client-server/cross_signing.yaml
+++ b/data/api/client-server/cross_signing.yaml
@@ -29,6 +29,7 @@ securityDefinitions:
 paths:
   "/keys/device_signing/upload":
     post:
+      x-addedInMatrixVersion: "1.1"
       summary: Upload cross-signing keys.
       description: |-
         Publishes cross-signing keys for the user.
@@ -140,6 +141,7 @@ paths:
         - End-to-end encryption
   "/keys/signatures/upload":
     post:
+      x-addedInMatrixVersion: "1.1"
       summary: Upload cross-signing signatures.
       description: |-
         Publishes cross-signing signatures for the user.  The request body is a
diff --git a/data/api/client-server/inviting.yaml b/data/api/client-server/inviting.yaml
index 0e223fa73..9beda8a09 100644
--- a/data/api/client-server/inviting.yaml
+++ b/data/api/client-server/inviting.yaml
@@ -72,6 +72,7 @@ paths:
                 type: string
                 description: The fully qualified user ID of the invitee.
               reason:
+                x-addedInMatrixVersion: "1.1"
                 type: string
                 description: |-
                   Optional reason to be included as the `reason` on the subsequent
diff --git a/data/api/client-server/joining.yaml b/data/api/client-server/joining.yaml
index 0fe5164d5..3a4b7fb2f 100644
--- a/data/api/client-server/joining.yaml
+++ b/data/api/client-server/joining.yaml
@@ -66,6 +66,7 @@ paths:
                   `m.room.third_party_invite` event in the room, and perform
                   key validity checking if required by the event.
               reason:
+                x-addedInMatrixVersion: "1.1"
                 type: string
                 description: |-
                   Optional reason to be included as the `reason` on the subsequent
@@ -152,6 +153,7 @@ paths:
                   that it matches a pending `m.room.third_party_invite` event in the
                   room, and perform key validity checking if required by the event.
               reason:
+                x-addedInMatrixVersion: "1.1"
                 type: string
                 description: |-
                   Optional reason to be included as the `reason` on the subsequent
diff --git a/data/api/client-server/key_backup.yaml b/data/api/client-server/key_backup.yaml
index 6e7889089..1e3c876e0 100644
--- a/data/api/client-server/key_backup.yaml
+++ b/data/api/client-server/key_backup.yaml
@@ -29,6 +29,7 @@ securityDefinitions:
 paths:
   "/room_keys/version":
     post:
+      x-addedInMatrixVersion: "1.1"
       summary: Create a new backup.
       description: |-
         Creates a new backup.
@@ -157,6 +158,7 @@ paths:
         - End-to-end encryption
   "/room_keys/version/{version}":
     get:
+      x-addedInMatrixVersion: "1.1"
       summary: Get information about an existing backup.
       description: |-
         Get information about an existing backup.
@@ -734,6 +736,7 @@ paths:
         - End-to-end encryption
   "/room_keys/keys":
     put:
+      x-addedInMatrixVersion: "1.1"
       summary: Store several keys in the backup.
       description: |-
         Store several keys in the backup.
diff --git a/data/api/client-server/keys.yaml b/data/api/client-server/keys.yaml
index 26a10aede..65782362f 100644
--- a/data/api/client-server/keys.yaml
+++ b/data/api/client-server/keys.yaml
@@ -238,6 +238,7 @@ paths:
                       }
                     }
               master_keys:
+                x-addedInMatrixVersion: "1.1"
                 type: object
                 description: |-
                   Information on the master cross-signing keys of the queried users.
@@ -259,6 +260,7 @@ paths:
                   }
                 }
               self_signing_keys:
+                x-addedInMatrixVersion: "1.1"
                 type: object
                 description: |-
                   Information on the self-signing keys of the queried users. A map
diff --git a/data/api/client-server/knocking.yaml b/data/api/client-server/knocking.yaml
index 2c663144b..c2a760ca6 100644
--- a/data/api/client-server/knocking.yaml
+++ b/data/api/client-server/knocking.yaml
@@ -29,6 +29,7 @@ securityDefinitions:
 paths:
   "/knock/{roomIdOrAlias}":
     post:
+      x-addedInMatrixVersion: "1.1"
       summary: Knock on a room, requesting permission to join.
       description: |-
         *Note that this API takes either a room ID or alias, unlike other membership APIs.*
diff --git a/data/api/client-server/leaving.yaml b/data/api/client-server/leaving.yaml
index caed647b6..ce304883d 100644
--- a/data/api/client-server/leaving.yaml
+++ b/data/api/client-server/leaving.yaml
@@ -62,6 +62,7 @@ paths:
             }
             properties:
               reason:
+                x-addedInMatrixVersion: "1.1"
                 type: string
                 description: |-
                   Optional reason to be included as the `reason` on the subsequent
diff --git a/data/api/client-server/sso_login_redirect.yaml b/data/api/client-server/sso_login_redirect.yaml
index eb51f7c8f..07278aafa 100644
--- a/data/api/client-server/sso_login_redirect.yaml
+++ b/data/api/client-server/sso_login_redirect.yaml
@@ -23,6 +23,7 @@ basePath: /_matrix/client/v3
 paths:
   "/login/sso/redirect":
     get:
+      x-addedInMatrixVersion: "1.1"
       summary: Redirect the user's browser to the SSO interface.
       description: |-
         A web-based Matrix client should instruct the user's browser to
@@ -50,6 +51,7 @@ paths:
        - Session management
   "/login/sso/redirect/{idpId}":
     get:
+      x-addedInMatrixVersion: "1.1"
       summary: Redirect the user's browser to the SSO interface for an IdP.
       description: |-
         This endpoint is the same as `/login/sso/redirect`, though with an
diff --git a/data/api/client-server/whoami.yaml b/data/api/client-server/whoami.yaml
index b17c092fe..d53ed1581 100644
--- a/data/api/client-server/whoami.yaml
+++ b/data/api/client-server/whoami.yaml
@@ -58,6 +58,7 @@ paths:
                 type: string
                 description: The user ID that owns the access token.
               device_id:
+                x-addedInMatrixVersion: "1.1"
                 type: string
                 description: |-
                   Device ID associated with the access token. If no device
diff --git a/data/api/identity/versions.yaml b/data/api/identity/versions.yaml
index 5d0a01c42..51d6762ce 100644
--- a/data/api/identity/versions.yaml
+++ b/data/api/identity/versions.yaml
@@ -24,6 +24,7 @@ produces:
 paths:
   "/versions":
     get:
+      x-addedInMatrixVersion: "1.1"
       summary: Gets the versions of the specification supported by the server.
       description: |-
         Gets the versions of the specification supported by the server.
diff --git a/data/api/server-server/definitions/event-schemas/m.device_list_update.yaml b/data/api/server-server/definitions/event-schemas/m.device_list_update.yaml
index 2a9d9b602..2221ad5fd 100644
--- a/data/api/server-server/definitions/event-schemas/m.device_list_update.yaml
+++ b/data/api/server-server/definitions/event-schemas/m.device_list_update.yaml
@@ -13,6 +13,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+x-addedInMatrixVersion: "1.1"
 type: object
 title: m.device_list_update
 description: |-
diff --git a/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml b/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml
index c84cd6c31..55d911410 100644
--- a/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml
+++ b/data/api/server-server/definitions/event-schemas/m.signing_key_update.yaml
@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+x-addedInMatrixVersion: "1.1"
 type: object
 title: m.signing_key_update
 description: |-
diff --git a/data/api/server-server/knocks.yaml b/data/api/server-server/knocks.yaml
index 063c3f3b0..e65a7d01f 100644
--- a/data/api/server-server/knocks.yaml
+++ b/data/api/server-server/knocks.yaml
@@ -29,6 +29,7 @@ securityDefinitions:
 paths:
   "/make_knock/{roomId}/{userId}":
     get:
+      x-addedInMatrixVersion: "1.1"
       summary: Get information required to make a knock event for a room.
       description: |-
         Asks the receiving server to return information that the sending
@@ -190,6 +191,7 @@ paths:
 
   "/send_knock/{roomId}/{eventId}":
     put:
+      x-addedInMatrixVersion: "1.1"
       summary: Submit a signed knock event to a resident server.
       description: |-
         Submits a signed knock event to the resident server for it to
diff --git a/data/api/server-server/user_keys.yaml b/data/api/server-server/user_keys.yaml
index e1601e33c..efad00562 100644
--- a/data/api/server-server/user_keys.yaml
+++ b/data/api/server-server/user_keys.yaml
@@ -178,6 +178,7 @@ paths:
                             description:
                               The display name which the user set on the device.
               master_keys:
+                x-addedInMatrixVersion: "1.1"
                 type: object
                 description: |-
                   Information on the master cross-signing keys of the queried users.
@@ -199,6 +200,7 @@ paths:
                   }
                 }
               self_signing_keys:
+                x-addedInMatrixVersion: "1.1"
                 type: object
                 description: |-
                   Information on the self-signing keys of the queried users. A map
diff --git a/data/event-schemas/schema/m.room.member.yaml b/data/event-schemas/schema/m.room.member.yaml
index 37975cbe1..df992ee25 100644
--- a/data/event-schemas/schema/m.room.member.yaml
+++ b/data/event-schemas/schema/m.room.member.yaml
@@ -64,6 +64,7 @@ properties:
         description: Flag indicating if the room containing this event was created with the intention of being a direct chat. See [Direct Messaging](/client-server-api/#direct-messaging).
         type: boolean
       reason:
+        x-addedInMatrixVersion: "1.1"
         type: string
         description: |-
           Optional user-supplied text for why their membership has changed. For kicks and bans, this is typically the reason for the kick or ban.
diff --git a/layouts/partials/added-in.html b/layouts/partials/added-in.html
new file mode 100644
index 000000000..c75c0676d
--- /dev/null
+++ b/layouts/partials/added-in.html
@@ -0,0 +1,13 @@
+{{ $ver := .v }}
+{{ $this := .this }}
+
+{{/*
+    This differs from the shortcode added-in by wanting to be a block instead of inline
+    and by slightly altering the rendered text as a result.
+*/}}
+
+{{ if $this }}
+  **New in this version.**
+{{ else }}
+  **Added in `v{{ $ver }}`**
+{{ end }}
diff --git a/layouts/partials/events/render-event.html b/layouts/partials/events/render-event.html
index b4bb75b4f..4d7596461 100644
--- a/layouts/partials/events/render-event.html
+++ b/layouts/partials/events/render-event.html
@@ -25,6 +25,10 @@
 
   <hr/>
 
+{{ if (index $event_data "x-addedInMatrixVersion") }}
+  {{ partial "added-in" (dict "v" (index $event_data "x-addedInMatrixVersion")) }}
+{{ end }}
+
 {{ $event_data.description | markdownify }}
 
 </summary>
diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html
index bf275ed6e..63a353918 100644
--- a/layouts/partials/openapi/render-object-table.html
+++ b/layouts/partials/openapi/render-object-table.html
@@ -82,7 +82,7 @@
  <tr>
   <td><code>{{ $property_name }}</code></td>
   <td><code>{{ $type }}</code></td>
-  <td>{{ if $required }}<strong>Required: </strong>{{end}}{{ $property.description | markdownify }}{{ if eq $type "enum"}}<p>One of: <code>{{ $property.enum }}</code>.</p>{{ end }}</td>
+  <td>{{ if $required }}<strong>Required: </strong>{{end}}{{ $property.description | markdownify }}{{ if eq $type "enum"}}<p>One of: <code>{{ $property.enum }}</code>.</p>{{ end }}{{ if (index $property "x-addedInMatrixVersion") }}{{ partial "added-in" (dict "v" (index $property "x-addedInMatrixVersion")) }}{{ end }}</td>
  </tr>
 
     {{ end }}
diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html
index 430c571a0..5b2dd5335 100644
--- a/layouts/partials/openapi/render-operation.html
+++ b/layouts/partials/openapi/render-operation.html
@@ -39,6 +39,10 @@
     {{ partial "alert" (dict "type" "warning" "omit_title" "true" "content" "This API is deprecated and will be removed from a future release.") }}
 {{ end }}
 
+{{ if (index $operation_data "x-addedInMatrixVersion") }}
+  {{ partial "added-in" (dict "v" (index $operation_data "x-addedInMatrixVersion")) }}
+{{ end }}
+
 <p>{{ $operation_data.description | markdownify }}</p>
 
 </summary>
diff --git a/layouts/shortcodes/added-in.html b/layouts/shortcodes/added-in.html
new file mode 100644
index 000000000..4113d9227
--- /dev/null
+++ b/layouts/shortcodes/added-in.html
@@ -0,0 +1,8 @@
+{{ $ver := .Params.v }}
+{{ $this := .Params.this }}
+
+{{ if $this }}
+  <span>**[New in this version]**</span>
+{{ else }}
+  <span>**[Added in `v{{ $ver }}`]**</span>
+{{ end }} {{/* Do not leave an empty line at the end of this file otherwise the inline behaviour breaks. */}}
\ No newline at end of file
diff --git a/layouts/shortcodes/definition.html b/layouts/shortcodes/definition.html
index 151e06060..2e000c730 100644
--- a/layouts/shortcodes/definition.html
+++ b/layouts/shortcodes/definition.html
@@ -37,6 +37,10 @@
 
 <hr/>
 
+{{ if (index $definition "x-addedInMatrixVersion") }}
+  {{ partial "added-in" (dict "v" (index $definition "x-addedInMatrixVersion")) }}
+{{ end }}
+
 {{ $definition.description | markdownify }}
 
 </summary>
diff --git a/openapi_extensions.md b/openapi_extensions.md
index 6f3e92a81..ea3380a30 100644
--- a/openapi_extensions.md
+++ b/openapi_extensions.md
@@ -62,3 +62,9 @@ doesn't work, as in the following example:
 In some cases, the schema will have HTTP response code definitions like
 `2xx`, `3xx`, and `4xx`. These indicate that a response code within those
 ranges (`2xx` = `200` to `299`) is valid for the schema.
+
+## Custom `x-addedInMatrixVersion` key
+
+This property is added throughout the OpenAPI schemas to denote which version
+of the Matrix specification added the associated object (endpoint, parameter,
+property, etc).
diff --git a/scripts/package-lock.json b/scripts/package-lock.json
new file mode 100644
index 000000000..bdeadee4b
--- /dev/null
+++ b/scripts/package-lock.json
@@ -0,0 +1,287 @@
+{
+  "name": "swagger-cli-validator",
+  "version": "0.0.1",
+  "lockfileVersion": 2,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "swagger-cli-validator",
+      "version": "0.0.1",
+      "license": "ISC",
+      "dependencies": {
+        "nopt": "^3.0.2",
+        "swagger-parser": "^10.0.3"
+      }
+    },
+    "node_modules/@apidevtools/json-schema-ref-parser": {
+      "version": "9.0.9",
+      "resolved": "https://registry.npmjs.org/@apidevtools/json-schema-ref-parser/-/json-schema-ref-parser-9.0.9.tgz",
+      "integrity": "sha512-GBD2Le9w2+lVFoc4vswGI/TjkNIZSVp7+9xPf+X3uidBfWnAeUWmquteSyt0+VCrhNMWj/FTABISQrD3Z/YA+w==",
+      "dependencies": {
+        "@jsdevtools/ono": "^7.1.3",
+        "@types/json-schema": "^7.0.6",
+        "call-me-maybe": "^1.0.1",
+        "js-yaml": "^4.1.0"
+      }
+    },
+    "node_modules/@apidevtools/openapi-schemas": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@apidevtools/openapi-schemas/-/openapi-schemas-2.1.0.tgz",
+      "integrity": "sha512-Zc1AlqrJlX3SlpupFGpiLi2EbteyP7fXmUOGup6/DnkRgjP9bgMM/ag+n91rsv0U1Gpz0H3VILA/o3bW7Ua6BQ==",
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/@apidevtools/swagger-methods": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/@apidevtools/swagger-methods/-/swagger-methods-3.0.2.tgz",
+      "integrity": "sha512-QAkD5kK2b1WfjDS/UQn/qQkbwF31uqRjPTrsCs5ZG9BQGAkjwvqGFjjPqAuzac/IYzpPtRzjCP1WrTuAIjMrXg=="
+    },
+    "node_modules/@apidevtools/swagger-parser": {
+      "version": "10.0.3",
+      "resolved": "https://registry.npmjs.org/@apidevtools/swagger-parser/-/swagger-parser-10.0.3.tgz",
+      "integrity": "sha512-sNiLY51vZOmSPFZA5TF35KZ2HbgYklQnTSDnkghamzLb3EkNtcQnrBQEj5AOCxHpTtXpqMCRM1CrmV2rG6nw4g==",
+      "dependencies": {
+        "@apidevtools/json-schema-ref-parser": "^9.0.6",
+        "@apidevtools/openapi-schemas": "^2.0.4",
+        "@apidevtools/swagger-methods": "^3.0.2",
+        "@jsdevtools/ono": "^7.1.3",
+        "call-me-maybe": "^1.0.1",
+        "z-schema": "^5.0.1"
+      },
+      "peerDependencies": {
+        "openapi-types": ">=7"
+      }
+    },
+    "node_modules/@jsdevtools/ono": {
+      "version": "7.1.3",
+      "resolved": "https://registry.npmjs.org/@jsdevtools/ono/-/ono-7.1.3.tgz",
+      "integrity": "sha512-4JQNk+3mVzK3xh2rqd6RB4J46qUR19azEHBneZyTZM+c456qOrbbM/5xcR8huNCCcbVt7+UmizG6GuUvPvKUYg=="
+    },
+    "node_modules/@types/json-schema": {
+      "version": "7.0.9",
+      "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.9.tgz",
+      "integrity": "sha512-qcUXuemtEu+E5wZSJHNxUXeCZhAfXKQ41D+duX+VYPde7xyEVZci+/oXKJL13tnRs9lR2pr4fod59GT6/X1/yQ=="
+    },
+    "node_modules/abbrev": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz",
+      "integrity": "sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q=="
+    },
+    "node_modules/argparse": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
+      "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q=="
+    },
+    "node_modules/call-me-maybe": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/call-me-maybe/-/call-me-maybe-1.0.1.tgz",
+      "integrity": "sha1-JtII6onje1y95gJQoV8DHBak1ms="
+    },
+    "node_modules/commander": {
+      "version": "2.20.3",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz",
+      "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==",
+      "optional": true
+    },
+    "node_modules/js-yaml": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz",
+      "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==",
+      "dependencies": {
+        "argparse": "^2.0.1"
+      },
+      "bin": {
+        "js-yaml": "bin/js-yaml.js"
+      }
+    },
+    "node_modules/lodash.get": {
+      "version": "4.4.2",
+      "resolved": "https://registry.npmjs.org/lodash.get/-/lodash.get-4.4.2.tgz",
+      "integrity": "sha1-LRd/ZS+jHpObRDjVNBSZ36OCXpk="
+    },
+    "node_modules/lodash.isequal": {
+      "version": "4.5.0",
+      "resolved": "https://registry.npmjs.org/lodash.isequal/-/lodash.isequal-4.5.0.tgz",
+      "integrity": "sha1-QVxEePK8wwEgwizhDtMib30+GOA="
+    },
+    "node_modules/nopt": {
+      "version": "3.0.6",
+      "resolved": "https://registry.npmjs.org/nopt/-/nopt-3.0.6.tgz",
+      "integrity": "sha1-xkZdvwirzU2zWTF/eaxopkayj/k=",
+      "dependencies": {
+        "abbrev": "1"
+      },
+      "bin": {
+        "nopt": "bin/nopt.js"
+      }
+    },
+    "node_modules/openapi-types": {
+      "version": "9.3.0",
+      "resolved": "https://registry.npmjs.org/openapi-types/-/openapi-types-9.3.0.tgz",
+      "integrity": "sha512-sR23YjmuwDSMsQVZDHbV9mPgi0RyniQlqR0AQxTC2/F3cpSjRFMH3CFPjoWvNqhC4OxPkDYNb2l8Mc1Me6D/KQ==",
+      "peer": true
+    },
+    "node_modules/swagger-parser": {
+      "version": "10.0.3",
+      "resolved": "https://registry.npmjs.org/swagger-parser/-/swagger-parser-10.0.3.tgz",
+      "integrity": "sha512-nF7oMeL4KypldrQhac8RyHerJeGPD1p2xDh900GPvc+Nk7nWP6jX2FcC7WmkinMoAmoO774+AFXcWsW8gMWEIg==",
+      "dependencies": {
+        "@apidevtools/swagger-parser": "10.0.3"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/validator": {
+      "version": "13.6.0",
+      "resolved": "https://registry.npmjs.org/validator/-/validator-13.6.0.tgz",
+      "integrity": "sha512-gVgKbdbHgtxpRyR8K0O6oFZPhhB5tT1jeEHZR0Znr9Svg03U0+r9DXWMrnRAB+HtCStDQKlaIZm42tVsVjqtjg==",
+      "engines": {
+        "node": ">= 0.10"
+      }
+    },
+    "node_modules/z-schema": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/z-schema/-/z-schema-5.0.1.tgz",
+      "integrity": "sha512-Gp8xU2lULhREqTWj9t4BEAeA7M835n4fWJ9KjGWksV3wmLUdOJo2hAr+QYvkVZIGOOTyeN274g1f95dKRsgYgQ==",
+      "dependencies": {
+        "lodash.get": "^4.4.2",
+        "lodash.isequal": "^4.5.0",
+        "validator": "^13.6.0"
+      },
+      "bin": {
+        "z-schema": "bin/z-schema"
+      },
+      "engines": {
+        "node": ">=8.0.0"
+      },
+      "optionalDependencies": {
+        "commander": "^2.7.1"
+      }
+    }
+  },
+  "dependencies": {
+    "@apidevtools/json-schema-ref-parser": {
+      "version": "9.0.9",
+      "resolved": "https://registry.npmjs.org/@apidevtools/json-schema-ref-parser/-/json-schema-ref-parser-9.0.9.tgz",
+      "integrity": "sha512-GBD2Le9w2+lVFoc4vswGI/TjkNIZSVp7+9xPf+X3uidBfWnAeUWmquteSyt0+VCrhNMWj/FTABISQrD3Z/YA+w==",
+      "requires": {
+        "@jsdevtools/ono": "^7.1.3",
+        "@types/json-schema": "^7.0.6",
+        "call-me-maybe": "^1.0.1",
+        "js-yaml": "^4.1.0"
+      }
+    },
+    "@apidevtools/openapi-schemas": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@apidevtools/openapi-schemas/-/openapi-schemas-2.1.0.tgz",
+      "integrity": "sha512-Zc1AlqrJlX3SlpupFGpiLi2EbteyP7fXmUOGup6/DnkRgjP9bgMM/ag+n91rsv0U1Gpz0H3VILA/o3bW7Ua6BQ=="
+    },
+    "@apidevtools/swagger-methods": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/@apidevtools/swagger-methods/-/swagger-methods-3.0.2.tgz",
+      "integrity": "sha512-QAkD5kK2b1WfjDS/UQn/qQkbwF31uqRjPTrsCs5ZG9BQGAkjwvqGFjjPqAuzac/IYzpPtRzjCP1WrTuAIjMrXg=="
+    },
+    "@apidevtools/swagger-parser": {
+      "version": "10.0.3",
+      "resolved": "https://registry.npmjs.org/@apidevtools/swagger-parser/-/swagger-parser-10.0.3.tgz",
+      "integrity": "sha512-sNiLY51vZOmSPFZA5TF35KZ2HbgYklQnTSDnkghamzLb3EkNtcQnrBQEj5AOCxHpTtXpqMCRM1CrmV2rG6nw4g==",
+      "requires": {
+        "@apidevtools/json-schema-ref-parser": "^9.0.6",
+        "@apidevtools/openapi-schemas": "^2.0.4",
+        "@apidevtools/swagger-methods": "^3.0.2",
+        "@jsdevtools/ono": "^7.1.3",
+        "call-me-maybe": "^1.0.1",
+        "z-schema": "^5.0.1"
+      }
+    },
+    "@jsdevtools/ono": {
+      "version": "7.1.3",
+      "resolved": "https://registry.npmjs.org/@jsdevtools/ono/-/ono-7.1.3.tgz",
+      "integrity": "sha512-4JQNk+3mVzK3xh2rqd6RB4J46qUR19azEHBneZyTZM+c456qOrbbM/5xcR8huNCCcbVt7+UmizG6GuUvPvKUYg=="
+    },
+    "@types/json-schema": {
+      "version": "7.0.9",
+      "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.9.tgz",
+      "integrity": "sha512-qcUXuemtEu+E5wZSJHNxUXeCZhAfXKQ41D+duX+VYPde7xyEVZci+/oXKJL13tnRs9lR2pr4fod59GT6/X1/yQ=="
+    },
+    "abbrev": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz",
+      "integrity": "sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q=="
+    },
+    "argparse": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
+      "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q=="
+    },
+    "call-me-maybe": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/call-me-maybe/-/call-me-maybe-1.0.1.tgz",
+      "integrity": "sha1-JtII6onje1y95gJQoV8DHBak1ms="
+    },
+    "commander": {
+      "version": "2.20.3",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz",
+      "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==",
+      "optional": true
+    },
+    "js-yaml": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz",
+      "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==",
+      "requires": {
+        "argparse": "^2.0.1"
+      }
+    },
+    "lodash.get": {
+      "version": "4.4.2",
+      "resolved": "https://registry.npmjs.org/lodash.get/-/lodash.get-4.4.2.tgz",
+      "integrity": "sha1-LRd/ZS+jHpObRDjVNBSZ36OCXpk="
+    },
+    "lodash.isequal": {
+      "version": "4.5.0",
+      "resolved": "https://registry.npmjs.org/lodash.isequal/-/lodash.isequal-4.5.0.tgz",
+      "integrity": "sha1-QVxEePK8wwEgwizhDtMib30+GOA="
+    },
+    "nopt": {
+      "version": "3.0.6",
+      "resolved": "https://registry.npmjs.org/nopt/-/nopt-3.0.6.tgz",
+      "integrity": "sha1-xkZdvwirzU2zWTF/eaxopkayj/k=",
+      "requires": {
+        "abbrev": "1"
+      }
+    },
+    "openapi-types": {
+      "version": "9.3.0",
+      "resolved": "https://registry.npmjs.org/openapi-types/-/openapi-types-9.3.0.tgz",
+      "integrity": "sha512-sR23YjmuwDSMsQVZDHbV9mPgi0RyniQlqR0AQxTC2/F3cpSjRFMH3CFPjoWvNqhC4OxPkDYNb2l8Mc1Me6D/KQ==",
+      "peer": true
+    },
+    "swagger-parser": {
+      "version": "10.0.3",
+      "resolved": "https://registry.npmjs.org/swagger-parser/-/swagger-parser-10.0.3.tgz",
+      "integrity": "sha512-nF7oMeL4KypldrQhac8RyHerJeGPD1p2xDh900GPvc+Nk7nWP6jX2FcC7WmkinMoAmoO774+AFXcWsW8gMWEIg==",
+      "requires": {
+        "@apidevtools/swagger-parser": "10.0.3"
+      }
+    },
+    "validator": {
+      "version": "13.6.0",
+      "resolved": "https://registry.npmjs.org/validator/-/validator-13.6.0.tgz",
+      "integrity": "sha512-gVgKbdbHgtxpRyR8K0O6oFZPhhB5tT1jeEHZR0Znr9Svg03U0+r9DXWMrnRAB+HtCStDQKlaIZm42tVsVjqtjg=="
+    },
+    "z-schema": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/z-schema/-/z-schema-5.0.1.tgz",
+      "integrity": "sha512-Gp8xU2lULhREqTWj9t4BEAeA7M835n4fWJ9KjGWksV3wmLUdOJo2hAr+QYvkVZIGOOTyeN274g1f95dKRsgYgQ==",
+      "requires": {
+        "commander": "^2.7.1",
+        "lodash.get": "^4.4.2",
+        "lodash.isequal": "^4.5.0",
+        "validator": "^13.6.0"
+      }
+    }
+  }
+}
diff --git a/scripts/package.json b/scripts/package.json
index 84b9dd7b5..d4342c561 100644
--- a/scripts/package.json
+++ b/scripts/package.json
@@ -10,6 +10,6 @@
   "license": "ISC",
   "dependencies": {
     "nopt": "^3.0.2",
-    "swagger-parser": "^3.2.1"
+    "swagger-parser": "^10.0.3"
   }
 }