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 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.

Custom x-weight key

This property allows controlling the display order of events rendered with the event-group shortcode.