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 122c7c6e..2a58c6c1 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 5b4cb5d8..04d20b52 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 f1d4e91c..1faa108c 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 3805b369..8b4c985c 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 ca2cb74a..da6c6a47 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 897ea196..0d33464e 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 d9d01317..477dd492 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 f9dee911..b1ba4d02 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 721f6344..603d88fd 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 0e223fa7..9beda8a0 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 0fe5164d..3a4b7fb2 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 6e788908..1e3c876e 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 26a10aed..65782362 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 2c663144..c2a760ca 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 caed647b..ce304883 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 eb51f7c8..07278aaf 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 b17c092f..d53ed158 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 5d0a01c4..51d6762c 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 2a9d9b60..2221ad5f 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 c84cd6c3..55d91141 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 063c3f3b..e65a7d01 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 e1601e33..efad0056 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 37975cbe..df992ee2 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 00000000..c75c0676
--- /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 b4bb75b4..4d759646 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 bf275ed6..63a35391 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 430c571a..5b2dd533 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 00000000..4113d922
--- /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 151e0606..2e000c73 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 6f3e92a8..ea3380a3 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 00000000..bdeadee4
--- /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 84b9dd7b..d4342c56 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"
   }
 }