archive
/
matrix-spec-proposals
mirror of https://github.com/matrix-org/matrix-spec-proposals
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add raw API end event schemas into /data directory

Browse Source
anoa/support-rendered-data
Will 3 years ago
parent 636974948d
commit 91ab39343b
No known key found for this signature in database
GPG Key ID: 385872BB265E8BF8
463 changed files with 39775 additions and 0 deletions
Show Stats Download Patch File Download Diff File

2
data/api/README
Unescape Escape View File

@ -0,0 +1,2 @@
This directory contains swagger-compatible representations of our APIs. See
the main README.rst for details on how to make use of them.

32
data/api/application-service/definitions/location.yaml
Unescape Escape View File

@ -0,0 +1,32 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
properties:
alias:
description: An alias for a matrix room.
type: string
example: "#freenode_#matrix:matrix.org"
protocol:
description: The protocol ID that the third party location is a part of.
type: string
example: "irc"
fields:
description: Information used to identify this third party location.
type: object
example: {
"network": "freenode",
"channel": "#matrix"
}
required: ['alias', 'protocol', 'fields']
title: Location
type: object

17
data/api/application-service/definitions/location_batch.yaml
Unescape Escape View File

@ -0,0 +1,17 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: array
description: List of matched third party locations.
items:
$ref: location.yaml

113
data/api/application-service/definitions/protocol.yaml
Unescape Escape View File

@ -0,0 +1,113 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
title: Protocol
type: object
properties:
user_fields:
description: |-
Fields which may be used to identify a third party user. These should be
ordered to suggest the way that entities may be grouped, where higher
groupings are ordered first. For example, the name of a network should be
searched before the nickname of a user.
type: array
items:
type: string
description: Field used to identify a third party user.
example: ["network", "nickname"]
location_fields:
description: |-
Fields which may be used to identify a third party location. These should be
ordered to suggest the way that entities may be grouped, where higher
groupings are ordered first. For example, the name of a network should be
searched before the name of a channel.
type: array
items:
type: string
description: Field used to identify a third party location.
example: ["network", "channel"]
icon:
description: A content URI representing an icon for the third party protocol.
type: string
example: "mxc://example.org/aBcDeFgH"
field_types:
title: Field Types
description: |-
The type definitions for the fields defined in the ``user_fields`` and
``location_fields``. Each entry in those arrays MUST have an entry here. The
``string`` key for this object is field name itself.
May be an empty object if no fields are defined.
type: object
additionalProperties:
title: Field Type
description: Definition of valid values for a field.
type: object
properties:
regexp:
description: |-
A regular expression for validation of a field's value. This may be relatively
coarse to verify the value as the application service providing this protocol
may apply additional validation or filtering.
type: string
placeholder:
description: An placeholder serving as a valid example of the field value.
type: string
required: ['regexp', 'placeholder']
required: ['fieldname']
example: {
"network": {
"regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
"placeholder": "irc.example.org"
},
"nickname": {
"regexp": "[^\\s#]+",
"placeholder": "username"
},
"channel": {
"regexp": "#[^\\s]+",
"placeholder": "#foobar"
}
}
instances:
description: |-
A list of objects representing independent instances of configuration.
For example, multiple networks on IRC if multiple are provided by the
same application service.
type: array
items:
type: object
title: Protocol Instance
properties:
desc:
type: string
description: A human-readable description for the protocol, such as the name.
example: "Freenode"
icon:
type: string
description: |-
An optional content URI representing the protocol. Overrides the one provided
at the higher level Protocol object.
example: "mxc://example.org/JkLmNoPq"
fields:
type: object
description: Preset values for ``fields`` the client may use to search by.
example: {
"network": "freenode"
}
network_id:
type: string
description: A unique identifier across all instances.
example: "freenode"
required: ['desc', 'fields', 'network_id']
required: ['user_fields', 'location_fields', 'icon', 'field_types', 'instances']

70
data/api/application-service/definitions/protocol_metadata.yaml
Unescape Escape View File

@ -0,0 +1,70 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
description: Dictionary of supported third party protocols.
additionalProperties:
$ref: protocol.yaml
example: {
"irc": {
"user_fields": ["network", "nickname"],
"location_fields": ["network", "channel"],
"icon": "mxc://example.org/aBcDeFgH",
"field_types": {
"network": {
"regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
"placeholder": "irc.example.org"
},
"nickname": {
"regexp": "[^\\s]+",
"placeholder": "username"
},
"channel": {
"regexp": "#[^\\s]+",
"placeholder": "#foobar"
}
},
"instances": [
{
"network_id": "freenode",
"desc": "Freenode",
"icon": "mxc://example.org/JkLmNoPq",
"fields": {
"network": "freenode.net",
}
}
]
},
"gitter": {
"user_fields": ["username"],
"location_fields": ["room"],
"field_types": {
"username": {
"regexp": "@[^\\s]+",
"placeholder": "@username"
},
"room": {
"regexp": "[^\\s]+\\/[^\\s]+",
"placeholder": "matrix-org/matrix-doc"
}
},
"instances": [
{
"network_id": "gitter",
"desc": "Gitter",
"icon": "mxc://example.org/zXyWvUt",
"fields": {}
}
]
}
}

18
data/api/application-service/definitions/security.yaml
Unescape Escape View File

@ -0,0 +1,18 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
homeserverAccessToken:
type: apiKey
description: The ``hs_token`` provided by the application service's registration.
name: access_token
in: query

33
data/api/application-service/definitions/user.yaml
Unescape Escape View File

@ -0,0 +1,33 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# TODO: Change userid to user_id as a breaking change
properties:
userid:
description: A Matrix User ID represting a third party user.
type: string
example: "@_gitter_jim:matrix.org"
protocol:
description: The protocol ID that the third party location is a part of.
type: string
example: "gitter"
fields:
description: Information used to identify this third party location.
type: object
example: {
"user": "jim"
}
required: ['userid', 'protocol', 'fields']
title: User
type: object

17
data/api/application-service/definitions/user_batch.yaml
Unescape Escape View File

@ -0,0 +1,17 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: array
description: List of matched third party users.
items:
$ref: user.yaml

279
data/api/application-service/protocols.yaml
Unescape Escape View File

@ -0,0 +1,279 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Application Service API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/app/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/thirdparty/protocol/{protocol}":
get:
summary: Retrieve metadata about a specific protocol that the application service supports.
description: |-
This API is called by the homeserver when it wants to present clients
with specific information about the various third party networks that
an application service supports.
operationId: getProtocolMetadata
security:
- homeserverAccessToken: []
parameters:
- in: path
name: protocol
type: string
description: The protocol ID.
required: true
x-example: "irc"
responses:
200:
description: The protocol was found and metadata returned.
schema:
$ref: definitions/protocol_metadata.yaml
401:
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No protocol was found with the given path.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/thirdparty/user/{protocol}":
get:
summary: Retrieve the Matrix User ID of a corresponding third party user.
description: |-
This API is called by the homeserver in order to retrieve a Matrix
User ID linked to a user on the third party network, given a set of
user parameters.
operationId: queryUserByProtocol
security:
- homeserverAccessToken: []
parameters:
- in: path
name: protocol
type: string
description: The protocol ID.
required: true
x-example: irc
- in: query
name: fields...
type: string
description: |-
One or more custom fields that are passed to the application
service to help identify the user.
responses:
200:
description: The Matrix User IDs found with the given parameters.
schema:
$ref: definitions/user_batch.yaml
401:
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No users were found with the given parameters.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/thirdparty/location/{protocol}":
get:
summary: Retrieve Matrix-side portal rooms leading to a third party location.
description: |-
Retrieve a list of Matrix portal rooms that lead to the matched third party location.
operationId: queryLocationByProtocol
security:
- homeserverAccessToken: []
parameters:
- in: path
name: protocol
type: string
description: The protocol ID.
required: true
x-example: irc
- in: query
name: fields...
type: string
description: |-
One or more custom fields that are passed to the application
service to help identify the third party location.
responses:
200:
description: At least one portal room was found.
schema:
$ref: definitions/location_batch.yaml
401:
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No mappings were found with the given parameters.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/thirdparty/location":
get:
summary: Reverse-lookup third party locations given a Matrix room alias.
description: |-
Retrieve an array of third party network locations from a Matrix room
alias.
operationId: queryLocationByAlias
security:
- homeserverAccessToken: []
parameters:
- in: query
name: alias
type: string
description: The Matrix room alias to look up.
responses:
200:
description: |-
All found third party locations.
schema:
$ref: definitions/location_batch.yaml
401:
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No mappings were found with the given parameters.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/thirdparty/user":
get:
summary: Reverse-lookup third party users given a Matrix User ID.
description: |-
Retrieve an array of third party users from a Matrix User ID.
operationId: queryUserByID
security:
- homeserverAccessToken: []
parameters:
- in: query
name: userid
type: string
description: The Matrix User ID to look up.
responses:
200:
description: |-
An array of third party users.
schema:
$ref: definitions/user_batch.yaml
401:
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No mappings were found with the given parameters.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml

90
data/api/application-service/query_room.yaml
Unescape Escape View File

@ -0,0 +1,90 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Application Service API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/app/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/rooms/{roomAlias}":
get:
summary: Query if a room alias should exist on the application service.
description: |-
This endpoint is invoked by the homeserver on an application service to query
the existence of a given room alias. The homeserver will only query room
aliases inside the application service's ``aliases`` namespace. The
homeserver will send this request when it receives a request to join a
room alias within the application service's namespace.
operationId: queryRoomByAlias
security:
- homeserverAccessToken: []
parameters:
- in: path
name: roomAlias
type: string
description: The room alias being queried.
required: true
x-example: "#magicforest:example.com"
responses:
200:
description: |-
The application service indicates that this room alias exists. The
application service MUST have created a room and associated it with
the queried room alias using the client-server API. Additional
information about the room such as its name and topic can be set
before responding.
examples:
application/json: {}
schema:
type: object
401:
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
description: |-
The application service indicates that this room alias does not exist.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml

87
data/api/application-service/query_user.yaml
Unescape Escape View File

@ -0,0 +1,87 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Application Service API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/app/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/users/{userId}":
get:
summary: Query if a user should exist on the application service.
description: |-
This endpoint is invoked by the homeserver on an application service to query
the existence of a given user ID. The homeserver will only query user IDs
inside the application service's ``users`` namespace. The homeserver will
send this request when it receives an event for an unknown user ID in
the application service's namespace, such as a room invite.
operationId: queryUserById
security:
- homeserverAccessToken: []
parameters:
- in: path
name: userId
type: string
description: The user ID being queried.
required: true
x-example: "@alice:example.com"
responses:
200:
description: |-
The application service indicates that this user exists. The application
service MUST create the user using the client-server API.
examples:
application/json: {}
schema:
type: object
401:
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
description: |-
The application service indicates that this user does not exist.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml

77
data/api/application-service/transactions.yaml
Unescape Escape View File

@ -0,0 +1,77 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Application Service API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/app/v1
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/transactions/{txnId}":
put:
summary: Send some events to the application service.
description: |-
This API is called by the homeserver when it wants to push an event
(or batch of events) to the application service.
Note that the application service should distinguish state events
from message events via the presence of a ``state_key``, rather than
via the event type.
operationId: sendTransaction
security:
- homeserverAccessToken: []
parameters:
- in: path
name: txnId
type: string
description: |-
The transaction ID for this set of events. Homeservers generate
these IDs and they are used to ensure idempotency of requests.
required: true
x-example: "35"
- in: body
name: body
description: Transaction information
schema:
type: object
example: {
"events": [
{"$ref": "../../event-schemas/examples/m.room.member"},
{"$ref": "../../event-schemas/examples/m.room.message$m.text"}
]
}
properties:
events:
type: array
description: |-
A list of events, formatted as per the Client-Server API.
items:
type: object
title: Event
required: ["events"]
responses:
200:
description: The transaction was processed successfully.
examples:
application/json: {}
schema:
type: object

