matrix-spec/openapi_extensions.md

# OpenAPI Extensions

For some functionality that is not directly provided by the OpenAPI v3.1
specification, some extensions have been added that are to be consistent
across the specification. The defined extensions are listed below. Extensions
should not break parsers, however if extra functionality is required, aware
parsers should be able to take advantage of the added syntax.

## Using multiple files to describe API

To ease API design and management, the API definition is split across several
files. Each of these files is self-contained valid OpenAPI.

There is no single root file in the source tree as OpenAPI requires; this file
can be generated by `dump-openapi.py`. The script does not convert
the extensions described further in this document so there can be minor
interoperability issues with tooling that expects compliant OpenAPI.

## Custom `x-addedInMatrixVersion` key

This property is added throughout the OpenAPI schemas to denote which version
of the Matrix specification added the associated object (endpoint, parameter,
property, etc).

## Custom `x-changedInMatrixVersion` key

A variation of the above: indicates changes to the associated parameter in
particular Matrix specification versions.

## Use of `$ref` inside examples

Although the OpenAPI/JSON Schema specs only allow to use `$ref` to reference a
whole example, we use it to compose examples from other examples.

## Custom `x-pattern-format` key and custom formats 

In JSON Schema, [`format`](https://json-schema.org/understanding-json-schema/reference/string#format)
is a property to convey semantic information about a schema. We define
`x-pattern-format` as a key on the schemas under `patternProperties` with the
same use as `format`, but that applies to the pattern of the property. We also
define custom values for formats with the `mx-` prefix in
`data/custom-formats.yaml`. Those values are recognized in the rendered
specification and link to the definition of the format.