Merge remote-tracking branch 'origin/master' into erikj/search_yet_agian

CHANGELOG.rst

@@ -1,41 +0,0 @@
-.. This file is automatically processed by the templating system. To make it
-.. happy, you MUST use '=' as the title underline and you MUST stick the version
-.. in the title. The version MUST follow the numbering format 
-.. "v<num>.<num>.<num>" - You cannot use a-z. If the templating system fails to
-.. find the right info, it will be treated as a test failure and so will show up
-.. in Jenkins. Comments like this are ignored by both RST and the templating
-.. system. Add the newest release notes beneath this comment.
-
-Specification changes in v0.2.0 (2015-10-02)
-============================================
-
-This update fundamentally restructures the specification. The specification has
-been split into more digestible "modules" which each describe a particular
-function (e.g. typing). This was done in order make the specification easier to
-maintain and help define which modules are mandatory for certain types
-of clients. Types of clients along with the mandatory modules can be found in a
-new "Feature Profiles" section. This update also begins to aggressively
-standardise on using Swagger and JSON Schema to document HTTP endpoints and
-Events respectively. It also introduces a number of new concepts to Matrix.
-
-Additions:
- - New section: Feature Profiles.
- - New section: Receipts.
- - New section: Room history visibility.
- - New event: ``m.receipt``.
- - New event: ``m.room.canonical_alias``
- - New event: ``m.room.history_visibility``
- - New keys: ``/createRoom`` - allows room "presets" using ``preset`` and
-   ``initial_state`` keys.
- - New endpoint: ``/tokenrefresh`` - Related to refreshing access tokens.
-
-Modifications:
- - Convert most of the older HTTP APIs to Swagger documentation.
- - Convert most of the older event formats to JSON Schema.
- - Move selected client-server sections to be "Modules".
-
-Specification changes in v0.1.0 (2015-06-01)
-============================================
-- First numbered release.
-- Restructure the format of Event information. Add more information.
-- Restructure the format of the Client-Server HTTP APIs.

api/application-service/application_service.yaml

@@ -198,4 +198,3 @@ paths:
               }
           schema:
             type: object
-

api/check_examples.py

@@ -49,7 +49,8 @@ def check_parameter(filepath, request, parameter):
             # Setting the 'id' tells jsonschema where the file is so that it
             # can correctly resolve relative $ref references in the schema
             schema['id'] = fileurl
