diff --git a/api/check_examples.py b/api/check_examples.py
index ee3c773c..b206a737 100755
--- a/api/check_examples.py
+++ b/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:
diff --git a/api/client-server/definitions/event.json b/api/client-server/definitions/event.json
deleted file mode 100644
index 98aac21e..00000000
--- a/api/client-server/definitions/event.json
+++ /dev/null
@@ -1,49 +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."
-        },
-        "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."
-        }
-      }
-    }
-  }
-}
diff --git a/api/client-server/definitions/event.yaml b/api/client-server/definitions/event.yaml
new file mode 100644
index 00000000..d40be8a9
--- /dev/null
+++ b/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
diff --git a/api/client-server/definitions/event_batch.json b/api/client-server/definitions/event_batch.json
deleted file mode 100644
index 7f489423..00000000
--- a/api/client-server/definitions/event_batch.json
+++ /dev/null
@@ -1,13 +0,0 @@
-{
-  "type": "object",
-  "properties": {
-    "events": {
-      "type": "array",
-      "description": "List of events",
-      "items": {
-        "type": "object",
-        "allOf": [{"$ref": "event.json" }]
-      }
-    }
-  }
-}
diff --git a/api/client-server/definitions/event_batch.yaml b/api/client-server/definitions/event_batch.yaml
new file mode 100644
index 00000000..bc6faf5b
--- /dev/null
+++ b/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
diff --git a/api/client-server/definitions/event_filter.json b/api/client-server/definitions/event_filter.json
deleted file mode 100644
index 1cdcb1f4..00000000
--- a/api/client-server/definitions/event_filter.json
+++ /dev/null
@@ -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"
-      }
-    }
-  }
-}
diff --git a/api/client-server/definitions/event_filter.yaml b/api/client-server/definitions/event_filter.yaml
new file mode 100644
index 00000000..23a2f11c
--- /dev/null
+++ b/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
diff --git a/api/client-server/definitions/push_condition.json b/api/client-server/definitions/push_condition.json
deleted file mode 100644
index 1d84955c..00000000
--- a/api/client-server/definitions/push_condition.json
+++ /dev/null
@@ -1,9 +0,0 @@
-{
-  "type": "object", 
-  "properties": {
-    "kind": {
-      "type": "string",
-      "enum": ["event_match", "profile_tag", "contains_display_name", "room_member_count"]
-    }
-  }
-}
\ No newline at end of file
diff --git a/api/client-server/definitions/push_condition.yaml b/api/client-server/definitions/push_condition.yaml
new file mode 100644
index 00000000..e698d73d
--- /dev/null
+++ b/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
diff --git a/api/client-server/definitions/push_rule.json b/api/client-server/definitions/push_rule.json
deleted file mode 100644
index d10f11f8..00000000
--- a/api/client-server/definitions/push_rule.json
+++ /dev/null
@@ -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"
-    }
-  }
-}
diff --git a/api/client-server/definitions/push_rule.yaml b/api/client-server/definitions/push_rule.yaml
new file mode 100644
index 00000000..0b2d78f4
--- /dev/null
+++ b/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
diff --git a/api/client-server/definitions/push_ruleset.json b/api/client-server/definitions/push_ruleset.json
deleted file mode 100644
index 529ebeed..00000000
--- a/api/client-server/definitions/push_ruleset.json
+++ /dev/null
@@ -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"
-    }
-  }
-}
diff --git a/api/client-server/definitions/push_ruleset.yaml b/api/client-server/definitions/push_ruleset.yaml
new file mode 100644
index 00000000..52ae5d1e
--- /dev/null
+++ b/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
diff --git a/api/client-server/definitions/room_event_filter.json b/api/client-server/definitions/room_event_filter.json
deleted file mode 100644
index 02e5d0e0..00000000
--- a/api/client-server/definitions/room_event_filter.json
+++ /dev/null
@@ -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"
-      }
-    }
-  }
-}
diff --git a/api/client-server/definitions/room_event_filter.yaml b/api/client-server/definitions/room_event_filter.yaml
new file mode 100644
index 00000000..4826693d
--- /dev/null
+++ b/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
diff --git a/api/client-server/definitions/sync_filter.json b/api/client-server/definitions/sync_filter.json
deleted file mode 100644
index 8884f7d1..00000000
--- a/api/client-server/definitions/sync_filter.json
+++ /dev/null
@@ -1,49 +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"}]
-        },
-        "include_leave": {
-          "description":
-            "Include rooms that the user has left in the sync, default false",
-          "type": "boolean"
-        }
-      }
-    },
-    "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"
-      }
-    }
-  }
-}
diff --git a/api/client-server/definitions/sync_filter.yaml b/api/client-server/definitions/sync_filter.yaml
new file mode 100644
index 00000000..4aa78e77
--- /dev/null
+++ b/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
diff --git a/api/client-server/definitions/timeline_batch.json b/api/client-server/definitions/timeline_batch.json
deleted file mode 100644
index 6f7e714a..00000000
--- a/api/client-server/definitions/timeline_batch.json
+++ /dev/null
@@ -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"
-    }
-  }
-}
diff --git a/api/client-server/definitions/timeline_batch.yaml b/api/client-server/definitions/timeline_batch.yaml
new file mode 100644
index 00000000..095bb61e
--- /dev/null
+++ b/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
diff --git a/api/client-server/filter.yaml b/api/client-server/filter.yaml
index 4dd0b597..bf81f60e 100644
--- a/api/client-server/filter.yaml
+++ b/api/client-server/filter.yaml
@@ -42,7 +42,7 @@ paths:
           schema:
             type: object
             allOf:
-              - $ref: "definitions/sync_filter.json"
+              - $ref: "definitions/sync_filter.yaml"
             example: |-
               {
                 "room": {
@@ -138,6 +138,6 @@ paths:
           schema:
             type: object
             allOf:
-              - $ref: "definitions/sync_filter.json"
+              - $ref: "definitions/sync_filter.yaml"
       tags:
         - Room participation
diff --git a/api/client-server/guest_events.yaml b/api/client-server/guest_events.yaml
index ff02d1fb..3dce4140 100644
--- a/api/client-server/guest_events.yaml
+++ b/api/client-server/guest_events.yaml
@@ -98,7 +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.
diff --git a/api/client-server/old_sync.yaml b/api/client-server/old_sync.yaml
index 3dff7a78..fafcb825 100644
--- a/api/client-server/old_sync.yaml
+++ b/api/client-server/old_sync.yaml
@@ -84,7 +84,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."
       tags:
@@ -286,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:
@@ -333,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
@@ -346,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"]
@@ -362,7 +362,7 @@ 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:
@@ -401,7 +401,7 @@ paths:
               }
           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:
diff --git a/api/client-server/presence.yaml b/api/client-server/presence.yaml
index 23edc4e2..d9a1b866 100644
--- a/api/client-server/presence.yaml
+++ b/api/client-server/presence.yaml
@@ -210,6 +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
diff --git a/api/client-server/pushrules.yaml b/api/client-server/pushrules.yaml
index a00ca2e8..07bd6bdb 100644
--- a/api/client-server/pushrules.yaml
+++ b/api/client-server/pushrules.yaml
@@ -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: |-
@@ -297,7 +297,7 @@ paths:
             description: The push rule.
             title: PushRule
             allOf: [
-              "$ref": "definitions/push_rule.json"
+              "$ref": "definitions/push_rule.yaml"
             ]
       tags:
         - Push notifications
@@ -420,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:
diff --git a/api/client-server/rooms.yaml b/api/client-server/rooms.yaml
index 68e7b993..c21bd5b6 100644
--- a/api/client-server/rooms.yaml
+++ b/api/client-server/rooms.yaml
@@ -214,7 +214,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"
         403:
           description: >
             You aren't a member of the room and weren't previously a
@@ -396,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
@@ -409,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"]
@@ -424,7 +424,7 @@ 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: >
diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml
index da2fcec6..b2596cd7 100644
--- a/api/client-server/search.yaml
+++ b/api/client-server/search.yaml
@@ -111,7 +111,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"
           examples:
             application/json: |-
                {
diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml
index d3ae9fd0..4b399d07 100644
--- a/api/client-server/sync.yaml
+++ b/api/client-server/sync.yaml
@@ -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: |-
               {
diff --git a/event-schemas/check_examples.py b/event-schemas/check_examples.py
index 5a409407..0e879541 100755
--- a/event-schemas/check_examples.py
+++ b/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")
diff --git a/event-schemas/schema/core-event-schema/event.json b/event-schemas/schema/core-event-schema/event.json
deleted file mode 100644
index f9103715..00000000
--- a/event-schemas/schema/core-event-schema/event.json
+++ /dev/null
@@ -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'"
-    }
-  }
-}
diff --git a/event-schemas/schema/core-event-schema/event.yaml b/event-schemas/schema/core-event-schema/event.yaml
new file mode 100644
index 00000000..ebf67aa3
--- /dev/null
+++ b/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
diff --git a/event-schemas/schema/core-event-schema/msgtype_infos/image_info.json b/event-schemas/schema/core-event-schema/msgtype_infos/image_info.json
deleted file mode 100644
index ee75745e..00000000
--- a/event-schemas/schema/core-event-schema/msgtype_infos/image_info.json
+++ /dev/null
@@ -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``."
-    }
-  }
-}
diff --git a/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml b/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml
new file mode 100644
index 00000000..7ef7a86f
--- /dev/null
+++ b/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
diff --git a/event-schemas/schema/core-event-schema/room_event.json b/event-schemas/schema/core-event-schema/room_event.json
deleted file mode 100644
index 81fb4b09..00000000
--- a/event-schemas/schema/core-event-schema/room_event.json
+++ /dev/null
@@ -1,42 +0,0 @@
-{
-  "type": "object",
-  "title": "Room Event",
-  "description": "In addition to the Event fields, Room Events may have the following additional fields.",
-  "allOf":[{
-    "$ref": "event.json"
-  }],
-  "properties": {
-    "event_id": {
-      "type": "string",
-      "description": "Required. The globally unique event identifier."
-    },
-    "room_id": {
-      "type": "string",
-      "description": "Required. The ID of the room associated with this event."
-    },
-    "sender": {
-      "type": "string",
-      "description": "Required. Contains the fully-qualified ID of the user who *sent* this event."
-    },
-    "unsigned": {
-      "type": "object",
-      "description": "Contains optional extra information about the event.",
-      "title": "UnsignedData",
-      "properties": {
-        "age": {
-          "type": "integer",
-          "description": "The time in milliseconds that has elapsed since the event was sent"
-        },
-        "redacted_because": {
-          "type": "string",
-          "description": "The reason this event was redacted, if it was redacted"
-        },
-        "transaction_id": {
-          "type": "string",
-          "description": "The client-supplied transaction ID, if the client being given the event is the same one which sent it."
-        }
-      }
-    }
-  },
-  "required": ["event_id", "room_id", "sender"]
-}
diff --git a/event-schemas/schema/core-event-schema/room_event.yaml b/event-schemas/schema/core-event-schema/room_event.yaml
new file mode 100644
index 00000000..96c16031
--- /dev/null
+++ b/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
diff --git a/event-schemas/schema/core-event-schema/state_event.json b/event-schemas/schema/core-event-schema/state_event.json
deleted file mode 100644
index cfcb212c..00000000
--- a/event-schemas/schema/core-event-schema/state_event.json
+++ /dev/null
@@ -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"]
-}
diff --git a/event-schemas/schema/core-event-schema/state_event.yaml b/event-schemas/schema/core-event-schema/state_event.yaml
new file mode 100644
index 00000000..020e9087
--- /dev/null
+++ b/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
diff --git a/event-schemas/schema/m.call.answer b/event-schemas/schema/m.call.answer
index f11a61ba..9d98dd7d 100644
--- a/event-schemas/schema/m.call.answer
+++ b/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": {
diff --git a/event-schemas/schema/m.call.candidates b/event-schemas/schema/m.call.candidates
index 52e06705..7426717c 100644
--- a/event-schemas/schema/m.call.candidates
+++ b/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": {
diff --git a/event-schemas/schema/m.call.hangup b/event-schemas/schema/m.call.hangup
index 02667635..9d45d179 100644
--- a/event-schemas/schema/m.call.hangup
+++ b/event-schemas/schema/m.call.hangup
@@ -2,7 +2,7 @@
     "type": "object",
     "description": "Sent by either party to signal their termination of the call. This can be sent either once the call has has been established or before to abort the call.",
     "allOf": [{
-        "$ref": "core-event-schema/room_event.json"
+        "$ref": "core-event-schema/room_event.yaml"
     }],
     "properties": {
         "content": {
diff --git a/event-schemas/schema/m.call.invite b/event-schemas/schema/m.call.invite
index 585403d0..ebf09267 100644
--- a/event-schemas/schema/m.call.invite
+++ b/event-schemas/schema/m.call.invite
@@ -2,7 +2,7 @@
     "type": "object",
     "description": "This event is sent by the caller when they wish to establish a call.",
     "allOf": [{
-        "$ref": "core-event-schema/room_event.json"
+        "$ref": "core-event-schema/room_event.yaml"
     }],
     "properties": {
         "content": {
diff --git a/event-schemas/schema/m.room.aliases b/event-schemas/schema/m.room.aliases
index 43cc9dbc..a3427703 100644
--- a/event-schemas/schema/m.room.aliases
+++ b/event-schemas/schema/m.room.aliases
@@ -3,7 +3,7 @@
     "title": "Informs the room about what room aliases it has been given.",
     "description": "This event is sent by a homeserver directly to inform of changes to the list of aliases it knows about for that room. The ``state_key`` for this event is set to the homeserver which owns the room alias. The entire set of known aliases for the room is the union of all the ``m.room.aliases`` events, one for each homeserver. Clients **should** check the validity of any room alias given in this list before presenting it to the user as trusted fact. The lists given by this event should be considered simply as advice on which aliases might exist, for which the client can perform the lookup to confirm whether it receives the correct room ID.",
     "allOf": [{
-        "$ref": "core-event-schema/state_event.json"
+        "$ref": "core-event-schema/state_event.yaml"
     }],
     "properties": {
         "content": {
diff --git a/event-schemas/schema/m.room.avatar b/event-schemas/schema/m.room.avatar
index 276c975c..60a3e1b6 100644
--- a/event-schemas/schema/m.room.avatar
+++ b/event-schemas/schema/m.room.avatar
@@ -3,7 +3,7 @@
     "description": "A picture that is associated with the room. This can be displayed alongside the room information.",
     "type": "object",
     "allOf": [{
-        "$ref": "core-event-schema/state_event.json"
+        "$ref": "core-event-schema/state_event.yaml"
     }],
     "properties": {
         "content": {
@@ -22,7 +22,7 @@
                     "title": "ImageInfo",
                     "description": "Metadata about the image referred to in ``thumbnail_url``.",
                     "allOf": [{
-                        "$ref": "core-event-schema/msgtype_infos/image_info.json"
+                        "$ref": "core-event-schema/msgtype_infos/image_info.yaml"
                     }]
                 },
                 "info": {
diff --git a/event-schemas/schema/m.room.canonical_alias b/event-schemas/schema/m.room.canonical_alias
index 49e0e669..4d6f956b 100644
--- a/event-schemas/schema/m.room.canonical_alias
+++ b/event-schemas/schema/m.room.canonical_alias
@@ -3,7 +3,7 @@
     "title": "Informs the room as to which alias is the canonical one.",
     "description": "This event is used to inform the room about which alias should be considered the canonical one. This could be for display purposes or as suggestion to users which alias to use to advertise the room.",
     "allOf": [{
-        "$ref": "core-event-schema/state_event.json"
+        "$ref": "core-event-schema/state_event.yaml"
     }],
     "properties": {
         "content": {
diff --git a/event-schemas/schema/m.room.create b/event-schemas/schema/m.room.create
index 348b6d86..13e5513c 100644
--- a/event-schemas/schema/m.room.create
+++ b/event-schemas/schema/m.room.create
@@ -3,7 +3,7 @@
     "title": "The first event in the room.",
     "description": "This is the first event in a room and cannot be changed. It acts as the root of all other events.",
     "allOf": [{
-        "$ref": "core-event-schema/state_event.json"
+        "$ref": "core-event-schema/state_event.yaml"
     }],
     "properties": {
         "content": {
diff --git a/event-schemas/schema/m.room.guest_access b/event-schemas/schema/m.room.guest_access
index a0141f37..c7ef9026 100644
--- a/event-schemas/schema/m.room.guest_access
+++ b/event-schemas/schema/m.room.guest_access
@@ -3,7 +3,7 @@
     "title": "Controls whether guest users are allowed to join rooms.",
     "description": "This event controls whether guest users are allowed to join rooms. If this event is absent, servers should act as if it is present and has the guest_access value \"forbidden\".",
     "allOf": [{
-        "$ref": "core-event-schema/state_event.json"
+        "$ref": "core-event-schema/state_event.yaml"
     }],
     "properties": {
         "content": {
diff --git a/event-schemas/schema/m.room.history_visibility b/event-schemas/schema/m.room.history_visibility
index 9abcf5b8..aaf25261 100644
--- a/event-schemas/schema/m.room.history_visibility
+++ b/event-schemas/schema/m.room.history_visibility
@@ -3,7 +3,7 @@
     "title": "Controls visibility of history.",
     "description": "This event controls whether a user can see the events that happened in a room from before they joined.",
     "allOf": [{
-        "$ref": "core-event-schema/state_event.json"
+        "$ref": "core-event-schema/state_event.yaml"
     }],
     "properties": {
         "content": {
diff --git a/event-schemas/schema/m.room.join_rules b/event-schemas/schema/m.room.join_rules
index 70c36ccb..680d6f60 100644
--- a/event-schemas/schema/m.room.join_rules
+++ b/event-schemas/schema/m.room.join_rules
@@ -3,7 +3,7 @@
     "title": "Describes how users are allowed to join the room.",
     "description": "A room may be ``public`` meaning anyone can join the room without any prior action. Alternatively, it can be ``invite`` meaning that a user who wishes to join the room must first receive an invite to the room from someone already inside of the room. Currently, ``knock`` and ``private`` are reserved keywords which are not implemented.",
     "allOf": [{
-        "$ref": "core-event-schema/state_event.json"
+        "$ref": "core-event-schema/state_event.yaml"
     }],
     "properties": {
         "content": {
diff --git a/event-schemas/schema/m.room.member b/event-schemas/schema/m.room.member
index 64f766d8..28a49c3a 100644
--- a/event-schemas/schema/m.room.member
+++ b/event-schemas/schema/m.room.member
@@ -3,7 +3,7 @@
     "title": "The current membership state of a user in the room.",
     "description": "Adjusts the membership state for a user in a room. It is preferable to use the membership APIs (``/rooms/<room id>/invite`` etc) when performing membership actions rather than adjusting the state directly as there are a restricted set of valid transformations. For example, user A cannot force user B to join a room, and trying to force this state change directly will fail. \n\nThe ``third_party_invite`` property will be set if this invite is an ``invite`` event and is the successor of an ``m.room.third_party_invite`` event, and absent otherwise.\n\nThis event may also include an ``invite_room_state`` key **outside the** ``content`` **key**. If present, this contains an array of ``StrippedState`` Events. These events provide information on a few select state events such as the room name.",
     "allOf": [{
-        "$ref": "core-event-schema/state_event.json"
+        "$ref": "core-event-schema/state_event.yaml"
     }],
     "properties": {
         "content": {
diff --git a/event-schemas/schema/m.room.message b/event-schemas/schema/m.room.message
index 91c04b7f..82de26a8 100644
--- a/event-schemas/schema/m.room.message
+++ b/event-schemas/schema/m.room.message
@@ -3,7 +3,7 @@
     "title": "Message",
     "description": "This event is used when sending messages in a room. Messages are not limited to be text. The ``msgtype`` key outlines the type of message, e.g. text, audio, image, video, etc. The ``body`` key is text and MUST be used with every kind of ``msgtype`` as a fallback mechanism for when a client cannot render a message. This allows clients to display *something* even if it is just plain text.",
     "allOf": [{
-        "$ref": "core-event-schema/room_event.json"
+        "$ref": "core-event-schema/room_event.yaml"
     }],
     "properties": {
         "content": {
diff --git a/event-schemas/schema/m.room.message#m.audio b/event-schemas/schema/m.room.message#m.audio
index 0a6625f5..cd55426c 100644
--- a/event-schemas/schema/m.room.message#m.audio
+++ b/event-schemas/schema/m.room.message#m.audio
@@ -3,7 +3,7 @@
     "title": "AudioMessage",
     "description": "This message represents a single audio clip.",
     "allOf": [{
-        "$ref": "core-event-schema/room_event.json"
+        "$ref": "core-event-schema/room_event.yaml"
     }],
     "properties": {
         "content": {
diff --git a/event-schemas/schema/m.room.message#m.emote b/event-schemas/schema/m.room.message#m.emote
index 690600f4..8fa63951 100644
--- a/event-schemas/schema/m.room.message#m.emote
+++ b/event-schemas/schema/m.room.message#m.emote
@@ -3,7 +3,7 @@
     "title": "EmoteMessage",
     "description": "This message is similar to ``m.text`` except that the sender is 'performing' the action contained in the ``body`` key, similar to ``/me`` in IRC. This message should be prefixed by the name of the sender. This message could also be represented in a different colour to distinguish it from regular ``m.text`` messages.",
     "allOf": [{
-        "$ref": "core-event-schema/room_event.json"
+        "$ref": "core-event-schema/room_event.yaml"
     }],
     "properties": {
         "content": {
diff --git a/event-schemas/schema/m.room.message#m.file b/event-schemas/schema/m.room.message#m.file
index c97480ef..f921b23f 100644
--- a/event-schemas/schema/m.room.message#m.file
+++ b/event-schemas/schema/m.room.message#m.file
@@ -3,7 +3,7 @@
     "title": "FileMessage",
     "description": "This message represents a generic file.",
     "allOf": [{
-        "$ref": "core-event-schema/room_event.json"
+        "$ref": "core-event-schema/room_event.yaml"
     }],
     "properties": {
         "content": {
@@ -49,7 +49,7 @@
                     "title": "ImageInfo",
                     "description": "Metadata about the image referred to in ``thumbnail_url``.",
                     "allOf": [{
-                        "$ref": "core-event-schema/msgtype_infos/image_info.json"
+                        "$ref": "core-event-schema/msgtype_infos/image_info.yaml"
                     }]
                 }
             },
diff --git a/event-schemas/schema/m.room.message#m.image b/event-schemas/schema/m.room.message#m.image
index af78096d..1085bb85 100644
--- a/event-schemas/schema/m.room.message#m.image
+++ b/event-schemas/schema/m.room.message#m.image
@@ -3,7 +3,7 @@
     "title": "ImageMessage",
     "description": "This message represents a single image and an optional thumbnail.",
     "allOf": [{
-        "$ref": "core-event-schema/room_event.json"
+        "$ref": "core-event-schema/room_event.yaml"
     }],
     "properties": {
         "content": {
@@ -30,7 +30,7 @@
                     "title": "ImageInfo",
                     "description": "Metadata about the image referred to in ``thumbnail_url``.",
                     "allOf": [{
-                        "$ref": "core-event-schema/msgtype_infos/image_info.json"
+                        "$ref": "core-event-schema/msgtype_infos/image_info.yaml"
                     }]
                 },
                 "info": {
diff --git a/event-schemas/schema/m.room.message#m.location b/event-schemas/schema/m.room.message#m.location
index ef4b5e81..7deb6f8d 100644
--- a/event-schemas/schema/m.room.message#m.location
+++ b/event-schemas/schema/m.room.message#m.location
@@ -3,7 +3,7 @@
     "title": "LocationMessage",
     "description": "This message represents a real-world location.",
     "allOf": [{
-        "$ref": "core-event-schema/room_event.json"
+        "$ref": "core-event-schema/room_event.yaml"
     }],
     "properties": {
         "content": {
@@ -29,7 +29,7 @@
                     "type": "object",
                     "title": "ImageInfo",
                     "allOf": [{
-                        "$ref": "core-event-schema/msgtype_infos/image_info.json"
+                        "$ref": "core-event-schema/msgtype_infos/image_info.yaml"
                     }]
                 }
             },
diff --git a/event-schemas/schema/m.room.message#m.notice b/event-schemas/schema/m.room.message#m.notice
index 195c56a3..100c3d60 100644
--- a/event-schemas/schema/m.room.message#m.notice
+++ b/event-schemas/schema/m.room.message#m.notice
@@ -3,7 +3,7 @@
     "title": "NoticeMessage",
     "description": "A m.notice message should be considered similar to a plain m.text message except that clients should visually distinguish it in some way. It is intended to be used by automated clients, such as bots, bridges, and other entities, rather than humans. Additionally, such automated agents which watch a room for messages and respond to them ought to ignore m.notice messages. This helps to prevent infinite-loop situations where two automated clients continuously exchange messages, as each responds to the other.",
     "allOf": [{
-        "$ref": "core-event-schema/room_event.json"
+        "$ref": "core-event-schema/room_event.yaml"
     }],
     "properties": {
         "content": {
diff --git a/event-schemas/schema/m.room.message#m.text b/event-schemas/schema/m.room.message#m.text
index de59cf0e..0b638113 100644
--- a/event-schemas/schema/m.room.message#m.text
+++ b/event-schemas/schema/m.room.message#m.text
@@ -3,7 +3,7 @@
     "title": "TextMessage",
     "description": "This message is the most basic message and is used to represent text.",
     "allOf": [{
-        "$ref": "core-event-schema/room_event.json"
+        "$ref": "core-event-schema/room_event.yaml"
     }],
     "properties": {
         "content": {
diff --git a/event-schemas/schema/m.room.message#m.video b/event-schemas/schema/m.room.message#m.video
index ad68e72a..6381543f 100644
--- a/event-schemas/schema/m.room.message#m.video
+++ b/event-schemas/schema/m.room.message#m.video
@@ -3,7 +3,7 @@
     "title": "VideoMessage",
     "description": "This message represents a single video clip.",
     "allOf": [{
-        "$ref": "core-event-schema/room_event.json"
+        "$ref": "core-event-schema/room_event.yaml"
     }],
     "properties": {
         "content": {
@@ -54,7 +54,7 @@
                             "type": "object",
                             "title": "ImageInfo",
                             "allOf": [{
-                                "$ref": "core-event-schema/msgtype_infos/image_info.json"
+                                "$ref": "core-event-schema/msgtype_infos/image_info.yaml"
                             }]
                         }
                     }
diff --git a/event-schemas/schema/m.room.message.feedback b/event-schemas/schema/m.room.message.feedback
index 2eaed999..38e5ce05 100644
--- a/event-schemas/schema/m.room.message.feedback
+++ b/event-schemas/schema/m.room.message.feedback
@@ -3,7 +3,7 @@
     "title": "MessageFeedback",
     "description": "**NB: Usage of this event is discouraged in favour of the** `receipts module`_. **Most clients will not recognise this event.** Feedback events are events sent to acknowledge a message in some way. There are two supported acknowledgements: ``delivered`` (sent when the event has been received) and ``read`` (sent when the event has been observed by the end-user). The ``target_event_id`` should reference the ``m.room.message`` event being acknowledged.",
     "allOf": [{
-        "$ref": "core-event-schema/room_event.json"
+        "$ref": "core-event-schema/room_event.yaml"
     }],
     "properties": {
         "content": {
diff --git a/event-schemas/schema/m.room.name b/event-schemas/schema/m.room.name
index 0e0b25be..9a21c26f 100644
--- a/event-schemas/schema/m.room.name
+++ b/event-schemas/schema/m.room.name
@@ -3,7 +3,7 @@
     "description": "A room has an opaque room ID which is not human-friendly to read. A room alias is human-friendly, but not all rooms have room aliases. The room name is a human-friendly string designed to be displayed to the end-user. The room name is not unique, as multiple rooms can have the same room name set. The room name can also be set when creating a room using ``/createRoom`` with the ``name`` key.",
     "type": "object",
     "allOf": [{
-        "$ref": "core-event-schema/state_event.json"
+        "$ref": "core-event-schema/state_event.yaml"
     }],
     "properties": {
         "content": {
diff --git a/event-schemas/schema/m.room.power_levels b/event-schemas/schema/m.room.power_levels
index 2ef3bfa3..e9082b7f 100644
--- a/event-schemas/schema/m.room.power_levels
+++ b/event-schemas/schema/m.room.power_levels
@@ -3,7 +3,7 @@
     "title": "Defines the power levels (privileges) of users in the room.",
     "description": "This event specifies the minimum level a user must have in order to perform a certain action. It also specifies the levels of each user in the room. If a ``user_id`` is in the ``users`` list, then that ``user_id`` has the associated power level. Otherwise they have the default level ``users_default``. If ``users_default`` is not supplied, it is assumed to be 0. The level required to send a certain event is governed by ``events``, ``state_default`` and ``events_default``. If an event type is specified in ``events``, then the user must have at least the level specified in order to send that event. If the event type is not supplied, it defaults to ``events_default`` for Message Events and ``state_default`` for State Events.",
     "allOf": [{
-        "$ref": "core-event-schema/state_event.json"
+        "$ref": "core-event-schema/state_event.yaml"
     }],
     "properties": {
         "content": {
diff --git a/event-schemas/schema/m.room.redaction b/event-schemas/schema/m.room.redaction
index 5c3ef391..173969f4 100644
--- a/event-schemas/schema/m.room.redaction
+++ b/event-schemas/schema/m.room.redaction
@@ -3,7 +3,7 @@
     "title": "Redaction",
     "description": "Events can be redacted by either room or server admins. Redacting an event means that all keys not required by the protocol are stripped off, allowing admins to remove offensive or illegal content that may have been attached to any event. This cannot be undone, allowing server owners to physically delete the offending data.  There is also a concept of a moderator hiding a message event, which can be undone, but cannot be applied to state events. The event that has been redacted is specified in the ``redacts`` event level key.",
     "allOf": [{
-        "$ref": "core-event-schema/room_event.json"
+        "$ref": "core-event-schema/room_event.yaml"
     }],
     "properties": {
         "content": {
diff --git a/event-schemas/schema/m.room.third_party_invite b/event-schemas/schema/m.room.third_party_invite
index ba66100f..cc11fe09 100644
--- a/event-schemas/schema/m.room.third_party_invite
+++ b/event-schemas/schema/m.room.third_party_invite
@@ -4,7 +4,7 @@
     "title": "An invitation to a room issued to a third party identifier, rather than a matrix user ID.",
     "description": "Acts as an ``m.room.member`` invite event, where there isn't a target user_id to invite. This event contains a token and a public key whose private key must be used to sign the token. Any user who can present that signature may use this invitation to join the target room.",
     "allOf": [{
-        "$ref": "core-event-schema/state_event.json"
+        "$ref": "core-event-schema/state_event.yaml"
     }],
     "properties": {
         "content": {
diff --git a/event-schemas/schema/m.room.topic b/event-schemas/schema/m.room.topic
index d13f0c23..dec649ea 100644
--- a/event-schemas/schema/m.room.topic
+++ b/event-schemas/schema/m.room.topic
@@ -3,7 +3,7 @@
     "title": "Topic",
     "description": "A topic is a short message detailing what is currently being discussed in the room.  It can also be used as a way to display extra information about the room, which may not be suitable for the room name. The room topic can also be set when creating a room using ``/createRoom`` with the ``topic`` key.",
     "allOf": [{
-        "$ref": "core-event-schema/state_event.json"
+        "$ref": "core-event-schema/state_event.yaml"
     }],
     "properties": {
         "content": {
diff --git a/templating/matrix_templates/units.py b/templating/matrix_templates/units.py
index e4caa54c..fcd3f7f9 100644
--- a/templating/matrix_templates/units.py
+++ b/templating/matrix_templates/units.py
@@ -24,8 +24,8 @@ CORE_EVENT_SCHEMA = "../event-schemas/schema/core-event-schema"
 CHANGELOG = "../CHANGELOG.rst"
 TARGETS = "../specification/targets.yaml"
 
-ROOM_EVENT = "core-event-schema/room_event.json"
-STATE_EVENT = "core-event-schema/state_event.json"
+ROOM_EVENT = "core-event-schema/room_event.yaml"
+STATE_EVENT = "core-event-schema/state_event.yaml"
 
 logger = logging.getLogger(__name__)
 
@@ -36,7 +36,7 @@ def resolve_references(path, schema):
             if key == "$ref":
                 path = os.path.join(os.path.dirname(path), value)
                 with open(path) as f:
-                    schema = json.load(f)
+                    schema = yaml.load(f)
                 return resolve_references(path, schema)
             else:
                 result[key] = resolve_references(path, value)
@@ -571,14 +571,14 @@ class MatrixUnits(Units):
 
         for (root, dirs, files) in os.walk(path):
             for filename in files:
-                if not filename.endswith(".json"):
+                if not filename.endswith(".yaml"):
                     continue
 
-                event_type = filename[:-5]  # strip the ".json"
+                event_type = filename[:-5]  # strip the ".yaml"
                 filepath = os.path.join(root, filename)
                 with open(filepath) as f:
                     try:
-                        event_info = json.load(f)
+                        event_info = yaml.load(f)
                     except Exception as e:
                         raise ValueError(
                             "Error reading file %r" % (filepath,), e
@@ -631,7 +631,7 @@ class MatrixUnits(Units):
             filepath = os.path.join(path, filename)
             self.log("Reading %s" % filepath)
             with open(filepath, "r") as f:
-                json_schema = json.loads(f.read())
+                json_schema = yaml.load(f)
                 schema = {
                     "typeof": None,
                     "typeof_info": "",