157
data/api/check_examples.py
Unescape Escape View File

@ -0,0 +1,157 @@
#! /usr/bin/env python
#
# Copyright 2016 OpenMarket Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
import sys
import json
import os
def import_error(module, package, debian, error):
sys.stderr.write((
"Error importing %(module)s: %(error)r\n"
"To install %(module)s run:\n"
" pip install %(package)s\n"
"or on Debian run:\n"
" sudo apt-get install python-%(debian)s\n"
) % locals())
if __name__ == '__main__':
sys.exit(1)
try:
import jsonschema
except ImportError as e:
import_error("jsonschema", "jsonschema", "jsonschema", e)
raise
try:
import yaml
except ImportError as e:
import_error("yaml", "PyYAML", "yaml", e)
raise
def check_schema(filepath, example, schema):
example = resolve_references(filepath, example)
schema = resolve_references(filepath, schema)
resolver = jsonschema.RefResolver(filepath, schema, handlers={"file": load_file})
jsonschema.validate(example, schema, resolver=resolver)
def check_parameter(filepath, request, parameter):
schema = parameter.get("schema")
example = schema.get('example')
if example and schema:
try:
print("Checking request schema for: %r %r" % (
filepath, request
))
check_schema(filepath, example, schema)
except Exception as e:
raise ValueError("Error validating JSON schema for %r" % (
request
), e)
def check_response(filepath, request, code, response):
example = response.get('examples', {}).get('application/json')
schema = response.get('schema')
if example and schema:
try:
print ("Checking response schema for: %r %r %r" % (
filepath, request, code
))
check_schema(filepath, example, schema)
except jsonschema.SchemaError as error:
for suberror in sorted(error.context, key=lambda e: e.schema_path):
print(list(suberror.schema_path), suberror.message, sep=", ")
raise ValueError("Error validating JSON schema for %r %r" % (
request, code
), e)
except Exception as e:
raise ValueError("Error validating JSON schema for %r %r" % (
request, code
), e)
def check_swagger_file(filepath):
with open(filepath) as f:
swagger = yaml.load(f)
for path, path_api in swagger.get('paths', {}).items():
for method, request_api in path_api.items():
request = "%s %s" % (method.upper(), path)
for parameter in request_api.get('parameters', ()):
if parameter['in'] == 'body':
check_parameter(filepath, request, parameter)
try:
responses = request_api['responses']
except KeyError:
raise ValueError("No responses for %r" % (request,))
for code, response in responses.items():
check_response(filepath, request, code, response)
def resolve_references(path, schema):
if isinstance(schema, dict):
# do $ref first
if '$ref' in schema:
value = schema['$ref']
path = os.path.abspath(os.path.join(os.path.dirname(path), value))
ref = load_file("file://" + path)
result = resolve_references(path, ref)
del schema['$ref']
else:
result = {}
for key, value in schema.items():
result[key] = resolve_references(path, value)
return result
elif isinstance(schema, list):
return [resolve_references(path, value) for value in schema]
else:
return schema
def load_file(path):
print("Loading reference: %s" % path)
if not path.startswith("file://"):
raise Exception("Bad ref: %s" % (path,))
path = path[len("file://"):]
with open(path, "r") as f:
if path.endswith(".json"):
return json.load(f)
else:
# We have to assume it's YAML because some of the YAML examples
# do not have file extensions.
return yaml.load(f)
if __name__ == '__main__':
paths = sys.argv[1:]
if not paths:
paths = []
for (root, dirs, files) in os.walk(os.curdir):
for filename in files:
if filename.endswith(".yaml"):
paths.append(os.path.join(root, filename))
for path in paths:
try:
check_swagger_file(path)
except Exception as e:
raise ValueError("Error checking file %r" % (path,), e)

197
data/api/client-server/account-data.yaml
Unescape Escape View File

@ -0,0 +1,197 @@
# Copyright 2016 OpenMarket Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Client-Server Client Config API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/user/{userId}/account_data/{type}":
put:
summary: Set some account_data for the user.
description: |-
Set some account_data for the client. This config is only visible to the user
that set the account_data. The config will be synced to clients in the
top-level ``account_data``.
operationId: setAccountData
security:
- accessToken: []
parameters:
- in: path
type: string
name: userId
required: true
description: |-
The ID of the user to set account_data for. The access token must be
authorized to make requests for this user ID.
x-example: "@alice:example.com"
- in: path
type: string
name: type
required: true
description: |-
The event type of the account_data to set. Custom types should be
namespaced to avoid clashes.
x-example: "org.example.custom.config"
- in: body
name: content
required: true
description: |-
The content of the account_data
schema:
type: object
example: {
"custom_account_data_key": "custom_config_value"}
responses:
200:
description:
The account_data was successfully added.
tags:
- User data
get:
summary: Get some account_data for the user.
description: |-
Get some account_data for the client. This config is only visible to the user
that set the account_data.
operationId: getAccountData
security:
- accessToken: []
parameters:
- in: path
type: string
name: userId
required: true
description: |-
The ID of the user to get account_data for. The access token must be
authorized to make requests for this user ID.
x-example: "@alice:example.com"
- in: path
type: string
name: type
required: true
description: |-
The event type of the account_data to get. Custom types should be
namespaced to avoid clashes.
x-example: "org.example.custom.config"
responses:
200:
description:
The account data content for the given type.
schema:
type: object
example: {
"custom_account_data_key": "custom_config_value"}
tags:
- User data
"/user/{userId}/rooms/{roomId}/account_data/{type}":
put:
summary: Set some account_data for the user.
description: |-
Set some account_data for the client on a given room. This config is only
visible to the user that set the account_data. The config will be synced to
clients in the per-room ``account_data``.
operationId: setAccountDataPerRoom
security:
- accessToken: []
parameters:
- in: path
type: string
name: userId
required: true
description: |-
The ID of the user to set account_data for. The access token must be
authorized to make requests for this user ID.
x-example: "@alice:example.com"
- in: path
type: string
name: roomId
required: true
description: |-
The ID of the room to set account_data on.
x-example: "!726s6s6q:example.com"
- in: path
type: string
name: type
required: true
description: |-
The event type of the account_data to set. Custom types should be
namespaced to avoid clashes.
x-example: "org.example.custom.room.config"
- in: body
name: content
required: true
description: |-
The content of the account_data
schema:
type: object
example: {
"custom_account_data_key": "custom_account_data_value"}
responses:
200:
description:
The account_data was successfully added.
tags:
- User data
get:
summary: Get some account_data for the user.
description: |-
Get some account_data for the client on a given room. This config is only
visible to the user that set the account_data.
operationId: getAccountDataPerRoom
security:
- accessToken: []
parameters:
- in: path
type: string
name: userId
required: true
description: |-
The ID of the user to set account_data for. The access token must be
authorized to make requests for this user ID.
x-example: "@alice:example.com"
- in: path
type: string
name: roomId
required: true
description: |-
The ID of the room to get account_data for.
x-example: "!726s6s6q:example.com"
- in: path
type: string
name: type
required: true
description: |-
The event type of the account_data to get. Custom types should be
namespaced to avoid clashes.
x-example: "org.example.custom.room.config"
responses:
200:
description:
The account data content for the given type.
schema:
type: object
example: {
"custom_account_data_key": "custom_config_value"}
tags:
- User data

115
data/api/client-server/admin.yaml
Unescape Escape View File

@ -0,0 +1,115 @@
# Copyright 2016 OpenMarket Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
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:
$ref: definitions/security.yaml
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.
operationId: getWhoIs
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 identifier 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: integer
format: int64
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

515
data/api/client-server/administrative_contact.yaml
Unescape Escape View File