-            jsonschema.validate(example, schema)
+            resolver = jsonschema.RefResolver(filepath, schema, handlers={"file": load_yaml})
+            jsonschema.validate(example, schema, resolver=resolver)
         except Exception as e:
             raise ValueError("Error validating JSON schema for %r" % (
                 request
@@ -76,7 +77,8 @@ def check_response(filepath, request, code, response):
             # Setting the 'id' tells jsonschema where the file is so that it
             # can correctly resolve relative $ref references in the schema
             schema['id'] = fileurl
-            jsonschema.validate(example, schema)
+            resolver = jsonschema.RefResolver(filepath, schema, handlers={"file": load_yaml})
+            jsonschema.validate(example, schema, resolver=resolver)
         except Exception as e:
             raise ValueError("Error validating JSON schema for %r %r" % (
                 request, code
@@ -103,6 +105,14 @@ def check_swagger_file(filepath):
                 check_response(filepath, request, code, response)
 
 
+def load_yaml(path):
+    if not path.startswith("file:///"):
+        raise Exception("Bad ref: %s" % (path,))
+    path = path[len("file://"):]
+    with open(path, "r") as f:
+        return yaml.load(f)
+
+
 if __name__ == '__main__':
     paths = sys.argv[1:]
     if not paths:

api/client-server/account-data.yaml

@@ -6,7 +6,7 @@ host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/v2_alpha
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -57,6 +57,8 @@ paths:
         200:
           description:
             The account_data was successfully added.
+      tags:
+        - User data
   "/user/{userId}/rooms/{roomId}/account_data/{type}":
     put:
       summary: Set some account_data for the user.
@@ -103,3 +105,5 @@ paths:
         200:
           description:
             The account_data was successfully added.
+      tags:
+        - User data

api/client-server/admin.yaml

@@ -0,0 +1,105 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Administration API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+paths:
+  "/admin/whois/{userId}":
+    get:
+      summary: Gets information about a particular user.
+      description: |-
+        Gets information about a particular user.
+
+        This API may be restricted to only be called by the user being looked
+        up, or by a server admin. Server-local administrator privileges are not
+        specified in this document.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          description: The user to look up.
+          required: true
+          x-example: "@peter:rabbit.rocks"
+      responses:
+        200:
+          description: The lookup was successful.
+          examples:
+            application/json: |-
+              {
+                "user_id": "@peter:rabbit.rocks",
+                "devices": {
+                  "teapot": {
+                    "sessions": [
+                      {
+                        "connections": [
+                          {
+                            "ip": "127.0.0.1",
+                            "last_seen": 1411996332123,
+                            "user_agent": "curl/7.31.0-DEV"
+                          },
+                          {
+                            "ip": "10.0.0.2",
+                            "last_seen": 1411996332123,
+                            "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36"
+                          }
+                        ]
+                      }
+                    ]
+                  }
+                }
+              }
+          schema:
+            type: object
+            properties:
+              user_id:
+                type: string
+                description: The Matrix user ID of the user.
+              devices:
+                type: object
+                description: |-
+                  Each key is an identitfier for one of the user's devices.
+                additionalProperties:
+                  type: object
+                  title: DeviceInfo
+                  properties:
+                    sessions:
+                      type: array
+                      description: A user's sessions (i.e. what they did with an access token from one login).
+                      items:
+                        type: object
+                        title: SessionInfo
+                        properties:
+                          connections:
+                            type: array
+                            description: Information particular connections in the session.
+                            items:
+                              type: object
+                              title: ConnectionInfo
+                              properties:
+                                ip:
+                                  type: string
+                                  description: Most recently seen IP address of the session.
+                                last_seen:
+                                  type: number
+                                  description: Unix timestamp that the session was last active.
+                                user_agent:
+                                  type: string
+                                  description: User agent string last seen in the session.
+      tags:
+        - Server administration

api/client-server/administrative_contact.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Account Administrative Contact API"
+  title: "Matrix Client-Server Account Administrative Contact API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/v2_alpha
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -25,7 +25,7 @@ paths:
         This API endpoint uses the User-Interactive Authentication API.
         An access token should be submitted to this endpoint if the client has
         an active session.
-        The Home Server may change the flows available depending on whether a
+        The homeserver may change the flows available depending on whether a
         valid access token is provided.
       security:
         - accessToken: []
@@ -54,6 +54,8 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - User data
   "/account/3pid":
     get:
       summary: Gets a list of a user's third party identifiers.
@@ -64,7 +66,7 @@ paths:
         This is *not* the same as the list of third party identifiers bound to
         the user's Matrix ID in Identity Servers.
 
-        Identifiers in this list may be used by the Home Server as, for example,
+        Identifiers in this list may be used by the homeserver as, for example,
         identifiers that it will accept to reset the user's account password.
       security:
         - accessToken: []
@@ -97,6 +99,8 @@ paths:
                     address:
                       type: string
                       description: The third party identifier address.
+      tags:
+        - User data
     post:
       summary: Adds contact information to the user's account.
       description: Adds contact information to the user's account.
@@ -155,3 +159,5 @@ paths:
                 "errcode": "M_THREEPID_AUTH_FAILED",
                 "error": "The third party credentials could not be verified by the identity server."
               }
+      tags:
+        - User data

api/client-server/banning.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Room Banning API"
+  title: "Matrix Client-Server Room Banning API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -74,3 +74,5 @@ paths:
                 "errcode": "M_FORBIDDEN",
                 "error": "You do not have a high enough power level to ban from this room."
               }
+      tags:
+        - Room membership

api/client-server/content-repo.yaml

@@ -1,11 +1,11 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Content Repository API"
+  title: "Matrix Client-Server Content Repository API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
-basePath: /_matrix/media/v1
+basePath: /_matrix/media/%CLIENT_MAJOR_VERSION%
 produces:
   - application/json
   - "*/*"
@@ -43,6 +43,8 @@ paths:
               {
                 "content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
               }
+      tags:
+        - Media
   "/download/{serverName}/{mediaId}":
     get:
       summary: "Download content from the content repository."
@@ -74,6 +76,8 @@ paths:
               type: "string"
           schema:
             type: file
+      tags:
+        - Media
   "/thumbnail/{serverName}/{mediaId}":
     get:
       summary: "Download a thumbnail of the content from the content repository."
@@ -123,5 +127,5 @@ paths:
               enum: ["image/jpeg", "image/png"]
           schema:
             type: file
-            
+      tags:
-
+        - Media

api/client-server/create_room.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Room Creation API"
+  title: "Matrix Client-Server Room Creation API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -146,3 +146,5 @@ paths:
         400:
           description: >
             The request body is malformed or the room alias specified is already taken.
+      tags:
+        - Room creation

api/client-server/definitions/event.json

@@ -1,53 +0,0 @@
-{
-  "type": "object",
-  "title": "Event",
-  "properties": {
-    "content": {
-      "type": "object",
-      "title": "EventContent",
-      "description": "The content of this event. The fields in this object will vary depending on the type of event."
-    },
-    "origin_server_ts": {
-      "type": "integer",
-      "format": "int64",
-      "description": "Timestamp in milliseconds on originating homeserver when this event was sent."
-    },
-    "sender": {
-      "type": "string",
-      "description": "The MXID of the user who sent this event."
-    },
-    "state_key": {
-      "type": "string",
-      "description": "Optional. This key will only be present for state events. A unique key which defines the overwriting semantics for this piece of room state."
-    },
-    "type": {
-      "type": "string",
-      "description": "The type of event."
-    },
-    "unsigned": {
-      "type": "object",
-      "title": "Unsigned",
-      "description": "Information about this event which was not sent by the originating homeserver",
-      "properties": {
-        "age": {
-          "type": "integer",
-          "format": "int64",
-          "description": "Time in milliseconds since the event was sent."
-        },
-        "prev_content": {
-          "title": "EventContent",
-          "type": "object",
-          "description": "Optional. The previous ``content`` for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there is no previous content, this key will be missing."
-        },
-        "replaces_state": {
-          "type": "string",
-          "description": "Optional. The event_id of the previous event for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there is no previous content, this key will be missing."
-        },
-        "transaction_id": {
-          "type": "string",
-          "description": "Optional. The transaction ID set when this message was sent. This key will only be present for message events sent by the device calling this API."
-        }
-      }
-    }
-  }
-}

api/client-server/definitions/event.yaml

@@ -0,0 +1,45 @@
+properties:
+  content:
+    description: The content of this event. The fields in this object will vary depending
+      on the type of event.
+    title: EventContent
+    type: object
+  origin_server_ts:
+    description: Timestamp in milliseconds on originating homeserver when this event
+      was sent.
+    format: int64
+    type: integer
+  sender:
+    description: The MXID of the user who sent this event.
+    type: string
+  state_key:
+    description: Optional. This key will only be present for state events. A unique
+      key which defines the overwriting semantics for this piece of room state.
+    type: string
+  type:
+    description: The type of event.
+    type: string
+  unsigned:
+    description: Information about this event which was not sent by the originating
+      homeserver
+    properties:
+      age:
+        description: Time in milliseconds since the event was sent.
+        format: int64
+        type: integer
+      prev_content:
+        description: Optional. The previous ``content`` for this state. This will
+          be present only for state events appearing in the ``timeline``. If this
+          is not a state event, or there is no previous content, this key will be
+          missing.
+        title: EventContent
+        type: object
+      transaction_id:
+        description: Optional. The transaction ID set when this message was sent.
+          This key will only be present for message events sent by the device calling
+          this API.
+        type: string
+    title: Unsigned
+    type: object
+title: Event
+type: object

api/client-server/definitions/event_batch.json

@@ -1,13 +0,0 @@
-{
-  "type": "object",
-  "properties": {
-    "events": {
-      "type": "array",
-      "description": "List of events",
-      "items": {
-        "type": "object",
-        "allOf": [{"$ref": "event.json" }]
-      }
-    }
-  }
-}

api/client-server/definitions/event_batch.yaml

@@ -0,0 +1,9 @@
+properties:
+  events:
+    description: List of events
+    items:
+      allOf:
+      - $ref: event.yaml
+      type: object
+    type: array
+type: object

api/client-server/definitions/event_filter.json

@@ -1,42 +0,0 @@
-{
-  "type": "object",
-  "properties": {
-    "limit": {
-      "type": "integer",
-      "description":
-        "The maximum number of events to return."
-    },
-    "types": {
-      "type": "array",
-      "description":
-        "A list of event types to include. If this list is absent then all event types are included. A '*' can be used as a wildcard to match any sequence of characters.",
-      "items": {
-        "type": "string"
-      }
-    },
-    "not_types": {
-      "type": "array",
-      "description":
-        "A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the 'types' filter. A '*' can be used as a wildcard to match any sequence of characters.",
-      "items": {
-        "type": "string"
-      }
-    },
-    "senders": {
-      "type": "array",
-      "description":
-        "A list of senders IDs to include. If this list is absent then all senders are included. A '*' can be used as a wildcard to match any sequence of characters.",
-      "items": {
-        "type": "string"
-      }
-    },
-    "not_senders": {
-      "type": "array",
-      "description":
-        "A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the 'senders' filter. A '*' can be used as a wildcard to match any sequence of characters.",
-      "items": {
-        "type": "string"
-      }
-    }
-  }
-}

api/client-server/definitions/event_filter.yaml

@@ -0,0 +1,34 @@
+properties:
+  limit:
+    description: The maximum number of events to return.
+    type: integer
+  not_senders:
+    description: A list of sender IDs to exclude. If this list is absent then no senders
+      are excluded. A matching sender will be excluded even if it is listed in the
+      'senders' filter. A '*' can be used as a wildcard to match any sequence of characters.
+    items:
+      type: string
+    type: array
+  not_types:
+    description: A list of event types to exclude. If this list is absent then no
+      event types are excluded. A matching type will be excluded even if it is listed
+      in the 'types' filter. A '*' can be used as a wildcard to match any sequence
+      of characters.
+    items:
+      type: string
+    type: array
+  senders:
+    description: A list of senders IDs to include. If this list is absent then all
+      senders are included. A '*' can be used as a wildcard to match any sequence
+      of characters.
+    items:
+      type: string
+    type: array
+  types:
+    description: A list of event types to include. If this list is absent then all
+      event types are included. A '*' can be used as a wildcard to match any sequence
+      of characters.
+    items:
+      type: string
+    type: array
+type: object

api/client-server/definitions/push_condition.json

@@ -1,9 +0,0 @@
-{
-  "type": "object", 
-  "properties": {
-    "kind": {
-      "type": "string",
-      "enum": ["event_match", "profile_tag", "contains_display_name", "room_member_count"]
-    }
-  }
-}

api/client-server/definitions/push_condition.yaml

@@ -0,0 +1,9 @@
+properties:
+  kind:
+    enum:
+    - event_match
+    - profile_tag
+    - contains_display_name
+    - room_member_count
+    type: string
+type: object

api/client-server/definitions/push_rule.json

@@ -1,21 +0,0 @@
-{
-  "title": "PushRule",
-  "type": "object", 
-  "properties": {
-    "default": {
-      "type": "boolean"
-    }, 
-    "enabled": {
-      "type": "boolean"
-    }, 
-    "rule_id": {
-      "type": "string"
-    }, 
-    "actions": {
-      "items": {
-        "type": ["object", "string"]
-      }, 
-      "type": "array"
-    }
-  }
-}

api/client-server/definitions/push_rule.yaml

@@ -0,0 +1,15 @@
+properties:
+  actions:
+    items:
+      type:
+      - object
+      - string
+    type: array
+  default:
+    type: boolean
+  enabled:
+    type: boolean
+  rule_id:
+    type: string
+title: PushRule
+type: object

api/client-server/definitions/push_ruleset.json

@@ -1,65 +0,0 @@
-{
-  "type": "object",
-  "properties": {
-    "content": {
-      "items": {
-        "type": "object",
-        "title": "PushRule",
-        "allOf": [
-          {
-            "$ref": "push_rule.json"
-          }
-        ]
-      },
-      "type": "array"
-    },
-    "override": {
-      "items": {
-        "type": "object",
-        "title": "PushRule",
-        "allOf": [
-          {
-            "$ref": "push_rule.json"
-          }
-        ]
-      },
-      "type": "array"
-    },
-    "sender": {
-      "items": {
-        "type": "object",
-        "title": "PushRule",
-        "allOf": [
-          {
-            "$ref": "push_rule.json"
-          }
-        ]
-      },
-      "type": "array"
-    },
-    "underride": {
-      "items": {
-        "type": "object",
-        "title": "PushRule",
-        "allOf": [
-          {
-            "$ref": "push_rule.json"
-          }
-        ]
-      },
-      "type": "array"
-    },
-    "room": {
-      "items": {
-        "type": "object",
-        "title": "PushRule",
-        "allOf": [
-          {
-            "$ref": "push_rule.json"
-          }
-        ]
-      },
-      "type": "array"
-    }
-  }
-}

api/client-server/definitions/push_ruleset.yaml

@@ -0,0 +1,37 @@
+properties:
+  content:
+    items:
+      allOf:
+      - $ref: push_rule.yaml
+      title: PushRule
+      type: object
+    type: array
+  override:
+    items:
+      allOf:
+      - $ref: push_rule.yaml
+      title: PushRule
+      type: object
+    type: array
+  room:
+    items:
+      allOf:
+      - $ref: push_rule.yaml
+      title: PushRule
+      type: object
+    type: array
+  sender:
+    items:
+      allOf:
+      - $ref: push_rule.yaml
+      title: PushRule
+      type: object
+    type: array
+  underride:
+    items:
+      allOf:
+      - $ref: push_rule.yaml
+      title: PushRule
+      type: object
+    type: array
+type: object

api/client-server/definitions/room_event_filter.json

@@ -1,22 +0,0 @@
-{
-  "type": "object",
-  "allOf": [{"$ref": "event_filter.json"}],
-  "properties": {
-    "rooms": {
-      "type": "array",
-      "description":
-        "A list of room IDs to include. If this list is absent then all rooms are included. A '*' can be used as a wildcard to match any sequence of characters.",
-      "items": {
-        "type": "string"
-      }
-    },
-    "not_rooms": {
-      "type": "array",
-      "description":
-        "A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the 'rooms' filter. A '*' can be used as a wildcard to match any sequence of characters.",
-      "items": {
-        "type": "string"
-      }
-    }
-  }
-}

api/client-server/definitions/room_event_filter.yaml

@@ -0,0 +1,17 @@
+allOf:
+- $ref: event_filter.yaml
+properties:
+  not_rooms:
+    description: A list of room IDs to exclude. If this list is absent then no rooms
+      are excluded. A matching room will be excluded even if it is listed in the 'rooms'
+      filter. A '*' can be used as a wildcard to match any sequence of characters.
+    items:
+      type: string
+    type: array
+  rooms:
+    description: A list of room IDs to include. If this list is absent then all rooms
+      are included. A '*' can be used as a wildcard to match any sequence of characters.
+    items:
+      type: string
+    type: array
+type: object

api/client-server/definitions/sync_filter.json

@@ -1,44 +0,0 @@
-{
-  "type": "object",
-  "properties": {
-    "room": {
-      "type": "object",
-      "properties": {
-        "state": {
-          "description":
-            "The state events to include for rooms.",
-          "allOf": [{"$ref": "room_event_filter.json"}]
-        },
-        "timeline": {
-          "description":
-            "The message and state update events to include for rooms.",
-          "allOf": [{"$ref": "room_event_filter.json"}]
-        },
-        "ephemeral": {
-          "description":
-            "The events that aren't recorded in the room history, e.g. typing and receipts, to include for rooms.",
-          "allOf": [{"$ref": "room_event_filter.json"}]
-        }
-      }
-    },
-    "presence": {
-      "description":
-        "The presence updates to include.",
-      "allOf": [{"$ref": "event_filter.json"}]
-    },
-    "event_format": {
-      "description":
-        "The format to use for events. 'client' will return the events in a format suitable for clients. 'federation' will return the raw event as receieved over federation. The default is 'client'.",
-      "type": "string",
-      "enum": ["client", "federation"]
-    },
-    "event_fields": {
-      "type": "array",
-      "description":
-        "List of event fields to include. If this list is absent then all fields are included. The entries may include '.' charaters to indicate sub-fields. So ['content.body'] will include the 'body' field of the 'content' object. A literal '.' character in a field name may be escaped using a '\\'. A server may include more fields than were requested.",
-      "items": {
-        "type": "string"
-      }
-    }
-  }
-}

api/client-server/definitions/sync_filter.yaml

@@ -0,0 +1,42 @@
+properties:
+  event_fields:
+    description: List of event fields to include. If this list is absent then all
+      fields are included. The entries may include '.' charaters to indicate sub-fields.
+      So ['content.body'] will include the 'body' field of the 'content' object. A
+      literal '.' character in a field name may be escaped using a '\'. A server may
+      include more fields than were requested.
+    items:
+      type: string
+    type: array
+  event_format:
+    description: The format to use for events. 'client' will return the events in
+      a format suitable for clients. 'federation' will return the raw event as receieved
+      over federation. The default is 'client'.
+    enum:
+    - client
+    - federation
+    type: string
+  presence:
+    allOf:
+    - $ref: event_filter.yaml
+    description: The presence updates to include.
+  room:
+    properties:
+      ephemeral:
+        allOf:
+        - $ref: room_event_filter.yaml
+        description: The events that aren't recorded in the room history, e.g. typing
+          and receipts, to include for rooms.
+      include_leave:
+        description: Include rooms that the user has left in the sync, default false
+        type: boolean
+      state:
+        allOf:
+        - $ref: room_event_filter.yaml
+        description: The state events to include for rooms.
+      timeline:
+        allOf:
+        - $ref: room_event_filter.yaml
+        description: The message and state update events to include for rooms.
+    type: object
+type: object

api/client-server/definitions/timeline_batch.json

@@ -1,14 +0,0 @@
-{
-  "type": "object",
-  "allOf": [{"$ref":"event_batch.json"}],
-  "properties": {
-    "limited": {
-      "type": "boolean",
-      "description": "True if the number of events returned was limited by the ``limit`` on the filter"
-    },
-    "prev_batch": {
-      "type": "string",
-      "description": "If the batch was limited then this is a token that can be supplied to the server to retrieve earlier events"
-    }
-  }
-}

api/client-server/definitions/timeline_batch.yaml

@@ -0,0 +1,12 @@
+allOf:
+- $ref: event_batch.yaml
+properties:
+  limited:
+    description: True if the number of events returned was limited by the ``limit``
+      on the filter
+    type: boolean
+  prev_batch:
+    description: If the batch was limited then this is a token that can be supplied
+      to the server to retrieve earlier events
+    type: string
+type: object

api/client-server/directory.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Directory API"
+  title: "Matrix Client-Server Directory API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1/directory
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%/directory
 consumes:
   - application/json
 produces:
@@ -52,6 +52,8 @@ paths:
               {}
           schema:
             type: object
+      tags:
+        - Room directory
     get:
       summary: Get the room ID corresponding to this room alias.
       parameters:
@@ -102,6 +104,8 @@ paths:
                 "errcode": "M_UNKNOWN",
                 "error": "Room alias #monkeys:matrix.org already exists."
               }
+      tags:
+        - Room directory
     delete:
       summary: Remove a mapping of room alias to room ID.
       description: |-
@@ -125,3 +129,5 @@ paths:
               {}
           schema:
             type: object
+      tags:
+        - Room directory

api/client-server/filter.yaml

@@ -1,11 +1,11 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v2 filter API"
+  title: "Matrix Client-Server filter API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
-basePath: /_matrix/client/v2_alpha
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -22,8 +22,8 @@ paths:
       summary: Upload a new filter.
       description: |-
         Uploads a new filter definition to the homeserver.
-        Returns a filter ID that may be used in /sync requests to
+        Returns a filter ID that may be used in future requests to
-        retrict which events are returned to the client.
+        restrict which events are returned to the client.
       security:
         - accessToken: []
       parameters:
@@ -42,7 +42,7 @@ paths:
           schema:
             type: object
             allOf:
-              - $ref: "definitions/sync_filter.json"
+              - $ref: "definitions/sync_filter.yaml"
             example: |-
               {
                 "room": {
@@ -84,6 +84,8 @@ paths:
                 type: string
                 description: |-
                   The ID of the filter that was created.
+      tags:
+        - Room participation
   "/user/{userId}/filter/{filterId}":
     get:
       summary: Download a filter
@@ -136,4 +138,6 @@ paths:
           schema:
             type: object
             allOf:
-              - $ref: "definitions/sync_filter.json"
+              - $ref: "definitions/sync_filter.yaml"
+      tags:
+        - Room participation

api/client-server/guest_events.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Sync Guest API"
+  title: "Matrix Client-Server Sync Guest API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -74,7 +74,7 @@ paths:
                     "origin_server_ts": 1432804485886,
                     "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                     "type": "m.room.message",
-                    "user_id": "@bob:localhost"
+                    "sender": "@bob:localhost"
                   }
                 ]
               }
