Add support for unstable feature advertising via /versions

api/client-server/versions.yaml

@@ -33,13 +33,28 @@ paths:
 
         Only the latest ``Z`` value will be reported for each supported ``X.Y`` value.
         i.e. if the server implements ``r0.0.0``, ``r0.0.1``, and ``r1.2.0``, it will report ``r0.0.1`` and ``r1.2.0``.
+
+        The server may additionally advertise experimental features it supports
+        through ``unstable_features``. These features should be namespaced and
+        may optionally include version information within their name if desired.
+        Features listed here are not for optionally toggling parts of the Matrix
+        specification and should only be used to advertise support for a feature
+        which has not yet landed in the spec. For example, a feature currently
+        undergoing the proposal process may appear here and eventually be taken
+        off this list once the feature lands in the spec and the server deems it
+        reasonable to do so. Servers may wish to keep advertising features here
+        after they've been released into the spec to give clients a chance to
+        upgrade appropriately.
       operationId: getVersions
       responses:
         200:
           description: The versions supported by the server.
           examples:
             application/json: {
-                "versions": ["r0.0.1"]
+                "versions": ["r0.0.1"],
+                "unstable_features": {
+                  "org.example.my_feature": true
+                }
               }
           schema:
             type: object
@@ -50,5 +65,15 @@ paths:
                 items:
                   type: string
                   description: The supported versions
+              unstable_features:
+                type: object
+                description: |-
+                  Experimental features the server supports. Features not listed here,
+                  or the lack of this property all together, indicate that a feature is
+                  not supported.
+                additionalProperties:
+                  type: boolean
+                  description: Whether or not the namespaced feature is supported.
+            required: ['versions']
       tags:
         - Server administration

changelogs/client_server/newsfragments/1786.feature

@@ -0,0 +1 @@
+Add support for advertising experimental features to clients.