@ -0,0 +1,515 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2019 The Matrix.org Foundation C.I.C.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Client-Server Account Administrative Contact API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/account/3pid":
get:
summary: Gets a list of a user's third party identifiers.
description: |-
Gets a list of the third party identifiers that the homeserver has
associated with the user's account.
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 homeserver as, for example,
identifiers that it will accept to reset the user's account password.
operationId: getAccount3PIDs
security:
- accessToken: []
responses:
200:
description: The lookup was successful.
examples:
application/json: {
"threepids": [
{
"medium": "email",
"address": "monkey@banana.island",
"validated_at": 1535176800000,
"added_at": 1535336848756
}
]
}
schema:
type: object
properties:
threepids:
type: array
items:
type: object
title: Third party identifier
properties:
medium:
type: string
description: The medium of the third party identifier.
enum: ["email", "msisdn"]
address:
type: string
description: The third party identifier address.
validated_at:
type: integer
format: int64
description: |-
The timestamp, in milliseconds, when the identifier was
validated by the identity server.
added_at:
type: integer
format: int64
description:
The timestamp, in milliseconds, when the homeserver
associated the third party identifier with the user.
required: ['medium', 'address', 'validated_at', 'added_at']
tags:
- User data
post:
summary: Adds contact information to the user's account.
description: |-
Adds contact information to the user's account.
This endpoint is deprecated in favour of the more specific ``/3pid/add``
and ``/3pid/bind`` endpoints.
.. Note::
Previously this endpoint supported a ``bind`` parameter. This parameter
has been removed, making this endpoint behave as though it was ``false``.
This results in this endpoint being an equivalent to ``/3pid/bind`` rather
than dual-purpose.
operationId: post3PIDs
deprecated: true
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
three_pid_creds:
title: "ThreePidCredentials"
type: object
description: The third party credentials to associate with the account.
properties:
client_secret:
type: string
description: The client secret used in the session with the identity server.
id_server:
type: string
description: The identity server to use.
id_access_token:
type: string
description: |-
An access token previously registered with the identity server. Servers
can treat this as optional to distinguish between r0.5-compatible clients
and this specification version.
sid:
type: string
description: The session identifier given by the identity server.
required: ["client_secret", "id_server", "id_access_token", "sid"]
required: ["three_pid_creds"]
example: {
"three_pid_creds": {
"id_server": "matrix.org",
"id_access_token": "abc123_OpaqueString",
"sid": "abc123987",
"client_secret": "d0n'tT3ll"
}
}
responses:
200:
description: The addition was successful.
examples:
application/json: {
"submit_url": "https://example.org/path/to/submitToken"
}
schema:
type: object
properties:
submit_url:
type: string
description: |-
An optional field containing a URL where the client must
submit the validation token to, with identical parameters
to the Identity Service API's ``POST
/validate/email/submitToken`` endpoint (without the requirement
for an access token). The homeserver must send this token to the
user (if applicable), who should then be prompted to provide it
to the client.
If this field is not present, the client can assume that
verification will happen without the client's involvement
provided the homeserver advertises this specification version
in the ``/versions`` response (ie: r0.5.0).
example: "https://example.org/path/to/submitToken"
403:
description: The credentials could not be verified with the identity server.
examples:
application/json: {
"errcode": "M_THREEPID_AUTH_FAILED",
"error": "The third party credentials could not be verified by the identity server."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- User data
"/account/3pid/add":
post:
summary: Adds contact information to the user's account.
description: |-
This API endpoint uses the `User-Interactive Authentication API`_.
Adds contact information to the user's account. Homeservers should use 3PIDs added
through this endpoint for password resets instead of relying on the identity server.
Homeservers should prevent the caller from adding a 3PID to their account if it has
already been added to another user's account on the homeserver.
operationId: add3PID
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
auth:
description: |-
Additional authentication information for the
user-interactive authentication API.
allOf:
- $ref: "definitions/auth_data.yaml"
client_secret:
type: string
description: The client secret used in the session with the homeserver.
sid:
type: string
description: The session identifier given by the homeserver.
required: ["client_secret", "sid"]
example: {
"sid": "abc123987",
"client_secret": "d0n'tT3ll"
}
responses:
200:
description: The addition was successful.
examples:
application/json: {}
schema:
type: object
401:
description: |-
The homeserver requires additional authentication information.
schema:
"$ref": "definitions/auth_response.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
"/account/3pid/bind":
post:
summary: Binds a 3PID to the user's account through an Identity Service.
description: |-
Binds a 3PID to the user's account through the specified identity server.
Homeservers should not prevent this request from succeeding if another user
has bound the 3PID. Homeservers should simply proxy any errors received by
the identity server to the caller.
Homeservers should track successful binds so they can be unbound later.
operationId: bind3PID
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
client_secret:
type: string
description: The client secret used in the session with the identity server.
id_server:
type: string
description: The identity server to use.
id_access_token:
type: string
description: |-
An access token previously registered with the identity server.
sid:
type: string
description: The session identifier given by the identity server.
required: ["client_secret", "id_server", "id_access_token", "sid"]
example: {
"id_server": "example.org",
"id_access_token": "abc123_OpaqueString",
"sid": "abc123987",
"client_secret": "d0n'tT3ll"
}
responses:
200:
description: The addition was successful.
examples:
application/json: {}
schema:
type: object
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data
"/account/3pid/delete":
post:
summary: Deletes a third party identifier from the user's account
description: |-
Removes a third party identifier from the user's account. This might not
cause an unbind of the identifier from the identity server.
Unlike other endpoints, this endpoint does not take an ``id_access_token``
parameter because the homeserver is expected to sign the request to the
identity server instead.
operationId: delete3pidFromAccount
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
id_server:
type: string
description: |-
The identity server to unbind from. If not provided, the homeserver
MUST use the ``id_server`` the identifier was added through. If the
homeserver does not know the original ``id_server``, it MUST return
a ``id_server_unbind_result`` of ``no-support``.
example: "example.org"
medium:
type: string
description: The medium of the third party identifier being removed.
enum: ["email", "msisdn"]
example: "email"
address:
type: string
description: The third party address being removed.
example: "example@example.org"
required: ['medium', 'address']
responses:
200:
description: |-
The homeserver has disassociated the third party identifier from the
user.
schema:
type: object
properties:
id_server_unbind_result:
type: string
enum:
# XXX: I don't know why, but the order matters here so that "no-support"
# doesn't become "no- support" by the renderer.
- "no-support"
- "success"
description: |-
An indicator as to whether or not the homeserver was able to unbind
the 3PID from the identity server. ``success`` indicates that the
indentity server has unbound the identifier whereas ``no-support``
indicates that the identity server refuses to support the request
or the homeserver was not able to determine an identity server to
unbind from.
example: "success"
required:
- id_server_unbind_result
tags:
- User data
"/account/3pid/unbind":
post:
summary: Removes a user's third party identifier from an identity server.
description: |-
Removes a user's third party identifier from the provided identity server
without removing it from the homeserver.
Unlike other endpoints, this endpoint does not take an ``id_access_token``
parameter because the homeserver is expected to sign the request to the
identity server instead.
operationId: unbind3pidFromAccount
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
id_server:
type: string
description: |-
The identity server to unbind from. If not provided, the homeserver
MUST use the ``id_server`` the identifier was added through. If the
homeserver does not know the original ``id_server``, it MUST return
a ``id_server_unbind_result`` of ``no-support``.
example: "example.org"
medium:
type: string
description: The medium of the third party identifier being removed.
enum: ["email", "msisdn"]
example: "email"
address:
type: string
description: The third party address being removed.
example: "example@example.org"
required: ['medium', 'address']
responses:
200:
description: |-
The identity server has disassociated the third party identifier from the
user.
schema:
type: object
properties:
id_server_unbind_result:
type: string
enum:
# XXX: I don't know why, but the order matters here so that "no-support"
# doesn't become "no- support" by the renderer.
- "no-support"
- "success"
description: |-
An indicator as to whether or not the identity server was able to unbind
the 3PID. ``success`` indicates that the identity server has unbound the
identifier whereas ``no-support`` indicates that the identity server
refuses to support the request or the homeserver was not able to determine
an identity server to unbind from.
example: "success"
required:
- id_server_unbind_result
tags:
- User data
"/account/3pid/email/requestToken":
post:
summary: Begins the validation process for an email address for association with the user's account.
description: |-
The homeserver must check that the given email address is **not**
already associated with an account on this homeserver. This API should
be used to request validation tokens when adding an email address to an
account. This API's parameters and response are identical to that of
the |/register/email/requestToken|_ endpoint. The homeserver should validate
the email itself, either by sending a validation email itself or by using
a service it has control over.
operationId: requestTokenTo3PIDEmail
parameters:
- in: body
name: body
required: true
schema:
$ref: "definitions/request_email_validation.yaml"
responses:
200:
description: |-
An email was sent to the given address. Note that this may be an
email containing the validation token or it may be informing the
user of an error.
schema:
$ref: "definitions/request_token_response.yaml"
403:
description: |-
The homeserver does not allow the third party identifier as a
contact option.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third party identifier is not allowed"
}
400:
description: |-
The third party identifier is already in use on the homeserver, or
the request was invalid. The error code ``M_SERVER_NOT_TRUSTED``
can be returned if the server does not trust/support the identity server
provided in the request.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_IN_USE",
"error": "Third party identifier already in use"
}
"/account/3pid/msisdn/requestToken":
post:
summary: Begins the validation process for a phone number for association with the user's account.
description: |-
The homeserver must check that the given phone number is **not**
already associated with an account on this homeserver. This API should
be used to request validation tokens when adding a phone number to an
account. This API's parameters and response are identical to that of
the |/register/msisdn/requestToken|_ endpoint. The homeserver should validate
the phone number itself, either by sending a validation message itself or by using
a service it has control over.
operationId: requestTokenTo3PIDMSISDN
parameters:
- in: body
name: body
required: true
schema:
$ref: "definitions/request_msisdn_validation.yaml"
responses:
200:
description: An SMS message was sent to the given phone number.
schema:
$ref: "definitions/request_token_response.yaml"
403:
description: |-
The homeserver does not allow the third party identifier as a
contact option.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_DENIED",
"error": "Third party identifier is not allowed"
}
400:
description: |-
The third party identifier is already in use on the homeserver, or
the request was invalid. The error code ``M_SERVER_NOT_TRUSTED``
can be returned if the server does not trust/support the identity server
provided in the request.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_THREEPID_IN_USE",
"error": "Third party identifier already in use"
}

88
data/api/client-server/appservice_room_directory.yaml
Unescape Escape View File

@ -0,0 +1,88 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Client-Server Application Service Room Directory API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
- application/json
securityDefinitions:
# Note: this is the same access_token definition used elsewhere in the client
# server API, however this expects an access token for an application service.
$ref: definitions/security.yaml
paths:
"/directory/list/appservice/{networkId}/{roomId}":
put:
summary: |-
Updates a room's visibility in the application service's room directory.
description: |-
Updates the visibility of a given room on the application service's room
directory.
This API is similar to the room directory visibility API used by clients
to update the homeserver's more general room directory.
This API requires the use of an application service access token (``as_token``)
instead of a typical client's access_token. This API cannot be invoked by
users who are not identified as application services.
operationId: updateAppserviceRoomDirectoryVsibility
parameters:
- in: path
type: string
name: networkId
description: |-
The protocol (network) ID to update the room list for. This would
have been provided by the application service as being listed as
a supported protocol.
required: true
x-example: "irc"
- in: path
type: string
name: roomId
description: The room ID to add to the directory.
required: true
x-example: "!somewhere:example.org"
- in: body
name: body
required: true
schema:
type: object
properties:
visibility:
type: string
enum: ["public", "private"]
description: |-
Whether the room should be visible (public) in the directory
or not (private).
example: "public"
required: ['visibility']
security:
# again, this is the appservice's token - not a typical client's
- accessToken: []
responses:
200:
description: The room's directory visibility has been updated.
schema:
type: object
examples:
application/json: {}
tags:
- Application service room directory management

148
data/api/client-server/banning.yaml
Unescape Escape View File

@ -0,0 +1,148 @@
# Copyright 2016 OpenMarket Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Client-Server Room Banning API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/rooms/{roomId}/ban":
post:
summary: Ban a user in the room.
description: |-
Ban a user in the room. If the user is currently in the room, also kick them.
When a user is banned from a room, they may not join it or be invited to it until they are unbanned.
The caller must have the required power level in order to perform this operation.
operationId: ban
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room identifier (not alias) from which the user should be banned.
required: true
x-example: "!e42d8c:matrix.org"
- in: body
name: body
required: true
schema:
type: object
example: {
"reason": "Telling unfunny jokes",
"user_id": "@cheeky_monkey:matrix.org"
}
properties:
user_id:
type: string
description: The fully qualified user ID of the user being banned.
reason:
type: string
description: The reason the user has been banned. This will be supplied as the
``reason`` on the target's updated `m.room.member`_ event.
required: ["user_id"]
responses:
200:
description: The user has been kicked and banned from the room.
examples:
application/json: {
}
schema:
type: object
403:
description: |-
You do not have permission to ban the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
- The banner is not currently in the room.
- The banner's power level is insufficient to ban users from the room.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to ban from this room."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room membership
"/rooms/{roomId}/unban":
post:
summary: Unban a user from the room.
description: |-
Unban a user from the room. This allows them to be invited to the room,
and join if they would otherwise be allowed to join according to its join rules.
The caller must have the required power level in order to perform this operation.
operationId: unban
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room identifier (not alias) from which the user should be unbanned.
required: true
x-example: "!e42d8c:matrix.org"
- in: body
name: body
required: true
schema:
type: object
example: {
"user_id": "@cheeky_monkey:matrix.org",
"reason": "They've been banned long enough"
}
properties:
user_id:
type: string
description: The fully qualified user ID of the user being unbanned.
reason:
type: string
description: |-
Optional reason to be included as the ``reason`` on the subsequent
membership event.
required: ["user_id"]
responses:
200:
description: The user has been unbanned from the room.
examples:
application/json: {
}
schema:
type: object
403:
description: |-
You do not have permission to unban the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
- The unbanner's power level is insufficient to unban users from the room.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to unban from this room."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room membership

112
data/api/client-server/capabilities.yaml
Unescape Escape View File

@ -0,0 +1,112 @@
# Copyright 2019 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Client-Server Capabilities API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/capabilities":
get:
summary: Gets information about the server's capabilities.
description: |-
Gets information about the server's supported feature set
and other relevant capabilities.
operationId: getCapabilities
security:
- accessToken: []
parameters: []
responses:
200:
description:
The capabilities of the server.
examples:
application/json: {
"capabilities": {
"m.change_password": {
"enabled": false
},
"m.room_versions": {
"default": "1",
"available": {
"1": "stable",
"2": "stable",
"3": "unstable",
"test-version": "unstable"
}
},
"com.example.custom.ratelimit": {
"max_requests_per_hour": 600
}
}
}
schema:
type: object
required: ["capabilities"]
properties:
capabilities:
type: object
title: Capabilities
description: |-
The custom capabilities the server supports, using the
Java package naming convention.
additionalProperties:
type: object
properties:
"m.change_password":
type: object
description: |-
Capability to indicate if the user can change their password.
title: ChangePasswordCapability
properties:
enabled:
type: boolean
description: |-
True if the user can change their password, false otherwise.
example: false
required: ['enabled']
"m.room_versions":
type: object
description: The room versions the server supports.
title: RoomVersionsCapability
properties:
default:
type: string
description: |-
The default room version the server is using for new rooms.
example: "1"
available:
type: object
description: |-
A detailed description of the room versions the server supports.
additionalProperties:
type: string
title: RoomVersionStability
enum: [stable, unstable]
description: The stability of the room version.
required: ['default', 'available']
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Capabilities

451
data/api/client-server/content-repo.yaml
Unescape Escape View File