@@ -98,6 +98,7 @@ paths:
                   type: object
                   title: Event
                   allOf:
-                    - "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
+                    - "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
         400:
           description: "Bad pagination ``from`` parameter."
+        # No tags to exclude this from the swagger UI - use the non-guest version instead.

api/client-server/inviting.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Room Joining API"
+  title: "Matrix Client-Server Room Joining API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -88,3 +88,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Room membership

api/client-server/joining.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Room Inviting API"
+  title: "Matrix Client-Server Room Inviting API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -63,6 +63,8 @@ paths:
           schema:
             "$ref": "definitions/error.yaml"
       x-alias:
-        canonical-link: "post-matrix-client-api-v1-rooms-roomid-join"
+        canonical-link: "post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-join"
         aliases:
-          - /_matrix/client/api/v1/join/{roomId}
+          - /_matrix/client/%CLIENT_MAJOR_VERSION%/join/{roomId}
+      tags:
+        - Room membership

api/client-server/leaving.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Room Leaving API"
+  title: "Matrix Client-Server Room Leaving API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -55,6 +55,8 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Room membership
   "/rooms/{roomId}/forget":
     post:
       summary: Stop the requesting user remembering about a particular room.
@@ -90,3 +92,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Room membership

api/client-server/list_public_rooms.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Room Creation API"
+  title: "Matrix Client-Server Room Creation API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -95,3 +95,5 @@ paths:
         400:
           description: >
             The request body is malformed or the room alias specified is already taken.
+      tags:
+        - Room discovery

api/client-server/login.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Registration and Login API"
+  title: "Matrix Client-Server Registration and Login API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -81,7 +81,7 @@ paths:
                   (optional) A ``refresh_token`` may be exchanged for a new ``access_token`` using the /tokenrefresh API endpoint.
               home_server:
                 type: string
-                description: The hostname of the Home Server on which the account has been registered.
+                description: The hostname of the homeserver on which the account has been registered.
         400:
           description: |-
             Part of the request was invalid. For example, the login type may not be recognised.
@@ -101,6 +101,8 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Session management
   "/tokenrefresh":
     post:
       summary: Exchanges a refresh token for an access token.
@@ -158,3 +160,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Session management

api/client-server/message_pagination.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Rooms API"
+  title: "Matrix Client-Server Rooms API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -129,3 +129,5 @@ paths:
         403:
           description: >
             You aren't a member of the room.
+      tags:
+        - Room participation

api/client-server/old_sync.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Sync API"
+  title: "Matrix Client-Server Sync API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -60,7 +60,7 @@ paths:
                     "origin_server_ts": 1432804485886,
                     "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                     "type": "m.room.message",
-                    "user_id": "@bob:localhost"
+                    "sender": "@bob:localhost"
                   }
                 ]
               }
@@ -84,9 +84,11 @@ paths:
                   type: object
                   title: Event
                   allOf:
-                    - "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
+                    - "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
         400:
           description: "Bad pagination ``from`` parameter."
+      tags:
+        - Room participation
   "/initialSync":
     get:
       summary: Get the user's current state.
@@ -154,7 +156,7 @@ paths:
                                       "origin_server_ts": 1432804485886,
                                       "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                                       "type": "m.room.message",
-                                      "user_id": "@alice:localhost"
+                                      "sender": "@alice:localhost"
                                   },
                                   {
                                       "age": 343511809,
@@ -166,7 +168,7 @@ paths:
                                       "origin_server_ts": 1432804487480,
                                       "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                                       "type": "m.room.message",
-                                      "user_id": "@bob:localhost"
+                                      "sender": "@bob:localhost"
                                   }
                               ],
                               "end": "s3456_9_0",
@@ -184,13 +186,12 @@ paths:
                                   "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                                   "state_key": "",
                                   "type": "m.room.join_rules",
-                                  "user_id": "@alice:localhost"
+                                  "sender": "@alice:localhost"
                               },
                               {
                                   "age": 6547561012,
                                   "content": {
                                       "avatar_url": "mxc://localhost/fzysBrHpPEeTGANCVLXWXNMI#auto",
-                                      "displayname": null,
                                       "membership": "join"
                                   },
                                   "event_id": "$1426600438280zExKY:localhost",
@@ -199,7 +200,7 @@ paths:
                                   "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                                   "state_key": "@alice:localhost",
                                   "type": "m.room.member",
-                                  "user_id": "@alice:localhost"
+                                  "sender": "@alice:localhost"
                               },
                               {
                                   "age": 7148267200,
@@ -211,7 +212,7 @@ paths:
                                   "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                                   "state_key": "",
                                   "type": "m.room.create",
-                                  "user_id": "@alice:localhost"
+                                  "sender": "@alice:localhost"
                               },
                               {
                                   "age": 1622568720,
@@ -226,7 +227,7 @@ paths:
                                   "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                                   "state_key": "@bob:localhost",
                                   "type": "m.room.member",
-                                  "user_id": "@bob:localhost"
+                                  "sender": "@bob:localhost"
                               },
                               {
                                   "age": 7148267004,
@@ -250,7 +251,7 @@ paths:
                                   "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                                   "state_key": "",
                                   "type": "m.room.power_levels",
-                                  "user_id": "@alice:localhost"
+                                  "sender": "@alice:localhost"
                               }
                           ],
                           "visibility": "private",
@@ -285,7 +286,7 @@ paths:
                   type: object
                   title: Event
                   allOf:
-                    - "$ref": "../../event-schemas/schema/core-event-schema/event.json"
+                    - "$ref": "../../event-schemas/schema/core-event-schema/event.yaml"
               rooms:
                 type: array
                 items:
@@ -332,7 +333,7 @@ paths:
                             type: object
                             title: RoomEvent
                             allOf:
