From ccc1cdaeadd5a207cc3f23c938e46512e994204b Mon Sep 17 00:00:00 2001
From: Travis Ralston <travpc@gmail.com>
Date: Mon, 7 Jan 2019 14:38:21 -0700
Subject: [PATCH] Add support for unstable feature advertising via /versions

Incorporates https://github.com/matrix-org/matrix-doc/issues/1497
---
 api/client-server/versions.yaml | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/api/client-server/versions.yaml b/api/client-server/versions.yaml
index d3aa035947c..4d0fd49e8d0 100644
--- a/api/client-server/versions.yaml
+++ b/api/client-server/versions.yaml
@@ -33,13 +33,25 @@ 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, an accepted proposal
+        for a feature needing implementation would advertise itself here with
+        the intention of being removed from this list once the spec changes land.
       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 +62,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