@ -0,0 +1,451 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2019 The Matrix.org Foundation C.I.C.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Client-Server Content Repository API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/media/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
- "*/*"
produces:
- application/json
- "*/*"
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/upload":
post:
summary: Upload some content to the content repository.
operationId: uploadContent
produces: ["application/json"]
security:
- accessToken: []
parameters:
- in: header
name: Content-Type
type: string
description: The content type of the file being uploaded
x-example: "application/pdf"
- in: query
type: string
x-example: "War and Peace.pdf"
name: filename
description: The name of the file being uploaded
- in: body
name: "<content>"
description: The content to be uploaded.
required: true
x-example: "<bytes>" # so the spec shows "<bytes>" without quotes.
schema:
type: string
example: "<bytes>"
format: byte
responses:
200:
description: The `MXC URI`_ for the uploaded content.
schema:
type: object
required: ["content_uri"]
properties:
content_uri:
type: string
description: "The `MXC URI`_ to the uploaded content."
examples:
application/json: {
"content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
}
403:
description: |-
The user does not have permission to upload the content. Some reasons for this error include:
- The server does not permit the file type.
- The user has reached a quota for uploaded content.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Cannot upload this content"
}
schema:
"$ref": "definitions/errors/error.yaml"
413:
description: |-
The uploaded content is too large for the server.
examples:
application/json: {
"errcode": "M_TOO_LARGE",
"error": "Cannot upload files larger than 100mb"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Media
"/download/{serverName}/{mediaId}":
get:
summary: "Download content from the content repository."
operationId: getContent
produces: ["*/*"]
parameters:
- in: path
type: string
name: serverName
x-example: matrix.org
required: true
description: |
The server name from the ``mxc://`` URI (the authoritory component)
- in: path
type: string
name: mediaId
x-example: ascERGshawAWawugaAcauga
required: true
description: |
The media ID from the ``mxc://`` URI (the path component)
- in: query
type: boolean
name: allow_remote
x-example: false
required: false
default: true
description: |
Indicates to the server that it should not attempt to fetch the media if it is deemed
remote. This is to prevent routing loops where the server contacts itself. Defaults to
true if not provided.
responses:
200:
description: "The content that was previously uploaded."
headers:
Content-Type:
description: "The content type of the file that was previously uploaded."
type: "string"
Content-Disposition:
description: |-
The name of the file that was previously uploaded, if set.
type: "string"
schema:
type: file
# This is a workaround for us not being able to say the response is required.
description: "**Required.** The bytes for the uploaded file."
502:
description: |-
The content is too large for the server to serve.
examples:
application/json: {
"errcode": "M_TOO_LARGE",
"error": "Content is too large to serve"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Media
"/download/{serverName}/{mediaId}/{fileName}":
get:
summary: Download content from the content repository overriding the file name
description: |-
This will download content from the content repository (same as
the previous endpoint) but replace the target file name with the one
provided by the caller.
operationId: getContentOverrideName
produces: ["*/*"]
parameters:
- in: path
type: string
name: serverName
x-example: matrix.org
required: true
description: |
The server name from the ``mxc://`` URI (the authoritory component)
- in: path
type: string
name: mediaId
x-example: ascERGshawAWawugaAcauga
required: true
description: |
The media ID from the ``mxc://`` URI (the path component)
- in: path
type: string
name: fileName
x-example: filename.jpg
required: true
description: A filename to give in the ``Content-Disposition`` header.
- in: query
type: boolean
name: allow_remote
x-example: false
required: false
default: true
description: |
Indicates to the server that it should not attempt to fetch the media if it is deemed
remote. This is to prevent routing loops where the server contacts itself. Defaults to
true if not provided.
responses:
200:
description: "The content that was previously uploaded."
headers:
Content-Type:
description: "The content type of the file that was previously uploaded."
type: "string"
Content-Disposition:
description: |-
The ``fileName`` requested or the name of the file that was previously
uploaded, if set.
type: "string"
schema:
type: file
# This is a workaround for us not being able to say the response is required.
description: "**Required.** The bytes for the uploaded file."
502:
description: |-
The content is too large for the server to serve.
examples:
application/json: {
"errcode": "M_TOO_LARGE",
"error": "Content is too large to serve"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Media
"/thumbnail/{serverName}/{mediaId}":
get:
summary: Download a thumbnail of content from the content repository
description: |-
Download a thumbnail of content from the content repository.
See the `thumbnailing <#thumbnails>`_ section for more information.
operationId: getContentThumbnail
produces: ["image/jpeg", "image/png"]
parameters:
- in: path
type: string
name: serverName
required: true
x-example: example.org
description: |
The server name from the ``mxc://`` URI (the authoritory component)
- in: path
type: string
name: mediaId
x-example: ascERGshawAWawugaAcauga
required: true
description: |
The media ID from the ``mxc://`` URI (the path component)
- in: query
type: integer
x-example: 64
name: width
required: true
description: |-
The *desired* width of the thumbnail. The actual thumbnail may be
larger than the size specified.
- in: query
type: integer
x-example: 64
name: height
required: true
description: |-
The *desired* height of the thumbnail. The actual thumbnail may be
larger than the size specified.
- in: query
type: string
enum: ["crop", "scale"]
name: method
x-example: "scale"
description: |-
The desired resizing method. See the `thumbnailing <#thumbnails>`_
section for more information.
- in: query
type: boolean
name: allow_remote
x-example: false
required: false
default: true
description: |-
Indicates to the server that it should not attempt to fetch
the media if it is deemed remote. This is to prevent routing loops
where the server contacts itself. Defaults to true if not provided.
responses:
200:
description: "A thumbnail of the requested content."
headers:
Content-Type:
description: "The content type of the thumbnail."
type: "string"
enum: ["image/jpeg", "image/png"]
schema:
type: file
# This is a workaround for us not being able to say the response is required.
description: "**Required.** The bytes for the thumbnail."
400:
description: |-
The request does not make sense to the server, or the server cannot thumbnail
the content. For example, the client requested non-integer dimensions or asked
for negatively-sized images.
examples:
application/json: {
"errcode": "M_UNKNOWN",
"error": "Cannot generate thumbnails for the requested content"
}
schema:
"$ref": "definitions/errors/error.yaml"
413:
description: |-
The local content is too large for the server to thumbnail.
examples:
application/json: {
"errcode": "M_TOO_LARGE",
"error": "Content is too large to thumbnail"
}
schema:
"$ref": "definitions/errors/error.yaml"
502:
description: |-
The remote content is too large for the server to thumbnail.
examples:
application/json: {
"errcode": "M_TOO_LARGE",
"error": "Content is too large to thumbnail"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Media
"/preview_url":
get:
summary: "Get information about a URL for a client"
description: |-
Get information about a URL for the client. Typically this is called when a
client sees a URL in a message and wants to render a preview for the user.
.. Note::
Clients should consider avoiding this endpoint for URLs posted in encrypted
rooms. Encrypted rooms often contain more sensitive information the users
do not want to share with the homeserver, and this can mean that the URLs
being shared should also not be shared with the homeserver.
operationId: getUrlPreview
produces: ["application/json"]
security:
- accessToken: []
parameters:
- in: query
type: string
x-example: "https://matrix.org"
name: url
description: "The URL to get a preview of."
required: true
- in: query
type: integer
format: int64
x-example: 1510610716656
name: ts
description: |-
The preferred point in time to return a preview for. The server may
return a newer version if it does not have the requested version
available.
responses:
200:
description: |-
The OpenGraph data for the URL, which may be empty. Some values are
replaced with matrix equivalents if they are provided in the response.
The differences from the OpenGraph protocol are described here.
schema:
type: object
properties:
"matrix:image:size":
type: integer
format: int64
description: |-
The byte-size of the image. Omitted if there is no image attached.
"og:image":
type: string
description: |-
An `MXC URI`_ to the image. Omitted if there is no image.
examples:
application/json: {
"og:title": "Matrix Blog Post",
"og:description": "This is a really cool blog post from matrix.org",
"og:image": "mxc://example.com/ascERGshawAWawugaAcauga",
"og:image:type": "image/png",
"og:image:height": 48,
"og:image:width": 48,
"matrix:image:size": 102400
}
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Media
"/config":
get:
summary: Get the configuration for the content repository.
description: |-
This endpoint allows clients to retrieve the configuration of the content
repository, such as upload limitations.
Clients SHOULD use this as a guide when using content repository endpoints.
All values are intentionally left optional. Clients SHOULD follow
the advice given in the field description when the field is not available.
**NOTE:** Both clients and server administrators should be aware that proxies
between the client and the server may affect the apparent behaviour of content
repository APIs, for example, proxies may enforce a lower upload size limit
than is advertised by the server on this endpoint.
operationId: getConfig
produces: ["application/json"]
security:
- accessToken: []
responses:
200:
description: The public content repository configuration for the matrix server.
schema:
type: object
properties:
m.upload.size:
type: integer
format: int64
description: |-
The maximum size an upload can be in bytes.
Clients SHOULD use this as a guide when uploading content.
If not listed or null, the size limit should be treated as unknown.
examples:
application/json: {
"m.upload.size": 50000000
}
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Media

269
data/api/client-server/create_room.yaml
Unescape Escape View File

@ -0,0 +1,269 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Client-Server Room Creation API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/createRoom":
post:
summary: Create a new room
description: |-
Create a new room with various configuration options.
The server MUST apply the normal state resolution rules when creating
the new room, including checking power levels for each event. It MUST
apply the events implied by the request in the following order:
1. The ``m.room.create`` event itself. Must be the first event in the
room.
2. An ``m.room.member`` event for the creator to join the room. This is
needed so the remaining events can be sent.
3. A default ``m.room.power_levels`` event, giving the room creator
(and not other members) permission to send state events. Overridden
by the ``power_level_content_override`` parameter.
4. Events set by the ``preset``. Currently these are the ``m.room.join_rules``,
``m.room.history_visibility``, and ``m.room.guest_access`` state events.
5. Events listed in ``initial_state``, in the order that they are
listed.
6. Events implied by ``name`` and ``topic`` (``m.room.name`` and ``m.room.topic``
state events).
7. Invite events implied by ``invite`` and ``invite_3pid`` (``m.room.member`` with
``membership: invite`` and ``m.room.third_party_invite``).
The available presets do the following with respect to room state:
======================== ============== ====================== ================ =========
Preset ``join_rules`` ``history_visibility`` ``guest_access`` Other
======================== ============== ====================== ================ =========
``private_chat`` ``invite`` ``shared`` ``can_join``
``trusted_private_chat`` ``invite`` ``shared`` ``can_join`` All invitees are given the same power level as the room creator.
``public_chat`` ``public`` ``shared`` ``forbidden``
======================== ============== ====================== ================ =========
The server will create a ``m.room.create`` event in the room with the
requesting user as the creator, alongside other keys provided in the
``creation_content``.
operationId: createRoom
security:
- accessToken: []
parameters:
- in: body
name: body
description: The desired room configuration.
required: true
schema:
type: object
example: {
"preset": "public_chat",
"room_alias_name": "thepub",
"name": "The Grand Duke Pub",
"topic": "All about happy hour",
"creation_content": {
"m.federate": false
}
}
properties:
visibility:
type: string
enum: ["public", "private"]
description: |-
A ``public`` visibility indicates that the room will be shown
in the published room list. A ``private`` visibility will hide
the room from the published room list. Rooms default to
``private`` visibility if this key is not included. NB: This
should not be confused with ``join_rules`` which also uses the
word ``public``.
room_alias_name:
type: string
description: |-
The desired room alias **local part**. If this is included, a
room alias will be created and mapped to the newly created
room. The alias will belong on the *same* homeserver which
created the room. For example, if this was set to "foo" and
sent to the homeserver "example.com" the complete room alias
would be ``#foo:example.com``.
The complete room alias will become the canonical alias for
the room.
name:
type: string
description: |-
If this is included, an ``m.room.name`` event will be sent
into the room to indicate the name of the room. See Room
Events for more information on ``m.room.name``.
topic:
type: string
description: |-
If this is included, an ``m.room.topic`` event will be sent
into the room to indicate the topic for the room. See Room
Events for more information on ``m.room.topic``.
invite:
type: array
description: |-
A list of user IDs to invite to the room. This will tell the
server to invite everyone in the list to the newly created room.
items:
type: string
invite_3pid:
type: array
description: |-
A list of objects representing third party IDs to invite into
the room.
items:
type: object
title: Invite3pid
properties:
id_server:
type: string
description: The hostname+port of the identity server which should be used for third party identifier lookups.
id_access_token:
type: string
description: |-
An access token previously registered with the identity server. Servers
can treat this as optional to distinguish between r0.5-compatible clients
and this specification version.
medium:
type: string
# TODO: Link to Identity Service spec when it eixsts
description: The kind of address being passed in the address field, for example ``email``.
address:
type: string
description: The invitee's third party identifier.
required: ["id_server", "id_access_token", "medium", "address"]
room_version:
type: string
description: |-
The room version to set for the room. If not provided, the homeserver is
to use its configured default. If provided, the homeserver will return a
400 error with the errcode ``M_UNSUPPORTED_ROOM_VERSION`` if it does not
support the room version.
example: "1"
creation_content:
title: CreationContent
type: object
description: |-
Extra keys, such as ``m.federate``, to be added to the content
of the `m.room.create`_ event. The server will clobber the following
keys: ``creator``, ``room_version``. Future versions of the specification
may allow the server to clobber other keys.
initial_state:
type: array
description: |-
A list of state events to set in the new room. This allows
the user to override the default state events set in the new
room. The expected format of the state events are an object
with type, state_key and content keys set.
Takes precedence over events set by ``preset``, but gets
overriden by ``name`` and ``topic`` keys.
items:
type: object
title: StateEvent
properties:
type:
type: string
description: The type of event to send.
state_key:
type: string
description: The state_key of the state event. Defaults to an empty string.
content:
type: object
description: The content of the event.
required: ["type", "content"]
preset:
type: string
enum: ["private_chat", "public_chat", "trusted_private_chat"]
description: |-
Convenience parameter for setting various default state events
based on a preset.
If unspecified, the server should use the ``visibility`` to determine
which preset to use. A visbility of ``public`` equates to a preset of
``public_chat`` and ``private`` visibility equates to a preset of
``private_chat``.
is_direct:
type: boolean
description: |-
This flag makes the server set the ``is_direct`` flag on the
``m.room.member`` events sent to the users in ``invite`` and
``invite_3pid``. See `Direct Messaging`_ for more information.
power_level_content_override:
title: Power Level Event Content
type: object
description: |-
The power level content to override in the default power level
event. This object is applied on top of the generated `m.room.power_levels`_
event content prior to it being sent to the room. Defaults to
overriding nothing.
responses:
200:
description: Information about the newly created room.
schema:
type: object
description: Information about the newly created room.
properties:
room_id:
type: string
description: |-
The created room's ID.
required: ['room_id']
examples:
application/json: {
"room_id": "!sefiuhWgwghwWgh:example.com"
}
400:
description: |-
The request is invalid. A meaningful ``errcode`` and description
error text will be returned. Example reasons for rejection include:
- The request body is malformed (``errcode`` set to ``M_BAD_JSON``
or ``M_NOT_JSON``).
- The room alias specified is already taken (``errcode`` set to
``M_ROOM_IN_USE``).
- The initial state implied by the parameters to the request is
invalid: for example, the user's ``power_level`` is set below
that necessary to set the room name (``errcode`` set to
``M_INVALID_ROOM_STATE``).
- The homeserver doesn't support the requested room version, or
one or more users being invited to the new room are residents
of a homeserver which does not support the requested room version.
The ``errcode`` will be ``M_UNSUPPORTED_ROOM_VERSION`` in these
cases.
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room creation

224
data/api/client-server/cross_signing.yaml
Unescape Escape View File

@ -0,0 +1,224 @@
# Copyright 2020 The Matrix.org Foundation C.I.C.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Client-Server Cross Signing API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/keys/device_signing/upload":
post:
summary: Upload cross-signing keys.
description: |-
Publishes cross-signing keys for the user.
This API endpoint uses the `User-Interactive Authentication API`_.
operationId: uploadCrossSigningKeys
security:
- accessToken: []
parameters:
- in: body
name: keys
description: |-
The keys to be published.
schema:
type: object
properties:
master_key:
description: |-
Optional. The user\'s master key.
allOf:
- $ref: definitions/cross_signing_key.yaml
self_signing_key:
description: |-
Optional. The user\'s self-signing key. Must be signed by
the accompanying master key, or by the user\'s most recently
uploaded master key if no master key is included in the
request.
allOf:
- $ref: definitions/cross_signing_key.yaml
user_signing_key:
description: |-
Optional. The user\'s user-signing key. Must be signed by
the accompanying master key, or by the user\'s most recently
uploaded master key if no master key is included in the
request.
allOf:
- $ref: definitions/cross_signing_key.yaml
example: {
"master_key": {
"user_id": "@alice:example.com",
"usage": ["master"],
"keys": {
"ed25519:base64+master+public+key": "base64+master+public+key",
}
},
"self_signing_key": {
"user_id": "@alice:example.com",
"usage": ["self_signing"],
"keys": {
"ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key",
},
"signatures": {
"@alice:example.com": {
"ed25519:base64+master+public+key": "signature+of+self+signing+key"
}
}
},
"user_signing_key": {
"user_id": "@alice:example.com",
"usage": ["user_signing"],
"keys": {
"ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key",
},
"signatures": {
"@alice:example.com": {
"ed25519:base64+master+public+key": "signature+of+user+signing+key"
}
}
}
}
responses:
200:
description: The provided keys were successfully uploaded.
schema:
type: object
example: {}
400:
description: |-
The input was invalid in some way. This can include one of the
following error codes:
* ``M_INVALID_SIGNATURE``: For example, the self-signing or
user-signing key had an incorrect signature.
* ``M_MISSING_PARAM``: No master key is available.
schema:
type: object
example: {
"errcode": "M_INVALID_SIGNATURE",
"error": "Invalid signature"
}
403:
description: |-
The public key of one of the keys is the same as one of the user\'s
device IDs, or the request is not authorized for any other reason.
schema:
type: object
example: {
"errcode": "M_FORBIDDEN",
"error": "Key ID in use"
}
"/keys/signatures/upload":
post:
summary: Upload cross-signing signatures.
description: |-
Publishes cross-signing signatures for the user. The request body is a
map from user ID to key ID to signed JSON object.
operationId: uploadCrossSigningSignatures
security:
- accessToken: []
parameters:
- in: body
name: signatures
description: |-
The signatures to be published.
schema:
type: object
title: Signatures
additionalProperties:
type: object
additionalProperties:
type: object
example: {
"@alice:example.com": {
"HIJKLMN": {
"user_id": "@alice:example.com",
"device_id": "HIJKLMN",
"algorithms": [
"m.olm.curve25519-aes-sha256",
"m.megolm.v1.aes-sha"
],
"keys": {
"curve25519:HIJKLMN": "base64+curve25519+key",
"ed25519:HIJKLMN": "base64+ed25519+key"
},
"signatures": {
"@alice:example.com": {
"ed25519:base64+self+signing+public+key": "base64+signature+of+HIJKLMN"
}
}
},
"base64+master+public+key": {
"user_id": "@alice:example.com",
"usage": ["master"],
"keys": {
"ed25519:base64+master+public+key": "base64+master+public+key"
},
"signatures": {
"@alice:example.com": {
"ed25519:HIJKLMN": "base64+signature+of+master+key"
}
}
}
},
"@bob:example.com": {
"bobs+base64+master+public+key": {
"user_id": "@bob:example.com",
"keys": {
"ed25519:bobs+base64+master+public+key": "bobs+base64+master+public+key"
},
"usage": ["master"],
"signatures": {
"@alice:example.com": {
"ed25519:base64+user+signing+public+key": "base64+signature+of+bobs+master+key"
}
}
}
}
}
responses:
200:
description: The provided signatures were processed.
schema:
type: object
properties:
failures:
type: object
description: |-
A map from user ID to key ID to an error for any signatures
that failed. If a signature was invalid, the ``errcode`` will
be set to ``M_INVALID_SIGNATURE``.
additionalProperties:
type: object
additionalProperties:
type: object
title: Error
example: {
"@alice:example.com": {
"HIJKLMN": {
"errcode": "M_INVALID_SIGNATURE",
"error": "Invalid signature"
}
}
}

33
data/api/client-server/definitions/auth_data.yaml
Unescape Escape View File

@ -0,0 +1,33 @@
# Copyright 2016 OpenMarket Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
title: Authentication Data
description: |-
Used by clients to submit authentication information to the interactive-authentication API
type: object
properties:
type:
description: The login type that the client is attempting to complete.
type: string
session:
description: The value of the session key given by the homeserver.
type: string
additionalProperties:
description: Keys dependent on the login type
type: object
required:
- type
example:
type: "example.type.foo"
session: "xxxxx"
example_credential: "verypoorsharedsecret"

62
data/api/client-server/definitions/auth_response.yaml
Unescape Escape View File

@ -0,0 +1,62 @@
# Copyright 2016 OpenMarket Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
title: Authentication response
description: |-
Used by servers to indicate that additional authentication information is required,
type: object
properties:
flows:
description: A list of the login flows supported by the server for this API.
title: Flow information
type: array
items:
type: object
properties:
stages:
description: |-
The login type of each of the stages required to complete this
authentication flow
type: array
items:
type: string
example: "example.type.foo"
required:
- stages
params:
type: object
description: |-
Contains any information that the client will need to know in order to
use a given type of authentication. For each login type presented,
that type may be present as a key in this dictionary. For example, the
public part of an OAuth client ID could be given here.
additionalProperties:
type: object
example:
"example.type.baz": { "example_key": "foobar" }
session:
type: string
description: |-
This is a session identifier that the client must pass back to the home
server, if one is provided, in subsequent attempts to authenticate in the
same API call.
example: "xxxxxxyz"
completed:
type: array
description: |-
A list of the stages the client has completed successfully
items:
type: string
example: "example.type.foo"
required:
- flows

44
data/api/client-server/definitions/client_device.yaml
Unescape Escape View File

@ -0,0 +1,44 @@
# Copyright 2016 OpenMarket Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
description: A client device
title: Device
properties:
device_id:
type: string
description: Identifier of this device.
example: QBUAZIFURK
display_name:
type: string
description: |-
Display name set by the user for this device. Absent if no name has been
set.
example: android
last_seen_ip:
type: string
description: |-
The IP address where this device was last seen. (May be a few minutes out
of date, for efficiency reasons).
example: 1.2.3.4
last_seen_ts:
type: integer
format: int64
description: |-
The timestamp (in milliseconds since the unix epoch) when this devices
was last seen. (May be a few minutes out of date, for efficiency
reasons).
example: 1474491775024
required:
- device_id

55
data/api/client-server/definitions/cross_signing_key.yaml
Unescape Escape View File

@ -0,0 +1,55 @@
# Copyright 2020 The Matrix.org Foundation C.I.C.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: CrossSigningKey
description: Cross signing key
properties:
user_id:
type: string
description: |-
The ID of the user the key belongs to.
example: "@alice:example.com"
usage:
type: array
description: |-
What the key is used for.
items:
type: string
enum: ["master", "self_signing", "user_signing"]
keys:
type: object
additionalProperties:
type: string
description: |-
The public key. The object must have exactly one property, whose name is
in the form ``<algorithm>:<unpadded_base64_public_key>``, and whose value
is the unpadded base64 public key.
example:
"ed25519:alice+base64+public+key": "alice+base64+public+key"
signatures:
type: object
title: Signatures
description: |-
Signatures of the key, calculated using the process described at `Signing
JSON`_. Optional for the master key. Other keys must be signed by the
user\'s master key.
example: {
"@alice:example.com": {
"ed25519:alice+base64+master+key": "signature+of+key"
}
}
required:
- user_id
- usage
- keys

69
data/api/client-server/definitions/device_keys.yaml
Unescape Escape View File

@ -0,0 +1,69 @@
# Copyright 2016 OpenMarket Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: DeviceKeys
description: Device identity keys
properties:
user_id:
type: string
description: |-
The ID of the user the device belongs to. Must match the user ID used
when logging in.
example: "@alice:example.com"
device_id:
type: string
description: |-
The ID of the device these keys belong to. Must match the device ID used
when logging in.
example: "JLAFKJWSCS"
algorithms:
type: array
items:
type: string
description: |-
The encryption algorithms supported by this device.
example: ["m.olm.v1.curve25519-aes-sha2", "m.megolm.v1.aes-sha2"]
keys:
type: object
description: |-
Public identity keys. The names of the properties should be in the
format ``<algorithm>:<device_id>``. The keys themselves should be
encoded as specified by the key algorithm.
additionalProperties:
type: string
example:
"curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI"
"ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
signatures:
type: object
title: Signatures
description: |-
Signatures for the device key object. A map from user ID, to a map from
``<algorithm>:<device_id>`` to the signature.
The signature is calculated using the process described at `Signing
JSON`_.
additionalProperties:
type: object
additionalProperties:
type: string
example:
"@alice:example.com":
"ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
required:
- user_id
- device_id
- algorithms
- keys
- signatures

25
data/api/client-server/definitions/errors/error.yaml
Unescape Escape View File

@ -0,0 +1,25 @@
# Copyright 2016 OpenMarket Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
description: A Matrix-level Error
properties:
errcode:
type: string
description: An error code.
example: M_UNKNOWN
error:
type: string
description: A human-readable error message.
example: An unknown error occurred
required: ["errcode"]

32
data/api/client-server/definitions/errors/rate_limited.yaml
Unescape Escape View File

@ -0,0 +1,32 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
$ref: error.yaml
type: object
description: The rate limit was reached for this request
properties:
errcode:
type: string
description: The M_LIMIT_EXCEEDED error code
example: M_LIMIT_EXCEEDED
error:
type: string
description: A human-readable error message.
example: Too many requests
retry_after_ms:
type: integer
description: |-
The amount of time in milliseconds the client should wait
before trying the request again.
example: 2000
required: ["errcode"]

6
data/api/client-server/definitions/event-schemas/README.md
Unescape Escape View File

@ -0,0 +1,6 @@
Checking the event schemas
==========================
To validate the event schemas, and check the example events, run
./check-examples.py

134
data/api/client-server/definitions/event-schemas/check_examples.py
Unescape Escape View File

@ -0,0 +1,134 @@
#!/usr/bin/env python
#
# Copyright 2016 OpenMarket Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
import sys
import json
import os
import traceback
def import_error(module, package, debian, error):
sys.stderr.write((
"Error importing %(module)s: %(error)r\n"
"To install %(module)s run:\n"
" pip install %(package)s\n"
"or on Debian run:\n"
" sudo apt-get install python-%(debian)s\n"
) % locals())
if __name__ == '__main__':
sys.exit(1)
try:
import jsonschema
except ImportError as e:
import_error("jsonschema", "jsonschema", "jsonschema", e)
raise
try:
import yaml
except ImportError as e:
import_error("yaml", "PyYAML", "yaml", e)
raise
def load_file(path):
print("Loading reference: %s" % path)
if not path.startswith("file://"):
raise Exception("Bad ref: %s" % (path,))
path = path[len("file://"):]
with open(path, "r") as f:
if path.endswith(".json"):
return json.load(f)
else:
# We have to assume it's YAML because some of the YAML examples
# do not have file extensions.
return yaml.load(f)
def resolve_references(path, schema):
if isinstance(schema, dict):
# do $ref first
if '$ref' in schema:
value = schema['$ref']
path = os.path.abspath(os.path.join(os.path.dirname(path), value))
ref = load_file("file://" + path)
result = resolve_references(path, ref)
del schema['$ref']
else:
result = {}
for key, value in schema.items():
result[key] = resolve_references(path, value)
return result
elif isinstance(schema, list):
return [resolve_references(path, value) for value in schema]
else:
return schema
def check_example_file(examplepath, schemapath):
with open(examplepath) as f:
example = resolve_references(examplepath, json.load(f))
with open(schemapath) as f:
schema = yaml.load(f)
fileurl = "file://" + os.path.abspath(schemapath)
schema["id"] = fileurl
resolver = jsonschema.RefResolver(schemapath, schema, handlers={"file": load_file})
print ("Checking schema for: %r %r" % (examplepath, schemapath))
try:
jsonschema.validate(example, schema, resolver=resolver)
except Exception as e:
raise ValueError("Error validating JSON schema for %r %r" % (
examplepath, schemapath
), e)
def check_example_dir(exampledir, schemadir):
errors = []
for root, dirs, files in os.walk(exampledir):
for filename in files:
if filename.startswith("."):
# Skip over any vim .swp files.
continue
if filename.endswith(".json"):
# Skip over any explicit examples (partial event definitions)
continue
cwd = os.path.basename(os.path.dirname(os.path.join(root, filename)))
if cwd == "core":
# Skip checking the underlying definitions
continue
examplepath = os.path.join(root, filename)
schemapath = examplepath.replace(exampledir, schemadir)
if schemapath.find("$") >= 0:
schemapath = schemapath[:schemapath.find("$")]
try:
check_example_file(examplepath, schemapath)
except Exception as e:
errors.append(sys.exc_info())
for (exc_type, exc_value, exc_trace) in errors:
traceback.print_exception(exc_type, exc_value, exc_trace)
if errors:
raise ValueError("Error validating examples")
if __name__ == '__main__':
try:
check_example_dir("examples", "schema")
except:
sys.exit(1)

6
data/api/client-server/definitions/event-schemas/examples/core/event.json
Unescape Escape View File

@ -0,0 +1,6 @@
{
"content": {
"key": "value"
},
"type": "org.example.custom.event"
}

4
data/api/client-server/definitions/event-schemas/examples/core/room_edu.json
Unescape Escape View File

@ -0,0 +1,4 @@
{
"$ref": "event.json",
"room_id": "!jEsUZKDJdhlrceRyVU:example.org"
}

10
data/api/client-server/definitions/event-schemas/examples/core/room_event.json
Unescape Escape View File

@ -0,0 +1,10 @@
{
"$ref": "event.json",
"event_id": "$143273582443PhrSn:example.org",
"room_id": "!jEsUZKDJdhlrceRyVU:example.org",
"sender": "@example:example.org",
"origin_server_ts": 1432735824653,
"unsigned": {
"age": 1234
}
}

4
data/api/client-server/definitions/event-schemas/examples/core/state_event.json
Unescape Escape View File

@ -0,0 +1,4 @@
{
"$ref": "room_event.json",
"state_key": "ArbitraryString"
}

18
data/api/client-server/definitions/event-schemas/examples/invite_room_state.json
Unescape Escape View File

@ -0,0 +1,18 @@
[
{
"type": "m.room.name",
"sender": "@bob:example.org",
"state_key": "",
"content": {
"name": "Example Room"
}
},
{
"type": "m.room.join_rules",
"sender": "@bob:example.org",
"state_key": "",
"content": {
"join_rule": "invite"
}
}
]

10
data/api/client-server/definitions/event-schemas/examples/m.accepted_terms
Unescape Escape View File

@ -0,0 +1,10 @@
{
"$ref": "core/event.json",
"type": "m.accepted_terms",
"content": {
"accepted": [
"https://example.org/somewhere/terms-1.2-en.html",
"https://example.org/somewhere/privacy-1.2-en.html"
]
}
}

13
data/api/client-server/definitions/event-schemas/examples/m.call.answer
Unescape Escape View File

@ -0,0 +1,13 @@
{
"$ref": "core/room_event.json",
"type": "m.call.answer",
"content": {
"version" : 0,
"call_id": "12345",
"lifetime": 60000,
"answer": {
"type" : "answer",
"sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]"
}
}
}

15
data/api/client-server/definitions/event-schemas/examples/m.call.candidates
Unescape Escape View File

@ -0,0 +1,15 @@
{
"$ref": "core/room_event.json",
"type": "m.call.candidates",
"content": {
"version" : 0,
"call_id": "12345",
"candidates": [
{
"sdpMid": "audio",
"sdpMLineIndex": 0,
"candidate": "candidate:863018703 1 udp 2122260223 10.9.64.156 43670 typ host generation 0"
}
]
}
}

8
data/api/client-server/definitions/event-schemas/examples/m.call.hangup
Unescape Escape View File

@ -0,0 +1,8 @@
{
"$ref": "core/room_event.json",
"type": "m.call.hangup",
"content": {
"version" : 0,
"call_id": "12345"
}
}

13
data/api/client-server/definitions/event-schemas/examples/m.call.invite
Unescape Escape View File

@ -0,0 +1,13 @@
{
"$ref": "core/room_event.json",
"type": "m.call.invite",
"content": {
"version" : 0,
"call_id": "12345",
"lifetime": 60000,
"offer": {
"type" : "offer",
"sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]"
}
}
}

10
data/api/client-server/definitions/event-schemas/examples/m.direct
Unescape Escape View File

@ -0,0 +1,10 @@
{
"$ref": "core/event.json",
"type": "m.direct",
"content": {
"@bob:example.com": [
"!abcdefgh:example.com",
"!hgfedcba:example.com"
]
}
}

4
data/api/client-server/definitions/event-schemas/examples/m.dummy
Unescape Escape View File

@ -0,0 +1,4 @@
{
"content": {},
"type": "m.dummy"
}

14
data/api/client-server/definitions/event-schemas/examples/m.forwarded_room_key
Unescape Escape View File

@ -0,0 +1,14 @@
{
"content": {
"algorithm": "m.megolm.v1.aes-sha2",
"room_id": "!Cuyf34gef24t:localhost",
"session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ",
"session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf...",
"sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU",
"sender_claimed_ed25519_key": "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y",
"forwarding_curve25519_key_chain": [
"hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw"
]
},
"type": "m.forwarded_room_key"
}

8
data/api/client-server/definitions/event-schemas/examples/m.fully_read
Unescape Escape View File

@ -0,0 +1,8 @@
{
"$ref": "core/event.json",
"type": "m.fully_read",
"room_id": "!somewhere:example.org",
"content": {
"event_id": "$someplace:example.org"
}
}

7
data/api/client-server/definitions/event-schemas/examples/m.identity_server
Unescape Escape View File

@ -0,0 +1,7 @@
{
"$ref": "core/event.json",
"type": "m.identity_server",
"content": {
"base_url": "https://example.org"
}
}

9
data/api/client-server/definitions/event-schemas/examples/m.ignored_user_list
Unescape Escape View File

@ -0,0 +1,9 @@
{
"$ref": "core/event.json",
"type": "m.ignored_user_list",
"content": {
"ignored_users": {
"@someone:example.org": {}
}
}
}

12
data/api/client-server/definitions/event-schemas/examples/m.key.verification.accept
Unescape Escape View File

@ -0,0 +1,12 @@
{
"type": "m.key.verification.accept",
"content": {
"transaction_id": "S0meUniqueAndOpaqueString",
"method": "m.sas.v1",
"key_agreement_protocol": "curve25519",
"hash": "sha256",
"message_authentication_code": "hkdf-hmac-sha256",
"short_authentication_string": ["decimal", "emoji"],
"commitment": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
}
}

8
data/api/client-server/definitions/event-schemas/examples/m.key.verification.cancel
Unescape Escape View File

@ -0,0 +1,8 @@
{
"type": "m.key.verification.cancel",
"content": {
"transaction_id": "S0meUniqueAndOpaqueString",
"code": "m.user",
"reason": "User rejected the key verification request"
}
}

7
data/api/client-server/definitions/event-schemas/examples/m.key.verification.key
Unescape Escape View File

@ -0,0 +1,7 @@
{
"type": "m.key.verification.key",
"content": {
"transaction_id": "S0meUniqueAndOpaqueString",
"key": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
}
}

10
data/api/client-server/definitions/event-schemas/examples/m.key.verification.mac
Unescape Escape View File

@ -0,0 +1,10 @@
{
"type": "m.key.verification.mac",
"content": {
"transaction_id": "S0meUniqueAndOpaqueString",
"keys": "2Wptgo4CwmLo/Y8B8qinxApKaCkBG2fjTWB7AbP5Uy+aIbygsSdLOFzvdDjww8zUVKCmI02eP9xtyJxc/cLiBA",
"mac": {
"ed25519:ABCDEF": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
}
}
}

11
data/api/client-server/definitions/event-schemas/examples/m.key.verification.request
Unescape Escape View File

@ -0,0 +1,11 @@
{
"type": "m.key.verification.request",
"content": {
"from_device": "AliceDevice2",
"transaction_id": "S0meUniqueAndOpaqueString",
"methods": [
"m.sas.v1"
],
"timestamp": 1559598944869
}
}

8
data/api/client-server/definitions/event-schemas/examples/m.key.verification.start
Unescape Escape View File

@ -0,0 +1,8 @@
{
"type": "m.key.verification.start",
"content": {
"from_device": "BobDevice1",
"transaction_id": "S0meUniqueAndOpaqueString",
"method": "m.sas.v1"
}
}

12
data/api/client-server/definitions/event-schemas/examples/m.key.verification.start$m.sas.v1
Unescape Escape View File

@ -0,0 +1,12 @@
{
"type": "m.key.verification.start",
"content": {
"from_device": "BobDevice1",
"transaction_id": "S0meUniqueAndOpaqueString",
"method": "m.sas.v1",
"key_agreement_protocols": ["curve25519"],
"hashes": ["sha256"],
"message_authentication_codes": ["hkdf-hmac-sha256"],
"short_authentication_string": ["decimal", "emoji"]
}
}

10
data/api/client-server/definitions/event-schemas/examples/m.policy.rule.room
Unescape Escape View File

@ -0,0 +1,10 @@
{
"$ref": "core/state_event.json",
"type": "m.policy.rule.room",
"state_key": "rule:#*:example.org",
"content": {
"entity": "#*:example.org",
"recommendation": "m.ban",
"reason": "undesirable content"
}
}

10
data/api/client-server/definitions/event-schemas/examples/m.policy.rule.server
Unescape Escape View File

@ -0,0 +1,10 @@
{
"$ref": "core/state_event.json",
"type": "m.policy.rule.server",
"state_key": "rule:*.example.org",
"content": {
"entity": "*.example.org",
"recommendation": "m.ban",
"reason": "undesirable engagement"
}
}

10
data/api/client-server/definitions/event-schemas/examples/m.policy.rule.user
Unescape Escape View File

@ -0,0 +1,10 @@
{
"$ref": "core/state_event.json",
"type": "m.policy.rule.user",
"state_key": "rule:@alice*:example.org",
"content": {
"entity": "@alice*:example.org",
"recommendation": "m.ban",
"reason": "undesirable behaviour"
}
}

12
data/api/client-server/definitions/event-schemas/examples/m.presence
Unescape Escape View File

@ -0,0 +1,12 @@
{
"$ref": "core/event.json",
"sender": "@example:localhost",
"type": "m.presence",
"content": {
"avatar_url": "mxc://localhost:wefuiwegh8742w",
"last_active_ago": 2478593,
"presence": "online",
"currently_active": false,
"status_msg": "Making cupcakes"
}
}

197
data/api/client-server/definitions/event-schemas/examples/m.push_rules
Unescape Escape View File

@ -0,0 +1,197 @@
{
"$ref": "core/event.json",
"type": "m.push_rules",
"content": {
"global": {
"content": [
{
"actions": [
"notify",
{
"set_tweak": "sound",
"value": "default"
},
{
"set_tweak": "highlight"
}
],
"default": true,
"enabled": true,
"pattern": "alice",
"rule_id": ".m.rule.contains_user_name"
}
],
"override": [
{
"actions": [
"dont_notify"
],
"conditions": [],
"default": true,
"enabled": false,
"rule_id": ".m.rule.master"
},
{
"actions": [
"dont_notify"
],
"conditions": [
{
"key": "content.msgtype",
"kind": "event_match",
"pattern": "m.notice"
}
],
"default": true,
"enabled": true,
"rule_id": ".m.rule.suppress_notices"
}
],
"room": [],
"sender": [],
"underride": [
{
"actions": [
"notify",
{
"set_tweak": "sound",
"value": "ring"
},
{
"set_tweak": "highlight",
"value": false
}
],
"conditions": [
{
"key": "type",
"kind": "event_match",
"pattern": "m.call.invite"
}
],
"default": true,
"enabled": true,
"rule_id": ".m.rule.call"
},
{
"actions": [
"notify",
{
"set_tweak": "sound",
"value": "default"
},
{
"set_tweak": "highlight"
}
],
"conditions": [
{
"kind": "contains_display_name"
}
],
"default": true,
"enabled": true,
"rule_id": ".m.rule.contains_display_name"
},
{
"actions": [
"notify",
{
"set_tweak": "sound",
"value": "default"
},
{
"set_tweak": "highlight",
"value": false
}
],
"conditions": [
{
"kind": "room_member_count",
"is": "2"
},
{
"kind": "event_match",
"key": "type",
"pattern": "m.room.message"
}
],
"default": true,
"enabled": true,
"rule_id": ".m.rule.room_one_to_one"
},
{
"actions": [
"notify",
{
"set_tweak": "sound",
"value": "default"
},
{
"set_tweak": "highlight",
"value": false
}
],
"conditions": [
{
"key": "type",
"kind": "event_match",
"pattern": "m.room.member"
},
{
"key": "content.membership",
"kind": "event_match",
"pattern": "invite"
},
{
"key": "state_key",
"kind": "event_match",
"pattern": "@alice:example.com"
}
],
"default": true,
"enabled": true,
"rule_id": ".m.rule.invite_for_me"
},
{
"actions": [
"notify",
{
"set_tweak": "highlight",
"value": false
}
],
"conditions": [
{
"key": "type",
"kind": "event_match",
"pattern": "m.room.member"
}
],
"default": true,
"enabled": true,
"rule_id": ".m.rule.member_event"
},
{
"actions": [
"notify",
{
"set_tweak": "highlight",
"value": false
}
],
"conditions": [
{
"key": "type",
"kind": "event_match",
"pattern": "m.room.message"
}
],
"default": true,
"enabled": true,
"rule_id": ".m.rule.message"
}
]
}
}
}

13
data/api/client-server/definitions/event-schemas/examples/m.receipt
Unescape Escape View File

@ -0,0 +1,13 @@
{
"$ref": "core/room_edu.json",
"type": "m.receipt",
"content": {
"$1435641916114394fHBLK:matrix.org": {
"m.read": {
"@rikj:jki.re": {
"ts": 1436451550453
}
}
}
}
}

14
data/api/client-server/definitions/event-schemas/examples/m.room.avatar
Unescape Escape View File

@ -0,0 +1,14 @@
{
"$ref": "core/state_event.json",
"type": "m.room.avatar",
"state_key": "",
"content": {
"info": {
"h": 398,
"w": 394,
"mimetype": "image/jpeg",
"size": 31037
},
"url": "mxc://example.org/JWEIFJgwEIhweiWJE"
}
}

12
data/api/client-server/definitions/event-schemas/examples/m.room.canonical_alias
Unescape Escape View File

@ -0,0 +1,12 @@
{
"$ref": "core/state_event.json",
"type": "m.room.canonical_alias",
"state_key": "",
"content": {
"alias": "#somewhere:localhost",
"alt_aliases": [
"#somewhere:example.org",
"#myroom:example.com"
]
}
}

14
data/api/client-server/definitions/event-schemas/examples/m.room.create
Unescape Escape View File

@ -0,0 +1,14 @@
{
"$ref": "core/state_event.json",
"type": "m.room.create",
"state_key": "",
"content": {
"creator": "@example:example.org",
"room_version": "1",
"m.federate": true,
"predecessor": {
"event_id": "$something:example.org",
"room_id": "!oldroom:example.org"
}
}
}

11
data/api/client-server/definitions/event-schemas/examples/m.room.encrypted$megolm
Unescape Escape View File

@ -0,0 +1,11 @@
{
"$ref": "core/room_event.json",
"type": "m.room.encrypted",
"content": {
"algorithm": "m.megolm.v1.aes-sha2",
"ciphertext": "AwgAEnACgAkLmt6qF84IK++J7UDH2Za1YVchHyprqTqsg...",
"device_id": "RJYKSTBOIE",
"sender_key": "IlRMeOPX2e0MurIyfWEucYBRVOEEUMrOHqn/8mLqMjA",
"session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ"
}
}

14
data/api/client-server/definitions/event-schemas/examples/m.room.encrypted$olm
Unescape Escape View File

@ -0,0 +1,14 @@
{
"$ref": "core/room_event.json",
"type": "m.room.encrypted",
"content": {
"algorithm": "m.olm.v1.curve25519-aes-sha2",
"sender_key": "Szl29ksW/L8yZGWAX+8dY1XyFi+i5wm+DRhTGkbMiwU",
"ciphertext": {
"7qZcfnBmbEGzxxaWfBjElJuvn7BZx+lSz/SvFrDF/z8": {
"type": 0,
"body": "AwogGJJzMhf/S3GQFXAOrCZ3iKyGU5ZScVtjI0KypTYrW..."
}
}
}
}

10
data/api/client-server/definitions/event-schemas/examples/m.room.encryption
Unescape Escape View File

@ -0,0 +1,10 @@
{
"$ref": "core/state_event.json",
"type": "m.room.encryption",
"state_key": "",
"content": {
"algorithm": "m.megolm.v1.aes-sha2",
"rotation_period_ms": 604800000,
"rotation_period_msgs": 100
}
}

8
data/api/client-server/definitions/event-schemas/examples/m.room.guest_access
Unescape Escape View File

@ -0,0 +1,8 @@
{
"$ref": "core/state_event.json",
"type": "m.room.guest_access",
"state_key": "",
"content": {
"guest_access": "can_join"
}
}

8
data/api/client-server/definitions/event-schemas/examples/m.room.history_visibility
Unescape Escape View File

@ -0,0 +1,8 @@
{
"$ref": "core/state_event.json",
"type": "m.room.history_visibility",
"state_key": "",
"content": {
"history_visibility": "shared"
}
}

8
data/api/client-server/definitions/event-schemas/examples/m.room.join_rules
Unescape Escape View File

@ -0,0 +1,8 @@
{
"$ref": "core/state_event.json",
"type": "m.room.join_rules",
"state_key": "",
"content": {
"join_rule": "public"
}
}

11
data/api/client-server/definitions/event-schemas/examples/m.room.member
Unescape Escape View File

@ -0,0 +1,11 @@
{
"$ref": "core/state_event.json",
"state_key": "@alice:example.org",
"type": "m.room.member",
"content": {
"membership": "join",
"avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
"displayname": "Alice Margatroid",
"reason": "Looking for support"
}
}

15
data/api/client-server/definitions/event-schemas/examples/m.room.member$invite_room_state
Unescape Escape View File

@ -0,0 +1,15 @@
{
"$ref": "m.room.member",
"content": {
"membership": "invite",
"avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
"displayname": "Alice Margatroid",
"reason": "Looking for support"
},
"unsigned": {
"age": 1234,
"invite_room_state": {
"$ref": "invite_room_state.json"
}
}
}

20
data/api/client-server/definitions/event-schemas/examples/m.room.member$third_party_invite
Unescape Escape View File

@ -0,0 +1,20 @@
{
"$ref": "m.room.member",
"content": {
"membership": "invite",
"avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
"displayname": "Alice Margatroid",
"third_party_invite": {
"display_name": "alice",
"signed": {
"mxid": "@alice:example.org",
"signatures": {
"magic.forest": {
"ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
}
},
"token": "abc123"
}
}
}
}

14
data/api/client-server/definitions/event-schemas/examples/m.room.message$m.audio
Unescape Escape View File

@ -0,0 +1,14 @@
{
"$ref": "core/room_event.json",
"type": "m.room.message",
"content": {
"body": "Bee Gees - Stayin' Alive",
"url": "mxc://example.org/ffed755USFFxlgbQYZGtryd",
"info": {
"duration": 2140786,
"size": 1563685,
"mimetype": "audio/mpeg"
},
"msgtype": "m.audio"
}
}

10
data/api/client-server/definitions/event-schemas/examples/m.room.message$m.emote
Unescape Escape View File

@ -0,0 +1,10 @@
{
"$ref": "core/room_event.json",
"type": "m.room.message",
"content": {
"body": "thinks this is an example emote",
"msgtype": "m.emote",
"format": "org.matrix.custom.html",
"formatted_body": "thinks <b>this</b> is an example emote"
}
}

14
data/api/client-server/definitions/event-schemas/examples/m.room.message$m.file
Unescape Escape View File

@ -0,0 +1,14 @@
{
"$ref": "core/room_event.json",
"type": "m.room.message",
"content": {
"body": "something-important.doc",
"filename": "something-important.doc",
"info": {
"mimetype": "application/msword",
"size": 46144
},
"msgtype": "m.file",
"url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe"
}
}

15
data/api/client-server/definitions/event-schemas/examples/m.room.message$m.image
Unescape Escape View File

@ -0,0 +1,15 @@
{
"$ref": "core/room_event.json",
"type": "m.room.message",
"content": {
"body": "filename.jpg",
"info": {
"h": 398,
"w": 394,
"mimetype": "image/jpeg",
"size": 31037
},
"url": "mxc://example.org/JWEIFJgwEIhweiWJE",
"msgtype": "m.image"
}
}

18
data/api/client-server/definitions/event-schemas/examples/m.room.message$m.location
Unescape Escape View File

@ -0,0 +1,18 @@
{
"$ref": "core/room_event.json",
"type": "m.room.message",
"content": {
"body": "Big Ben, London, UK",
"geo_uri": "geo:51.5008,0.1247",
"info": {
"thumbnail_url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe",
"thumbnail_info": {
"mimetype": "image/jpeg",
"size": 46144,
"w": 300,
"h": 300
}
},
"msgtype": "m.location"
}
}

10
data/api/client-server/definitions/event-schemas/examples/m.room.message$m.notice
Unescape Escape View File

@ -0,0 +1,10 @@
{
"$ref": "core/room_event.json",
"type": "m.room.message",
"content": {
"body": "This is an example notice",
"msgtype": "m.notice",
"format": "org.matrix.custom.html",
"formatted_body": "This is an <strong>example</strong> notice"
}
}

11
data/api/client-server/definitions/event-schemas/examples/m.room.message$m.server_notice
Unescape Escape View File

@ -0,0 +1,11 @@
{
"$ref": "core/room_event.json",
"type": "m.room.message",
"content": {
"body": "Human-readable message to explain the notice",
"msgtype": "m.server_notice",
"server_notice_type": "m.server_notice.usage_limit_reached",
"admin_contact": "mailto:server.admin@example.org",
"limit_type": "monthly_active_user"
}
}

10
data/api/client-server/definitions/event-schemas/examples/m.room.message$m.text
Unescape Escape View File

@ -0,0 +1,10 @@
{
"$ref": "core/room_event.json",
"type": "m.room.message",
"content": {
"body": "This is an example text message",
"msgtype": "m.text",
"format": "org.matrix.custom.html",
"formatted_body": "<b>This is an example text message</b>"
}
}

23
data/api/client-server/definitions/event-schemas/examples/m.room.message$m.video
Unescape Escape View File

@ -0,0 +1,23 @@
{
"$ref": "core/room_event.json",
"type": "m.room.message",
"content": {
"body": "Gangnam Style",
"url": "mxc://example.org/a526eYUSFFxlgbQYZmo442",
"info": {
"thumbnail_url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe",
"thumbnail_info": {
"mimetype": "image/jpeg",
"size": 46144,
"w": 300,
"h": 300
},
"w": 480,
"h": 320,
"duration": 2140786,
"size": 1563685,
"mimetype": "video/mp4"
},
"msgtype": "m.video"
}
}

8
data/api/client-server/definitions/event-schemas/examples/m.room.message.feedback
Unescape Escape View File

@ -0,0 +1,8 @@
{
"$ref": "core/room_event.json",
"type": "m.room.message.feedback",
"content": {
"type": "delivered",
"target_event_id": "$WEIGFHFW:localhost"
}
}

8
data/api/client-server/definitions/event-schemas/examples/m.room.name
Unescape Escape View File

@ -0,0 +1,8 @@
{
"$ref": "core/state_event.json",
"type": "m.room.name",
"state_key": "",
"content": {
"name": "The room name"
}
}

8
data/api/client-server/definitions/event-schemas/examples/m.room.pinned_events
Unescape Escape View File

@ -0,0 +1,8 @@
{
"$ref": "core/state_event.json",
"type": "m.room.pinned_events",
"state_key": "",
"content": {
"pinned": ["$someevent:example.org"]
}
}

24
data/api/client-server/definitions/event-schemas/examples/m.room.power_levels
Unescape Escape View File

@ -0,0 +1,24 @@
{
"$ref": "core/state_event.json",
"type": "m.room.power_levels",
"state_key": "",
"content": {
"ban": 50,
"events": {
"m.room.name": 100,
"m.room.power_levels": 100
},
"events_default": 0,
"invite": 50,
"kick": 50,
"redact": 50,
"state_default": 50,
"users": {
"@example:localhost": 100
},
"users_default": 0,
"notifications": {
"room": 20
}
}
}

8
data/api/client-server/definitions/event-schemas/examples/m.room.redaction
Unescape Escape View File

@ -0,0 +1,8 @@
{
"$ref": "core/room_event.json",
"type": "m.room.redaction",
"redacts": "$fukweghifu23:localhost",
"content": {
"reason": "Spamming"
}
}

10
data/api/client-server/definitions/event-schemas/examples/m.room.server_acl
Unescape Escape View File

@ -0,0 +1,10 @@
{
"$ref": "core/state_event.json",
"type": "m.room.server_acl",
"state_key": "",
"content": {
"allow_ip_literals": false,
"allow": ["*"],
"deny": ["*.evil.com", "evil.com"]
}
}

14
data/api/client-server/definitions/event-schemas/examples/m.room.third_party_invite
Unescape Escape View File

@ -0,0 +1,14 @@
{
"$ref": "core/state_event.json",
"type": "m.room.third_party_invite",
"state_key": "pc98",
"content": {
"display_name": "Alice Margatroid",
"key_validity_url": "https://magic.forest/verifykey",
"public_key": "abc123",
"public_keys": [{
"public_key": "def456",
"key_validity_url": "https://magic.forest/verifykey"
}]
}
}

9
data/api/client-server/definitions/event-schemas/examples/m.room.tombstone
Unescape Escape View File

@ -0,0 +1,9 @@
{
"$ref": "core/state_event.json",
"type": "m.room.tombstone",
"state_key": "",
"content": {
"body": "This room has been replaced",
"replacement_room": "!newroom:example.org"
}
}

8
data/api/client-server/definitions/event-schemas/examples/m.room.topic
Unescape Escape View File

@ -0,0 +1,8 @@
{
"$ref": "core/state_event.json",
"type": "m.room.topic",
"state_key": "",
"content": {
"topic": "A room topic"
}
}

10
data/api/client-server/definitions/event-schemas/examples/m.room_key
Unescape Escape View File

@ -0,0 +1,10 @@
{
"$ref": "core/event.json",
"type": "m.room_key",
"content": {
"algorithm": "m.megolm.v1.aes-sha2",
"room_id": "!Cuyf34gef24t:localhost",
"session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ",
"session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEY..."
}
}

12
data/api/client-server/definitions/event-schemas/examples/m.room_key.withheld
Unescape Escape View File

@ -0,0 +1,12 @@
{
"$ref": "core/event.json",
"type": "m.room_key.withheld",
"content": {
"algorithm": "m.megolm.v1.aes-sha2",
"room_id": "!Cuyf34gef24t:localhost",
"session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ",
"sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU",
"code": "m.unverified",
"reason": "Device not verified"
}
}

8
data/api/client-server/definitions/event-schemas/examples/m.room_key_request$cancel_request
Unescape Escape View File

@ -0,0 +1,8 @@
{
"content": {
"action": "request_cancellation",
"requesting_device_id": "RJYKSTBOIE",
"request_id": "1495474790150.19"
},
"type": "m.room_key_request"
}

14
data/api/client-server/definitions/event-schemas/examples/m.room_key_request$request
Unescape Escape View File

@ -0,0 +1,14 @@
{
"content": {
"body": {
"algorithm": "m.megolm.v1.aes-sha2",
"room_id": "!Cuyf34gef24t:localhost",
"session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ",
"sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU"
},
"action": "request",
"requesting_device_id": "RJYKSTBOIE",
"request_id": "1495474790150.19"
},
"type": "m.room_key_request"
}

21
data/api/client-server/definitions/event-schemas/examples/m.sticker
Unescape Escape View File

@ -0,0 +1,21 @@
{
"$ref": "core/room_event.json",
"type": "m.sticker",
"content": {
"body": "Landing",
"info": {
"mimetype": "image/png",
"thumbnail_info": {
"mimetype": "image/png",
"h": 200,
"w": 140,
"size": 73602
},
"h": 200,
"thumbnail_url": "mxc://matrix.org/sHhqkFCvSkFwtmvtETOtKnLP",
"w": 140,
"size": 73602
},
"url": "mxc://matrix.org/sHhqkFCvSkFwtmvtETOtKnLP"
}
}

9
data/api/client-server/definitions/event-schemas/examples/m.tag
Unescape Escape View File

@ -0,0 +1,9 @@
{
"$ref": "core/event.json",
"type": "m.tag",
"content": {
"tags": {
"u.work": {"order": 0.9}
}
}
}

7
data/api/client-server/definitions/event-schemas/examples/m.typing
Unescape Escape View File

@ -0,0 +1,7 @@
{
"$ref": "core/room_edu.json",
"type": "m.typing",
"content": {
"user_ids": ["@alice:matrix.org", "@bob:example.com"]
}
}

30
data/api/client-server/definitions/event-schemas/moderation_policy_rule.yaml
Unescape Escape View File

@ -0,0 +1,30 @@
# Copyright 2020 The Matrix.org Foundation C.I.C.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
properties:
entity:
description: |-
The entity affected by this rule. Glob characters ``*`` and ``?`` can be used
to match zero or more and one or more characters respectively.
type: string
recommendation:
description: The suggested action to take. Currently only ``m.ban`` is specified.
type: string
reason:
description: The human-readable description for the ``recommendation``.
type: string
type: object
required:
- entity
- recommendation
- reason

15
data/api/client-server/definitions/event-schemas/schema/core-event-schema/event.yaml
Unescape Escape View File

@ -0,0 +1,15 @@
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.
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
required:
- type
- content
title: Event
type: object

36
data/api/client-server/definitions/event-schemas/schema/core-event-schema/msgtype_infos/image_info.yaml
Unescape Escape View File

@ -0,0 +1,36 @@
$schema: http://json-schema.org/draft-04/schema#
description: Metadata about an image.
properties:
h:
description: |-
The intended display height of the image in pixels. This may
differ from the intrinsic dimensions of the image file.
type: integer
w:
description: |-
The intended display width of the image in pixels. This may
differ from the intrinsic dimensions of the image file.
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
thumbnail_url:
description: |-
The URL (typically `MXC URI`_) to a thumbnail of the image.
Only present if the thumbnail is unencrypted.
type: string
thumbnail_file:
description: |-
Information on the encrypted thumbnail file, as specified in
|encrypted_files|_. Only present if the thumbnail is encrypted.
title: EncryptedFile
type: object
thumbnail_info:
allOf:
- $ref: thumbnail_info.yaml
description: Metadata about the image referred to in ``thumbnail_url``.
title: ImageInfo
type: object

Some files were not shown because too many files have changed in this diff Show More

Write Preview
Loading…
Cancel
Save