-                              - "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
+                              - "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
                       required: ["start", "end", "chunk"]
                     state:
                       type: array
@@ -345,7 +346,7 @@ paths:
                         title: StateEvent
                         type: object
                         allOf:
-                          - "$ref": "../../event-schemas/schema/core-event-schema/state_event.json"
+                          - "$ref": "../../event-schemas/schema/core-event-schema/state_event.yaml"
                     visibility:
                       type: string
                       enum: ["private", "public"]
@@ -361,11 +362,13 @@ paths:
                         title: Event
                         type: object
                         allOf:
-                          - "$ref": "../../event-schemas/schema/core-event-schema/event.json"
+                          - "$ref": "../../event-schemas/schema/core-event-schema/event.yaml"
                   required: ["room_id", "membership"]
             required: ["end", "rooms", "presence"]
         404:
           description: There is no avatar URL for this user or this user does not exist.
+      tags:
+        - Room participation
   "/events/{eventId}":
     get:
       summary: Get a single event by event ID.
@@ -392,12 +395,14 @@ paths:
                   "msgtype": "m.text"
                 },
                 "room_id:": "!wfgy43Sg4a:matrix.org",
-                "user_id": "@bob:matrix.org",
+                "sender": "@bob:matrix.org",
                 "event_id": "$asfDuShaf7Gafaw:matrix.org",
                 "type": "m.room.message"
               }
           schema:
             allOf:
-              - "$ref": "../../event-schemas/schema/core-event-schema/event.json"
+              - "$ref": "../../event-schemas/schema/core-event-schema/event.yaml"
         404:
           description: The event was not found or you do not have permission to read this event.
+      tags:
+        - Room participation

api/client-server/presence.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Presence API"
+  title: "Matrix Client-Server Presence API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -67,6 +67,8 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Presence
     get:
       summary: Get this user's presence state.
       description: |-
@@ -85,8 +87,7 @@ paths:
             application/json: |-
               {
                 "presence": "unavailable",
-                "last_active_ago": 420845,
+                "last_active_ago": 420845
-                "status_msg": null
               }
           schema:
             type: object
@@ -107,6 +108,8 @@ paths:
           description: |-
             There is no presence state for this user. This user may not exist or
             isn't exposing presence information to you.
+      tags:
+        - Presence
   "/presence/list/{userId}":
     post:
       summary: Add or remove users from this presence list.
@@ -161,6 +164,8 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Presence
     get:
       summary: Get presence events for this presence list.
       description: |-
@@ -205,4 +210,6 @@ paths:
               type: object
               title: PresenceEvent
               allOf:
-                - "$ref": "../../event-schemas/schema/core-event-schema/event.json"
+                - "$ref": "../../event-schemas/schema/core-event-schema/event.yaml"
+      tags:
+        - Presence

api/client-server/profile.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Profile API"
+  title: "Matrix Client-Server Profile API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -59,6 +59,8 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - User data
     get:
       summary: Get the user's display name.
       description: |-
@@ -88,6 +90,8 @@ paths:
                 description: The user's display name if they have set one.
         404:
           description: There is no display name for this user or this user does not exist.
+      tags:
+        - User data
   "/profile/{userId}/avatar_url":
     put:
       summary: Set the user's avatar URL.
@@ -129,6 +133,8 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - User data
     get:
       summary: Get the user's avatar URL.
       description: |-
@@ -158,6 +164,8 @@ paths:
                 description: The user's avatar URL if they have set one.
         404:
           description: There is no avatar URL for this user or this user does not exist.
+      tags:
+        - User data
   "/profile/{userId}":
     get:
       summary: Get this user's profile information.
@@ -193,3 +201,5 @@ paths:
                 description: The user's display name if they have set one.
         404:
           description: There is no profile information for this user or this user does not exist.
+      tags:
+        - User data

api/client-server/push_notifier.yaml

@@ -6,7 +6,7 @@ host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/push/v1
+basePath: /_matrix/push/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -189,4 +189,5 @@ paths:
                 items:
                   type: string
                   description: A pushkey
-
+      tags:
+        - Push notifications

api/client-server/pusher.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Push API"
+  title: "Matrix Client-Server Push API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -60,7 +60,6 @@ paths:
                   Max length, 512 bytes.
               kind:
                 type: string
-                enum: ["http", null]
                 description: |-
                   The kind of pusher to configure. ``"http"`` makes a pusher that
                   sends HTTP pokes. ``null`` deletes the pusher.
@@ -114,7 +113,7 @@ paths:
                 description: |-
                   If true, the homeserver should add another pusher with the
                   given pushkey and App ID in addition to any others with
-                  different user IDs. Otherwise, the Home Server must remove any
+                  different user IDs. Otherwise, the homeserver must remove any
                   other pushers with the same App ID and pushkey for different
                   users. The default is ``false``.
             required: ['profile_tag', 'kind', 'app_id', 'app_display_name',
@@ -141,4 +140,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
-
+      tags:
+        - Push notifications

api/client-server/pushrules.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Push Rules API"
+  title: "Matrix Client-Server Push Rules API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -45,14 +45,14 @@ paths:
                     description: The ruleset for this profile tag.
                     title: Ruleset
                     allOf: [
-                      "$ref": "definitions/push_ruleset.json"
+                      "$ref": "definitions/push_ruleset.yaml"
                     ]
               global:
                 type: object
                 description: The global ruleset.
                 title: Ruleset
                 allOf: [
-                  "$ref": "definitions/push_ruleset.json"
+                  "$ref": "definitions/push_ruleset.yaml"
                 ]
           examples:
             application/json: |-
@@ -245,6 +245,8 @@ paths:
                     ]
                 }
               }
+      tags:
+        - Push notifications
   "/pushrules/{scope}/{kind}/{ruleId}":
     get:
       summary: Retrieve a push rule.
@@ -295,8 +297,10 @@ paths:
             description: The push rule.
             title: PushRule
             allOf: [
-              "$ref": "definitions/push_rule.json"
+              "$ref": "definitions/push_rule.yaml"
             ]
+      tags:
+        - Push notifications
     delete:
       summary: Delete a push rule.
       description: |-
@@ -335,6 +339,8 @@ paths:
               {}
           schema:
             type: object  # empty json object
+      tags:
+        - Push notifications
     put:
       summary: Add or change a push rule.
       description: |-
@@ -414,7 +420,7 @@ paths:
                 items:
                   type: object
                   title: conditions
-                  allOf: [ "$ref": "definitions/push_condition.json" ]
+                  allOf: [ "$ref": "definitions/push_condition.yaml" ]
             required: ["actions"]
       responses:
         200:
@@ -438,6 +444,8 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Push notifications
   "/pushrules/{scope}/{kind}/{ruleId}/enabled":
     put:
       summary: "Enable or disable a push rule."
@@ -470,14 +478,21 @@ paths:
           description: |
             The identifier for the rule.
         - in: body
-          name: <body>
+          name: body
           description: |
             Whether the push rule is enabled or not.
           required: true
           schema:
+            type: object
+            properties:
+              enabled:
                 type: boolean
+                description: Whether the push rule is enabled or not.
+            required: ["enabled"]
             example: |-
-              true
+              {
+                "enabled": true
+              }
       responses:
         200:
           description: The push rule was enabled or disabled.
@@ -485,4 +500,6 @@ paths:
             application/json: |-
               {}
           schema:
-            type: object  # empty json object
+            type: object
+      tags:
+        - Push notifications

api/client-server/receipts.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v2 Receipts API"
+  title: "Matrix Client-Server Receipts API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/v2_alpha
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -67,3 +67,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Room participation

api/client-server/redaction.yaml

@@ -0,0 +1,84 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server message redaction API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/api/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+paths:
+  "/rooms/{roomId}/redact/{eventId}/{txnId}":
+    put:
+      summary: Strips all non-integrity-critical information out of an event.
+      description: |-
+        Strips all information out of an event which isn't critical to the
+        integrity of the server-side representation of the room.
+
+        This cannot be undone.
+
+        Users may redact their own events, and any user with a power level
+        greater than or equal to the `redact` power level of the room may
+        redact events there.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room from which to redact the event.
+          required: true
+          x-example: "!637q39766251:example.com"
+        - in: path
+          type: string
+          name: eventId
+          description: The ID of the event to redact
+          required: true
+          x-example: "bai2b1i9:matrix.org"
+        - in: path
+          name: txnId
+          type: string
+          description: |-
+            The transaction ID for this event. Clients should generate a
+            unique ID; it will be used by the server to ensure idempotency of requests.
+          required: true
+          x-example: "37"
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: |-
+              {
+                "reason": "Indecent material"
+              }
+            properties:
+              reason:
+                type: string
+                description: The reason for the event being redacted.
+      responses:
+        200:
+          description: "An ID for the redaction event."
+          examples:
+            application/json: |-
+              {
+                  "event_id": "YUwQidLecu"
+              }
+          schema:
+            type: object
+            properties:
+              event_id:
+                type: string
+                description: |-
+                  A unique identifier for the event.
+      tags:
+        - Room participation

api/client-server/registration.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v2 Registration API"
+  title: "Matrix Client-Server Registration API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v2_alpha
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -94,7 +94,7 @@ paths:
                   (optional) A ``refresh_token`` may be exchanged for a new ``access_token`` using the /tokenrefresh API endpoint.
               home_server:
                 type: string
-                description: The hostname of the Home Server on which the account has been registered.
+                description: The hostname of the homeserver on which the account has been registered.
         400:
           description: |-
             Part of the request was invalid. This may include one of the following error codes:
@@ -107,7 +107,7 @@ paths:
             including after authentication if the requested user ID was registered
             whilst the client was performing authentication.
 
-            Home Servers MUST perform the relevant checks and return these codes before
+            Homeservers MUST perform the relevant checks and return these codes before
             performing `User-Interactive Authentication`_, although they may also return
             them after authentication is completed if, for example, the requested user ID
             was registered whilst the client was performing authentication.
@@ -121,3 +121,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - User data

api/client-server/room_send.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 message event send API"
+  title: "Matrix Client-Server message event send API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -76,3 +76,5 @@ paths:
                 type: string
                 description: |-
                   A unique identifier for the event.
+      tags:
+        - Room participation

api/client-server/room_state.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 state event send API"
+  title: "Matrix Client-Server state event send API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -20,12 +20,12 @@ securityDefinitions:
 paths:
   "/rooms/{roomId}/state/{eventType}/{stateKey}":
     put:
-      summary: Send a message event to the given room.
+      summary: Send a state event to the given room.
       description: |
-        State events can be sent using this endpoint.  These events will be
+        State events can be sent using this endpoint. This endpoint is
-        overwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all
+        equivalent to calling `/rooms/{roomId}/state/{eventType}/{stateKey}`
-        match.  If the state event has an empty ``state_key``, it can be
+        with an empty `stateKey`. Previous state events with matching
-        omitted from the path.
+        `<roomId>` and `<eventType>`, and empty `<stateKey>`, will be overwritten.
 
         Requests to this endpoint **cannot use transaction IDs**
         like other ``PUT`` paths because they cannot be differentiated from the
@@ -78,3 +78,60 @@ paths:
                 type: string
                 description: |-
                   A unique identifier for the event.
+      tags:
+        - Room participation
+  "/rooms/{roomId}/state/{eventType}":
+    put:
+      summary: Send a state event to the given room.
+      description: |
+        State events can be sent using this endpoint.  These events will be
+        overwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all
+        match. This endpoint forces the state key to be the empty string.
+
+        Requests to this endpoint **cannot use transaction IDs**
+        like other ``PUT`` paths because they cannot be differentiated from the
+        ``state_key``. Furthermore, ``POST`` is unsupported on state paths.
+
+        The body of the request should be the content object of the event; the
+        fields in this object will vary depending on the type of event. See
+        `Room Events`_ for the ``m.`` event specification.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room to set the state in
+          required: true
+          x-example: "!636q39766251:example.com"
+        - in: path
+          type: string
+          name: eventType
+          description: The type of event to send.
+          required: true
+          x-example: "m.room.name"
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: |-
+              {
+                  "name": "New name for the room"
+              }
+      responses:
+        200:
+          description: "An ID for the sent event."
+          examples:
+            application/json: |-
+              {
+                  "event_id": "YUwRidLecu"
+              }
+          schema:
+            type: object
+            properties:
+              event_id:
+                type: string
+                description: |-
+                  A unique identifier for the event.
+      tags:
+        - Room participation

api/client-server/rooms.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Rooms API"
+  title: "Matrix Client-Server Rooms API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -44,7 +44,7 @@ paths:
         - in: path
           type: string
           name: stateKey
-          description: The key of the state to look up. Defaults to the empty string.
+          description: The key of the state to look up.
           required: true
           x-example: ""
       responses:
@@ -61,7 +61,49 @@ paths:
           description: >
             You aren't a member of the room and weren't previously a
             member of the room.
+      tags:
+        - Room participation
+  "/rooms/{roomId}/state/{eventType}":
+    get:
+      summary: Get the state identified by the type, with the empty state key.
+      description: |-
+        Looks up the contents of a state event in a room. If the user is
+        joined to the room then the state is taken from the current
+        state of the room. If the user has left the room then the state is
+        taken from the state of the room when they left.
 
+        This looks up the state event with the empty state key.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room to look up the state in.
+          required: true
+          x-example: "!636q39766251:example.com"
+        - in: path
+          type: string
+          name: eventType
+          description: The type of state to look up.
+          required: true
+          x-example: "m.room.name"
+      responses:
+        200:
+          description: The content of the state event.
+          examples:
+            application/json: |-
+              {"name": "Example room name"}
+          schema:
+            type: object
+        404:
+          description: The room has no state with the given type or key.
+        403:
+          description: >
+            You aren't a member of the room and weren't previously a
+            member of the room.
+      tags:
+        - Room participation
   "/rooms/{roomId}/state":
     get:
       summary: Get all state events in the current state of a room.
@@ -92,13 +134,12 @@ paths:
                     "room_id": "!636q39766251:example.com",
                     "state_key": "",
                     "type": "m.room.join_rules",
-                    "user_id": "@alice:example.com"
+                    "sender": "@alice:example.com"
                 },
                 {
                     "age": 6547561012,
                     "content": {
                         "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
-                        "displayname": null,
                         "membership": "join"
                     },
                     "event_id": "$1426600438280zExKY:example.com",
@@ -107,7 +148,7 @@ paths:
                     "room_id": "!636q39766251:example.com",
                     "state_key": "@alice:example.com",
                     "type": "m.room.member",
-                    "user_id": "@alice:example.com"
+                    "sender": "@alice:example.com"
                 },
                 {
                     "age": 7148267200,
@@ -119,7 +160,7 @@ paths:
                     "room_id": "!636q39766251:example.com",
                     "state_key": "",
                     "type": "m.room.create",
-                    "user_id": "@alice:example.com"
+                    "sender": "@alice:example.com"
                 },
                 {
                     "age": 1622568720,
@@ -134,7 +175,7 @@ paths:
                     "room_id": "!636q39766251:example.com",
                     "state_key": "@bob:example.com",
                     "type": "m.room.member",
-                    "user_id": "@bob:example.com"
+                    "sender": "@bob:example.com"
                 },
                 {
                     "age": 7148267004,
@@ -158,7 +199,7 @@ paths:
                     "room_id": "!636q39766251:example.com",
                     "state_key": "",
                     "type": "m.room.power_levels",
-                    "user_id": "@alice:example.com"
+                    "sender": "@alice:example.com"
                 }
               ]
           schema:
@@ -173,12 +214,13 @@ paths:
               title: StateEvent
               type: object
               allOf:
-                - "$ref": "../../event-schemas/schema/core-event-schema/state_event.json"
+                - "$ref": "../../event-schemas/schema/core-event-schema/state_event.yaml"
         403:
           description: >
             You aren't a member of the room and weren't previously a
             member of the room.
-
+      tags:
+        - Room participation
   "/rooms/{roomId}/initialSync":
     get:
       summary: Snapshot the current state of a room and its most recent messages.
@@ -212,7 +254,7 @@ paths:
                       "origin_server_ts": 1432804485886,
                       "room_id": "!636q39766251:example.com",
                       "type": "m.room.message",
-                      "user_id": "@alice:example.com"
+                      "sender": "@alice:example.com"
                     },
                     {
                       "age": 343511809,
@@ -224,7 +266,7 @@ paths:
                       "origin_server_ts": 1432804487480,
                       "room_id": "!636q39766251:example.com",
                       "type": "m.room.message",
-                      "user_id": "@bob:example.com"
+                      "sender": "@bob:example.com"
                     }
                   ],
                   "end": "s3456_9_0",
@@ -242,13 +284,12 @@ paths:
                     "room_id": "!636q39766251:example.com",
                     "state_key": "",
                     "type": "m.room.join_rules",
-                    "user_id": "@alice:example.com"
+                    "sender": "@alice:example.com"
                   },
                   {
                     "age": 6547561012,
                     "content": {
                       "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
-                      "displayname": null,
                       "membership": "join"
                     },
                     "event_id": "$1426600438280zExKY:example.com",
@@ -257,7 +298,7 @@ paths:
                     "room_id": "!636q39766251:example.com",
                     "state_key": "@alice:example.com",
                     "type": "m.room.member",
-                    "user_id": "@alice:example.com"
+                    "sender": "@alice:example.com"
                   },
                   {
                     "age": 7148267200,
@@ -269,7 +310,7 @@ paths:
                     "room_id": "!636q39766251:example.com",
                     "state_key": "",
                     "type": "m.room.create",
-                    "user_id": "@alice:example.com"
+                    "sender": "@alice:example.com"
                   },
                   {
                     "age": 1622568720,
@@ -284,7 +325,7 @@ paths:
                     "room_id": "!636q39766251:example.com",
                     "state_key": "@bob:example.com",
                     "type": "m.room.member",
-                    "user_id": "@bob:example.com"
+                    "sender": "@bob:example.com"
                   },
                   {
                     "age": 7148267004,
@@ -308,7 +349,7 @@ paths:
                     "room_id": "!636q39766251:example.com",
                     "state_key": "",
                     "type": "m.room.power_levels",
-                    "user_id": "@alice:example.com"
+                    "sender": "@alice:example.com"
                   }
                 ],
                 "visibility": "private",
@@ -355,7 +396,7 @@ paths:
                       type: object
                       title: RoomEvent
                       allOf:
-                        - "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
+                        - "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
                 required: ["start", "end", "chunk"]
               state:
                 type: array
@@ -368,7 +409,7 @@ paths:
                   title: StateEvent
                   type: object
                   allOf:
-                    - "$ref": "../../event-schemas/schema/core-event-schema/state_event.json"
+                    - "$ref": "../../event-schemas/schema/core-event-schema/state_event.yaml"
               visibility:
                 type: string
                 enum: ["private", "public"]
@@ -383,13 +424,14 @@ paths:
                   title: Event
                   type: object
                   allOf:
-                    - "$ref": "../../event-schemas/schema/core-event-schema/event.json"
+                    - "$ref": "../../event-schemas/schema/core-event-schema/event.yaml"
             required: ["room_id"]
         403:
           description: >
             You aren't a member of the room and weren't previously a
             member of the room.
-
+      tags:
+        - Room participation
   "/rooms/{roomId}/members":
     get:
       summary: Get the m.room.member events for the room.
@@ -416,7 +458,6 @@ paths:
                     "age": 6547561012,
                     "content": {
                       "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
-                      "displayname": null,
                       "membership": "join"
                     },
                     "event_id": "$1426600438280zExKY:example.com",
@@ -425,7 +466,7 @@ paths:
                     "room_id": "!636q39766251:example.com",
                     "state_key": "@alice:example.com",
                     "type": "m.room.member",
-                    "user_id": "@alice:example.com"
+                    "sender": "@alice:example.com"
                   },
                   {
                     "age": 1622568720,
@@ -440,7 +481,7 @@ paths:
                     "room_id": "!636q39766251:example.com",
                     "state_key": "@bob:example.com",
                     "type": "m.room.member",
-                    "user_id": "@bob:example.com"
+                    "sender": "@bob:example.com"
                   }
                 ]
               }
@@ -458,4 +499,5 @@ paths:
           description: >
             You aren't a member of the room and weren't previously a
             member of the room.
-
+      tags:
+        - Room participation

api/client-server/search.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Search API"
+  title: "Matrix Client-Server Search API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -74,7 +74,6 @@ paths:
                         type: object
                         title: Filter
                         description: |-
-                            The filter to apply to search results.
                             This has the same format as v2 filter API.
                       order_by:
                         title: "Ordering"
@@ -178,7 +177,7 @@ paths:
                               title: Event
                               description: The event that matched.
                               allOf:
-                                - "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
+                                - "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
                             context:
                               type: object
                               title: Event Context
@@ -218,7 +217,7 @@ paths:
                                     type: object
                                     title: Event
                                     allOf:
-                                      - "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
+                                      - "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
                                 events_after:
                                   type: array
                                   title: Events After
@@ -227,7 +226,7 @@ paths:
                                     type: object
                                     title: Event
                                     allOf:
-                                      - "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
+                                      - "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
                       state:
                         type: object
                         title: Current state
@@ -238,7 +237,7 @@ paths:
                             type: object
                             title: Event
                             allOf:
-                              - "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
+                              - "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
                       groups:
                         type: object
                         title: Groups
@@ -309,7 +308,7 @@ paths:
                             "origin_server_ts": 1444298308034,
                             "room_id": "!qPewotXpIctQySfjSy:localhost",
                             "type": "m.room.message",
-                            "user_id": "@test:localhost"
+                            "sender": "@test:localhost"
                           }
                         }
                       ]
@@ -322,3 +321,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Search

api/client-server/sync.yaml

@@ -1,11 +1,11 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v2 sync API"
+  title: "Matrix Client-Server sync API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
-basePath: /_matrix/client/v2_alpha
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -114,7 +114,7 @@ paths:
                             ``timeline``, if ``since`` is not given, or
                             ``full_state`` is true).
                           allOf:
-                            - $ref: "definitions/event_batch.json"
+                            - $ref: "definitions/event_batch.yaml"
                         timeline:
                           title: Timeline
                           type: object
@@ -122,7 +122,7 @@ paths:
                             The timeline of messages and state changes in the
                             room.
                           allOf:
-                            - $ref: "definitions/timeline_batch.json"
+                            - $ref: "definitions/timeline_batch.yaml"
                         ephemeral:
                           title: Ephemeral
                           type: object
@@ -131,7 +131,7 @@ paths:
                             recorded in the timeline or state of the room.
                             e.g. typing.
                           allOf:
-                            - $ref: "definitions/event_batch.json"
+                            - $ref: "definitions/event_batch.yaml"
                         account_data:
                           title: Account Data
                           type: object
@@ -139,7 +139,7 @@ paths:
                             The private data that this user has attached to
                             this room.
                           allOf:
-                          - $ref: "definitions/event_batch.json"
+                          - $ref: "definitions/event_batch.yaml"
                   invite:
                     title: Invited Rooms
                     type: object
@@ -166,7 +166,7 @@ paths:
                             delta against the archived ``state`` not the
                             ``invite_state``.
                           allOf:
-                            - $ref: "definitions/event_batch.json"
+                            - $ref: "definitions/event_batch.yaml"
                   leave:
                     title: Left rooms
                     type: object
@@ -182,7 +182,7 @@ paths:
                           description: |-
                             The state updates for the room up to the start of the timeline.
                           allOf:
-                            - $ref: "definitions/event_batch.json"
+                            - $ref: "definitions/event_batch.yaml"
                         timeline:
                           title: Timeline
                           type: object
@@ -190,14 +190,14 @@ paths:
                             The timeline of messages and state changes in the
                             room up to the point when the user left.
                           allOf:
-                            - $ref: "definitions/timeline_batch.json"
+                            - $ref: "definitions/timeline_batch.yaml"
               presence:
                 title: Presence
                 type: object
                 description: |-
                   The updates to the presence status of other users.
                 allOf:
-                  - $ref: "definitions/event_batch.json"
+                  - $ref: "definitions/event_batch.yaml"
           examples:
             application/json: |-
               {
@@ -310,3 +310,5 @@ paths:
                   "leave": {}
                 }
               }
+      tags:
+        - Room participation

api/client-server/tags.yaml

@@ -6,7 +6,7 @@ host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/v2_alpha
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -59,6 +59,8 @@ paths:
                   "pinned": {}
                 }
               }
+      tags:
+        - User data
   "/user/{userId}/rooms/{roomId}/tags/{tag}":
     put:
       summary: Add a tag to a room.
@@ -107,6 +109,8 @@ paths:
           examples:
             application/json: |-
               {}
+      tags:
+        - User data
     delete:
       summary: Remove a tag from the room.
       description: |-
@@ -145,3 +149,5 @@ paths:
           examples:
             application/json: |-
               {}
+      tags:
+        - User data

api/client-server/third_party_membership.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Room Membership API for third party identifiers"
+  title: "Matrix Client-Server Room Membership API for third party identifiers"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -121,3 +121,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Room membership

api/client-server/typing.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Typing API"
+  title: "Matrix Client-Server Typing API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -74,4 +74,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
-
+      tags:
+        - Room participation

api/client-server/voip.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Voice over IP API"
+  title: "Matrix Client-Server Voice over IP API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -18,7 +18,7 @@ securityDefinitions:
     name: access_token
     in: query
 paths:
-  "/turnServer":
+  "/voip/turnServer":
     get:
       summary: Obtain TURN server credentials.
       description: |-
@@ -65,4 +65,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
-
+      tags:
+        - VOIP

changelogs/client_server.rst

@@ -0,0 +1,37 @@
+r0
+===
+
+This is the first release of the client-server specification. It is largely a dump of what has currently been implemented, and there are several inconsistencies.
+
+An upcoming minor release will deprecate many of these inconsistencies, and they will be removed in the next major release.
+
+Since the draft stage, the following major changes have been made:
+- /api/v1 and /v2_alpha path segments have been replaced with the major version of the release (i.e. 'r0').
+- Some POST versions of APIs with both POST and PUT have been removed.
+- The specification has been split into one specification per API. This is the client-server API. The server-server API can be found documented separately.
+- All APIs are now documented using Swagger
+- The following modules have been added:
+  - Content repository
+  - Instant messaging
+  - Push notification
+  - History visibility
+  - Search
+  - Invites based on third party identifiers
+  - Room tagging
+  - Guest access
+  - Client config
+- The following APIs were added:
+  - ``/sync``
+  - ``/publicRooms``
+  - ``/rooms/{roomId}/forget``
+  - ``/admin/whois``
+  - ``/rooms/{roomId}/redact``
+  - ``/user/{userId}/filter``
+- The following APIs have been significantly modified:
+  - Invitations now contain partial room state
+  - Invitations can now be rejected
+  - ``/directory``
+- The following events have been added:
+  - ``m.room.avatar``
+- Example signed json is included for reference
+- Commentary on display name calculation was added

drafts/ancient_federated_versioning_design_notes.rst

@@ -1,4 +1,4 @@
-Versioning is, like, hard for backfilling backwards because of the number of Home Servers involved.
+Versioning is, like, hard for backfilling backwards because of the number of homeservers involved.
 
 The way we solve this is by doing versioning as an acyclic directed graph of PDUs. For backfilling purposes, this is done on a per context basis.
 When we send a PDU we include all PDUs that have been received for that context that hasn't been subsequently listed in a later PDU. The trivial case is a simple list of PDUs, e.g. A <- B <- C. However, if two servers send out a PDU at the same to, both B and C would point at A - a later PDU would then list both B and C.

drafts/as-http-api.rst

@@ -13,7 +13,7 @@ Application Services HTTP API
 
 .. sectnum::
 
-Application Service -> Home Server
+Application Service -> Homeserver
 ----------------------------------
 This contains homeserver APIs which are used by the application service.
 
@@ -122,7 +122,7 @@ API called when:
   }
 
 
-Home Server -> Application Service
+Homeserver -> Application Service
 ----------------------------------
 This contains application service APIs which are used by the homeserver.
 

drafts/markjh_end_to_end.rst

@@ -1,146 +0,0 @@
-Goals of Key-Distribution in Matrix
-===================================
-
-* No Central Authority: Users should not need to trust a central authority
-  when determining the authenticity of keys.
-
-* Easy to Add New Devices: It should be easy for a user to start using a
-  new device.
-
-* Possible to discover MITM: It should be possible for a user to determine if
-  they are being MITM.
-
-* Lost Devices: It should be possible for a user to recover if they lose all
-  their devices.
-
-* No Copying Keys: Keys should be per device and shouldn't leave the device
-  they were created on.
-
-A Possible Mechanism for Key Distribution
-=========================================
-
-Basic API for setting up keys on a server:
-
-https://github.com/matrix-org/matrix-doc/pull/24
-
-Client shouldn't trust the keys unless they have been verified, e.g by
-comparing fingerprints.
-
-If a user adds a new device it should some yet to be specified protocol
-communicate with an old device and obtain a cross-signature from the old
-device for its public key.
-
-The new device can then present the cross-signed key to all the devices
-that the user is in conversations with. Those devices should then include
-the new device into those conversations.
-
-If the user cannot cross-sign the new key, e.g. because their old device
-is lost or stolen. Then they will need to reauthenticate their conversations
-out of band, e.g by comparing fingerprints.
-
-
-Goals of End-to-end encryption in Matrix
-========================================
-
-* Access to Chat History: Users should be able to see the history of a
-  conversation on a new device. User should be able to control who can
-  see their chat history and how much of the chat history they can see.
-
-* Forward Secrecy of Discarded Chat History: Users should be able to discard
-  history from their device, once they have discarded the history it should be
-  impossible for an adversary to recover that history.
-
-* Forward Secrecy of Future Messages: Users should be able to recover from
-  disclosure of the chat history on their device.
-
-* Deniablity of Chat History: It should not be possible to prove to a third
-  party that a given user sent a message.
-
-* Authenticity of Chat History: It should be possible to prove amoungst
-  the members of a chat that a message sent by a user was authored by that
-  user.
-
-
-Bonus Goals:
-
-* Traffic Analysis: It would be nice if the protocol was resilient to traffic
-  or metadata analysis. However it's not something we want to persue if it
-  harms the usability of the protocol. It might be cool if there was a
-  way for the user to could specify the trade off between performance and
-  resilience to traffic analysis that they wanted.
-
-
-A Possible Design for Group Chat using Olm
-==========================================
-
-Protecting the secrecy of history
----------------------------------
-
-Each message sent by a client has a 32-bit counter. This counter increments
-by one for each message sent by the client. This counter is used to advance a
-ratchet. The ratchet is split into a vector four 256-bit values,
-:math:`R_{n,j}` for :math:`j \in {0,1,2,3}`. The ratchet can be advanced as
-follows:
-
-.. math::
-    \begin{align}
-    R_{2^24n,0} &= H_0\left(R_{2^24(i-1),0}\right) \\
-    R_{2^24n,1} &= H_1\left(R_{2^24(i-1),0}\right) \\
-    R_{2^24n,2} &= H_2\left(R_{2^24(i-1),0}\right) \\
-    R_{2^24n,3} &= H_3\left(R_{2^24(i-1),0}\right) \\
-    R_{2^16n,1} &= H_1\left(R_{2^16(i-1),1}\right) \\
-    R_{2^16n,2} &= H_2\left(R_{2^16(i-1),1}\right) \\
-    R_{2^16n,3} &= H_3\left(R_{2^16(i-1),1}\right) \\
-    R_{2^8i,2}  &= H_2\left(R_{2^8(i-1),2}\right) \\
-    R_{2^8i,3}  &= H_3\left(R_{2^8(i-1),2}\right) \\
-    R_{i,3}     &= H_3\left(R_{(i-1),3}\right)
-    \end{align}
-
-Where :math:`H_0`, :math:`H_1`, :math:`H_2`, and :math:`H_3`
-are different hash functions. For example
-:math:`H_0` could be :math:`HMAC\left(X,\text{"\textbackslash x00"}\right)` and
-:math:`H_1` could be :math:`HMAC\left(X,\text{"\textbackslash x01"}\right)`.
-
-So every :math:`2^24` iterations :math:`R_{n,1}` is reseeded from :math:`R_{n,0}`.
-Every :math:`2^16` iterations :math:`R_{n,2}` is reseeded from :math:`R_{n,1}`.
-Every :math:`2^8` iterations :math:`R_{n,3}` is reseeded from :math:`R_{n,2}`.
-
-This scheme allows the ratchet to be advanced an arbitrary amount forwards
-while needing only 1024 hash computations.
-
-This the value of the ratchet is hashed to generate the keys used to encrypt
-each mesage.
-
-A client can decrypt chat history onwards from the earliest value of the
-ratchet it is aware of. But cannot decrypt history from before that point
-without reversing the hash function.
-
-This allows a client to share its ability to decrypt chat history with another
-from a point in the conversation onwards by giving a copy of the ratchet at
-that point in the conversation.
-
-A client can discard history by advancing a ratchet to beyond the last message
-they want to discard and then forgetting all previous values of the ratchet.
-
-Proving and denying the authenticity of history
------------------------------------------------
-
-Client sign the messages they send using a Ed25519 key generated per
-conversation. That key, along with the ratchet key, is distributed
-to other clients using 1:1 olm ratchets. Those 1:1 ratchets are started using
-Triple Diffie-Hellman which provides authenticity of the messages to the
-participants and deniability of the messages to third parties. Therefore
-any keys shared over those keys inherit the same levels of deniability and
-authenticity.
-
-Protecting the secrecy of future messages
------------------------------------------
-
-A client would need to generate new keys if it wanted to prevent access to
-messages beyond a given point in the conversation. It must generate new keys
-whenever someone leaves the room. It should generate new keys periodically
-anyway.
-
-The frequency of key generation in a large room may need to be restricted to
-keep the frequency of messages broadcast over the individual 1:1 channels
-low.

drafts/model/presence.rst

@@ -5,14 +5,14 @@ A simple implementation of presence messaging has the ability to cause a large
 amount of Internet traffic relating to presence updates. In order to minimise
 the impact of such a feature, the following observations can be made:
 
- * There is no point in a Home Server polling status for peers in a user's
+ * There is no point in a homeserver polling status for peers in a user's
    presence list if the user has no clients connected that care about it.
 
  * It is highly likely that most presence subscriptions will be symmetric - a
    given user watching another is likely to in turn be watched by that user.
 
  * It is likely that most subscription pairings will be between users who share
-   at least one Room in common, and so their Home Servers are actively
+   at least one Room in common, and so their homeservers are actively
    exchanging message PDUs or transactions relating to that Room.
 
  * Presence update messages do not need realtime guarantees. It is acceptable to
@@ -25,7 +25,7 @@ promise to send them when required. Rather than actively polling for the
 current state all the time, HSes can rely on their relative stability to only
 push updates when required.
 
-A Home Server should not rely on the longterm validity of this presence
+A homeserver should not rely on the longterm validity of this presence
 information, however, as this would not cover such cases as a user's server
 crashing and thus failing to inform their peers that users it used to host are
 no longer available online. Therefore, each promise of future updates should
@@ -98,7 +98,7 @@ The data model presented here puts the following requirements on the APIs:
 Client-Server
 -------------
 
-Requests that a client can make to its Home Server
+Requests that a client can make to its homeserver
 
  * get/set current presence state
    Basic enumeration + ability to set a custom piece of text
@@ -128,7 +128,7 @@ Requests that a client can make to its Home Server
 Server-Server
 -------------
 
-Requests that Home Servers make to others
+Requests that homeservers make to others
 
  * request permission to add a user to presence list
 

drafts/model/profiles.rst

@@ -182,7 +182,7 @@ The data model presented here puts the following requirements on the APIs:
 Client-Server
 -------------
 
-Requests that a client can make to its Home Server
+Requests that a client can make to its homeserver
 
  * get/set my Display Name
    This should return/take a simple "text/plain" field
@@ -207,7 +207,7 @@ TODO(paul): At some later stage we should consider the API for:
 Server-Server
 -------------
 
-Requests that Home Servers make to others
+Requests that homeservers make to others
 
  * get a user's Display Name / Avatar
 
@@ -221,7 +221,7 @@ Requests that Home Servers make to others
 Room Event PDU Types
 --------------------
 
-Events that are pushed from Home Servers to other Home Servers or clients.
+Events that are pushed from homeservers to other homeservers or clients.
 
  * user Display Name change
  

drafts/model/rooms.rst

@@ -226,7 +226,7 @@ clients should display these in a special way too as the room name is not
 important; instead it should distinguish them on the Display Name of the other
 party.
 
-Home Servers will need a client-API option to request setting up a new user-user
+Homeservers will need a client-API option to request setting up a new user-user
 chat room, which will then need special handling within the server. It will
 create a new room with the following 
 
@@ -260,7 +260,7 @@ history with each other simultaneously create a room and invite the other to it.
 This is called a "glare" situation. There are two possible ideas for how to
 resolve this:
 
- * Each Home Server should persist the mapping of (user ID pair) to room ID, so
+ * Each homeserver should persist the mapping of (user ID pair) to room ID, so
    that duplicate requests can be suppressed. On receipt of a room creation
    request that the HS thinks there already exists a room for, the invitation to
    join can be rejected if:

drafts/model/third-party-id.rst

@@ -66,7 +66,7 @@ Privacy
 
 A User may publish the association between their phone number and Matrix User ID
 on the Identity Server without publishing the number in their Profile hosted on
-their Home Server.
+their homeserver.
 
 Identity Servers should refrain from publishing reverse mappings and should 
 take steps, such as rate limiting, to prevent attackers enumerating the space of

event-schemas/check_examples.py

@@ -38,13 +38,12 @@ def check_example_file(examplepath, schemapath):
         schema = yaml.load(f)
 
     fileurl = "file://" + os.path.abspath(schemapath)
+    schema["id"] = fileurl
+    resolver = jsonschema.RefResolver(schemapath, schema, handlers={"file": load_yaml})
 
     print ("Checking schema for: %r %r" % (examplepath, schemapath))
-    # Setting the 'id' tells jsonschema where the file is so that it
-    # can correctly resolve relative $ref references in the schema
-    schema['id'] = fileurl
     try:
-        jsonschema.validate(example, schema)
+        jsonschema.validate(example, schema, resolver=resolver)
     except Exception as e:
         raise ValueError("Error validating JSON schema for %r %r" % (
             examplepath, schemapath
@@ -71,6 +70,15 @@ def check_example_dir(exampledir, schemadir):
     if errors:
         raise ValueError("Error validating examples")
 
+
+def load_yaml(path):
+    if not path.startswith("file:///"):
+        raise Exception("Bad ref: %s" % (path,))
+    path = path[len("file://"):]
+    with open(path, "r") as f:
+        return yaml.load(f)
+
+
 if __name__ == '__main__':
     try:
         check_example_dir("examples", "schema")

event-schemas/examples/m.call.answer

@@ -13,5 +13,5 @@
   "event_id": "$WLGTSEFSEF:localhost",
   "type": "m.call.answer",
   "room_id": "!Cuyf34gef24t:localhost",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 }

event-schemas/examples/m.call.candidates

@@ -15,5 +15,5 @@
   "event_id": "$WLGTSEFSEF:localhost",
   "type": "m.call.candidates",
   "room_id": "!Cuyf34gef24t:localhost",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 }

event-schemas/examples/m.call.hangup

@@ -8,5 +8,5 @@
   "event_id": "$WLGTSEFSEF:localhost",
   "type": "m.call.hangup",
   "room_id": "!Cuyf34gef24t:localhost",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 }

event-schemas/examples/m.call.invite

@@ -13,5 +13,5 @@
   "event_id": "$WLGTSEFSEF:localhost",
   "type": "m.call.invite",
   "room_id": "!Cuyf34gef24t:localhost",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 }

event-schemas/examples/m.room.aliases

@@ -8,5 +8,5 @@
   "event_id": "$WLGTSEFSEF:localhost",
   "type": "m.room.aliases",
   "room_id": "!Cuyf34gef24t:localhost",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 }

event-schemas/examples/m.room.avatar

@@ -14,5 +14,5 @@
   "type": "m.room.avatar",
   "state_key": "",
   "room_id": "!Cuyf34gef24t:localhost",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 }

event-schemas/examples/m.room.canonical_alias

@@ -8,5 +8,5 @@
   "event_id": "$WLGTSEFSEF:localhost",
   "type": "m.room.canonical_alias",
   "room_id": "!Cuyf34gef24t:localhost",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 }

event-schemas/examples/m.room.create

@@ -8,5 +8,5 @@
   "event_id": "$WLGTSEFSEF:localhost",
   "type": "m.room.create",
   "room_id": "!Cuyf34gef24t:localhost",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 }

event-schemas/examples/m.room.guest_access

@@ -8,5 +8,5 @@
   "event_id": "$WLGTSEFSEG:localhost",
   "type": "m.room.guest_access",
   "room_id": "!Cuyf34gef24u:localhost",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 }

event-schemas/examples/m.room.history_visibility

@@ -8,5 +8,5 @@
   "event_id": "$WLGTSEFSEF:localhost",
   "type": "m.room.history_visibility",
   "room_id": "!Cuyf34gef24t:localhost",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 }

event-schemas/examples/m.room.join_rules

@@ -8,5 +8,5 @@
   "event_id": "$WLGTSEFSEF:localhost",
   "type": "m.room.join_rules",
   "room_id": "!Cuyf34gef24t:localhost",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 }

event-schemas/examples/m.room.member

@@ -26,5 +26,5 @@
   "event_id": "$WLGTSEFSEF:localhost",
   "type": "m.room.member",
   "room_id": "!Cuyf34gef24t:localhost",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 }

event-schemas/examples/m.room.member#invite_room_state

@@ -26,5 +26,5 @@
   "event_id": "$WLGTSEFSEF:localhost",
   "type": "m.room.member",
   "room_id": "!Cuyf34gef24t:localhost",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 }

event-schemas/examples/m.room.member#third_party_invite

@@ -21,5 +21,5 @@
   "event_id": "$WLGTSEFSEF:localhost",
   "type": "m.room.member",
   "room_id": "!Cuyf34gef24t:localhost",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 }

event-schemas/examples/m.room.message#m.audio

@@ -14,5 +14,5 @@
   "origin_server_ts": 1432735824653,
   "room_id": "!jEsUZKDJdhlrceRyVU:localhost",
   "type": "m.room.message",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 } 

event-schemas/examples/m.room.message#m.emote

@@ -8,5 +8,5 @@
   "event_id": "$WLGTSEFSEF:localhost",
   "type": "m.room.message",
   "room_id": "!Cuyf34gef24t:localhost",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 }

event-schemas/examples/m.room.message#m.file

@@ -14,5 +14,5 @@
   "origin_server_ts": 1432735824653,
   "room_id": "!jEsUZKDJdhlrceRyVU:localhost",
   "type": "m.room.message",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 } 

event-schemas/examples/m.room.message#m.image

@@ -15,5 +15,5 @@
   "event_id": "$WLGTSEFSEF:localhost",
   "type": "m.room.message",
   "room_id": "!Cuyf34gef24t:localhost",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 }

event-schemas/examples/m.room.message#m.location

@@ -16,5 +16,5 @@
   "origin_server_ts": 1432735824653,
   "room_id": "!jEsUZKDJdhlrceRyVU:localhost",
   "type": "m.room.message",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 } 

event-schemas/examples/m.room.message#m.notice

@@ -8,5 +8,5 @@
   "event_id": "$WLGTSEFSEF:localhost",
   "type": "m.room.message",
   "room_id": "!Cuyf34gef24t:localhost",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 }

event-schemas/examples/m.room.message#m.text

@@ -8,5 +8,5 @@
   "event_id": "$WLGTSEFSEF:localhost",
   "type": "m.room.message",
   "room_id": "!Cuyf34gef24t:localhost",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 }

event-schemas/examples/m.room.message#m.video

@@ -23,5 +23,5 @@
   "origin_server_ts": 1432735824653,
   "room_id": "!jEsUZKDJdhlrceRyVU:localhost",
   "type": "m.room.message",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 } 

event-schemas/examples/m.room.message.feedback

@@ -8,5 +8,5 @@
   "event_id": "$WLGTSEFSEF:localhost",
   "type": "m.room.message.feedback",
   "room_id": "!Cuyf34gef24t:localhost",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 }

event-schemas/examples/m.room.name

@@ -8,5 +8,5 @@
   "event_id": "$WLGTSEFSEF:localhost",
   "type": "m.room.name",
   "room_id": "!Cuyf34gef24t:localhost",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 }

event-schemas/examples/m.room.power_levels

@@ -20,5 +20,5 @@
   "event_id": "$WLGTSEFSEF:localhost",
   "type": "m.room.power_levels",
   "room_id": "!Cuyf34gef24t:localhost",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 }

event-schemas/examples/m.room.redaction

@@ -8,5 +8,5 @@
   "type": "m.room.redaction",
   "room_id": "!Cuyf34gef24t:localhost",
   "redacts": "!fukweghifu23:localhost",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 }

event-schemas/examples/m.room.topic

@@ -8,5 +8,5 @@
   "event_id": "$WLGTSEFSEF:localhost",
   "type": "m.room.topic",
   "room_id": "!Cuyf34gef24t:localhost",
-  "user_id": "@example:localhost"
+  "sender": "@example:localhost"
 }

event-schemas/schema/core-event-schema/event.json

@@ -1,16 +0,0 @@
-{
-  "type": "object",
-  "title": "Event",
-  "description": "The basic set of fields all events must have.",
-  "properties": {
-    "content": {
-      "type": "object",
-      "title": "EventContent",
-      "description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body."
-    },
-    "type": {
-      "type": "string",
-      "description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'"
-    }
-  }
-}

event-schemas/schema/core-event-schema/event.yaml

@@ -0,0 +1,13 @@
+description: The basic set of fields all events must have.
+properties:
+  content:
+    description: The fields in this object will vary depending on the type of event.
+      When interacting with the REST API, this is the HTTP body.
+    title: EventContent
+    type: object
+  type:
+    description: The type of event. This SHOULD be namespaced similar to Java package
+      naming conventions e.g. 'com.example.subdomain.event.type'
+    type: string
+title: Event
+type: object

event-schemas/schema/core-event-schema/msgtype_infos/image_info.json

@@ -1,23 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-04/schema#",
-  "title": "ImageInfo",
-  "description": "Metadata about an image.",
-  "properties": {
-    "size": {
-      "type": "integer",
-      "description": "Size of the image in bytes."
-    },
-    "w": {
-      "type": "integer",
-      "description": "The width of the image in pixels."
-    },
-    "h": {
-      "type": "integer",
-      "description": "The height of the image in pixels."
-    },
-    "mimetype": {
-      "type": "string",
-      "description": "The mimetype of the image, e.g. ``image/jpeg``."
-    }
-  }
-}

event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml

@@ -0,0 +1,16 @@
+$schema: http://json-schema.org/draft-04/schema#
+description: Metadata about an image.
+properties:
+  h:
+    description: The height of the image in pixels.
+    type: integer
+  mimetype:
+    description: The mimetype of the image, e.g. ``image/jpeg``.
+    type: string
+  size:
+    description: Size of the image in bytes.
+    type: integer
+  w:
+    description: The width of the image in pixels.
+    type: integer
+title: ImageInfo

event-schemas/schema/core-event-schema/room_event.json

@@ -1,23 +0,0 @@
-{
-  "type": "object",
-  "title": "Room Event",
-  "description": "In addition to the Event fields, Room Events MUST have the following additional field.",
-  "allOf":[{
-    "$ref": "event.json"
-  }],
-  "properties": {
-    "room_id": {
-      "type": "string",
-      "description": "The ID of the room associated with this event."
-    },
-    "event_id": {
-      "type": "string",
-      "description": "The globally unique event identifier."
-    },
-    "user_id": {
-      "type": "string",
-      "description": "Contains the fully-qualified ID of the user who *sent* this event."
-    }
-  },
-  "required": ["room_id"]
-}

event-schemas/schema/core-event-schema/room_event.yaml

@@ -0,0 +1,37 @@
+allOf:
+- $ref: event.yaml
+description: In addition to the Event fields, Room Events may have the following additional
+  fields.
+properties:
+  event_id:
+    description: Required. The globally unique event identifier.
+    type: string
+  room_id:
+    description: Required. The ID of the room associated with this event.
+    type: string
+  sender:
+    description: Required. Contains the fully-qualified ID of the user who *sent*
+      this event.
+    type: string
+  unsigned:
+    description: Contains optional extra information about the event.
+    properties:
+      age:
+        description: The time in milliseconds that has elapsed since the event was
+          sent
+        type: integer
+      redacted_because:
+        description: The reason this event was redacted, if it was redacted
+        type: string
+      transaction_id:
+        description: The client-supplied transaction ID, if the client being given
+          the event is the same one which sent it.
+        type: string
+    title: UnsignedData
+    type: object
+required:
+- event_id
+- room_id
+- sender
+title: Room Event
+type: object

event-schemas/schema/core-event-schema/state_event.json

@@ -1,20 +0,0 @@
-{
-  "type": "object",
-  "title": "State Event",
-  "description": "In addition to the Room Event fields, State Events have the following additional fields.",
-  "allOf":[{
-    "$ref": "room_event.json"
-  }],
-  "properties": {
-    "state_key": {
-      "type": "string",
-      "description": "A unique key which defines the overwriting semantics for this piece of room state. This value is often a zero-length string. The presence of this key makes this event a State Event. The key MUST NOT start with '_'."
-    },
-    "prev_content": {
-      "title": "EventContent",
-      "type": "object",
-      "description": "Optional. The previous ``content`` for this event. If there is no previous content, this key will be missing."
-    }
-  },
-  "required": ["state_key"]
-}

event-schemas/schema/core-event-schema/state_event.yaml

@@ -0,0 +1,19 @@
+allOf:
+- $ref: room_event.yaml
+description: In addition to the Room Event fields, State Events have the following
+  additional fields.
+properties:
+  prev_content:
+    description: Optional. The previous ``content`` for this event. If there is no
+      previous content, this key will be missing.
+    title: EventContent
+    type: object
+  state_key:
+    description: A unique key which defines the overwriting semantics for this piece
+      of room state. This value is often a zero-length string. The presence of this
+      key makes this event a State Event. The key MUST NOT start with '_'.
+    type: string
+required:
+- state_key
+title: State Event
+type: object

event-schemas/schema/m.call.answer

@@ -2,7 +2,7 @@
     "type": "object",
     "description": "This event is sent by the callee when they wish to answer the call.",
     "allOf": [{
-        "$ref": "core-event-schema/room_event.json"
+        "$ref": "core-event-schema/room_event.yaml"
     }],
     "properties": {
         "content": {

event-schemas/schema/m.call.candidates

@@ -2,7 +2,7 @@
     "type": "object",
     "description": "This event is sent by callers after sending an invite and by the callee after answering. Its purpose is to give the other party additional ICE candidates to try using to communicate.",
     "allOf": [{
-        "$ref": "core-event-schema/room_event.json"
+        "$ref": "core-event-schema/room_event.yaml"
     }],
     "properties": {
         "content": {