Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-02-17 11:33:42 +01:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Format descriptions

Browse source 
Signed-off-by: Kai A. Hiller <git@kaialexhiller.de>
This commit is contained in:
Kai A. Hiller 2025-04-08 19:54:40 +02:00
parent aad66b5780
commit 00fe0a2a2c
11 changed files with 151 additions and 111 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
data/api/application-service/definitions/namespace_list.yaml
View file

@ -19,10 +19,13 @@ items:
properties:
regex:
type: string
description: A POSIX regular expression defining which values this namespace includes.
description: >-
A POSIX regular expression defining which values this namespace includes.
exclusive:
type: boolean
description: A true or false value stating whether this application service has exclusive access to events within this namespace.
description: >-
A true or false value stating whether this application service has
exclusive access to events within this namespace.
required:
- regex
- exclusive

2
data/api/application-service/definitions/protocol.yaml
View file

@ -16,7 +16,7 @@ allOf:
- type: object
properties:
instances:
description: |-
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.

24
data/api/application-service/definitions/protocol_base.yaml
View file

@ -15,7 +15,7 @@ title: Protocol
type: object
properties:
user_fields:
description: |-
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
@ -26,9 +26,9 @@ properties:
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
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
@ -41,10 +41,11 @@ properties:
type: string
example: "mxc://example.org/aBcDeFgH"
field_types:
description: |-
description: >-
The type definitions for the fields defined in `user_fields` and
`location_fields`. Each entry in those arrays MUST have an entry here.
The `string` key for this object is the field name itself.
`location_fields`. Each entry in those arrays MUST have an entry here. The
`string` key for this object is the field name itself.
May be an empty object if no fields are defined.
type: object
@ -54,10 +55,11 @@ properties:
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.
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: A placeholder serving as a valid example of the field value.

6
data/api/application-service/definitions/protocol_instance.yaml
View file

@ -20,9 +20,9 @@ properties:
example: "Freenode"
icon:
type: string
description: |-
An optional content URI representing the protocol. Overrides the one provided
at the higher level Protocol object.
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

49
data/api/application-service/definitions/registration.yaml
View file

@ -17,27 +17,37 @@ title: Registration
properties:
id:
type: string
description: A unique, user-defined ID of the application service which will never change.
description: >-
A unique, user-defined ID of the application service which will never change.
url:
type: string
description: The URL for the application service. May include a path after the domain name. Optionally set to null if no traffic is required.
description: >-
The URL for the application service. May include a path after the domain
name. Optionally set to null if no traffic is required.
as_token:
type: string
description: A secret token that the application service will use to authenticate requests to the homeserver.
description: >-
A secret token that the application service will use to authenticate
requests to the homeserver.
hs_token:
type: string
description: A secret token that the homeserver will use authenticate requests to the application service.
description: >-
A secret token that the homeserver will use authenticate requests to the
application service.
sender_localpart:
type: string
description: |-
The localpart of the user associated with the application service. Events will be sent to the AS if this user is the target of the event, or
is a joined member of the room where the event occurred.
description: >-
The localpart of the user associated with the application service. Events
will be sent to the AS if this user is the target of the event, or is a
joined member of the room where the event occurred.
receive_ephemeral:
type: boolean
x-addedInMatrixVersion: "1.13"
description: |-
Whether the application service wants to [receive ephemeral data](/application-service-api/#pushing-ephemeral-data).
description: >-
Whether the application service wants to [receive ephemeral
data](/application-service-api/#pushing-ephemeral-data).
Defaults to `false` if not present.
namespaces:
type: object
@ -47,7 +57,7 @@ properties:
users:
allOf:
- $ref: namespace_list.yaml
- description: |-
- description: >-
A list of namespaces defining the user IDs that the application
service is interested in, in addition to its `sender_localpart`.
Events will be sent to the AS if a local user matching one of the
@ -56,23 +66,26 @@ properties:
rooms:
allOf:
- $ref: namespace_list.yaml
- description: |-
- description: >-
A list of namespaces defining the room IDs that the application
service is interested in. All events sent in a room with an ID
which matches one of the namespaces will be sent to the AS.
aliases:
allOf:
- $ref: namespace_list.yaml
- description: |-
A list of namespaces defining the room aliases that the application
service is interested in. All events sent in a room with an alias
which matches one of the namespaces will be sent to the AS.
- description: >-
A list of namespaces defining the room aliases that the
application service is interested in. All events sent in a room
with an alias which matches one of the namespaces will be sent to
the AS.
rate_limited:
type: boolean
description: Whether requests from masqueraded users are rate-limited. The sender is excluded.
description: >-
Whether requests from masqueraded users are rate-limited. The sender is excluded.
protocols:
type: array
description: The external protocols which the application service provides (e.g. IRC).
description: >-
The external protocols which the application service provides (e.g. IRC).
items:
type: string
required:

3
data/api/application-service/definitions/security.yaml
View file

@ -15,4 +15,5 @@
homeserverAccessToken:
type: http
scheme: bearer
description: The `Bearer` `hs_token` provided by the application service's registration.
description: >-
The `Bearer` `hs_token` provided by the application service's registration.

14
data/api/application-service/ping.yaml
View file

@ -20,13 +20,18 @@ paths:
post:
x-addedInMatrixVersion: "1.7"
summary: Ping the application service
description: |-
description: >-
This API is called by the homeserver to ensure that the connection works
and the `hs_token` the homeserver has is correct.
Currently this is only called by the homeserver as a direct result of
the application service calling
[`POST /_matrix/client/v1/appservice/{appserviceId}/ping`](#post_matrixclientv1appserviceappserviceidping).
[`POST /_matrix/client/v1/appservice/{appserviceId}/ping`].
[`POST /_matrix/client/v1/appservice/{appserviceId}/ping`]:
<#post_matrixclientv1appserviceappserviceidping>
operationId: ping
security:
- homeserverAccessToken: []
@ -41,13 +46,14 @@ paths:
properties:
transaction_id:
type: string
description: |-
description: >-
A transaction ID for the ping, copied directly from the
`POST /_matrix/client/v1/appservice/{appserviceId}/ping` call.
description: Ping body with optional transaction ID.
responses:
"200":
description: The provided `hs_token` is valid and the ping request was successful.
description: >-
The provided `hs_token` is valid and the ping request was successful.
content:
application/json:
schema:

69
data/api/application-service/protocols.yaml
View file

@ -20,10 +20,10 @@ paths:
get:
summary: Retrieve metadata about a specific protocol that the application
service supports.
description: |-
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.
with specific information about the various third-party networks that an
application service supports.
operationId: getProtocolMetadata
security:
- homeserverAccessToken: []
@ -43,9 +43,10 @@ paths:
schema:
$ref: definitions/protocol.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.
description: >-
The homeserver has not supplied credentials to the application
service. Optional error information can be included in the body of
this response.
content:
application/json:
schema:
@ -80,10 +81,10 @@ paths:
"/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.
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: []
@ -97,9 +98,9 @@ paths:
type: string
- in: query
name: fields
description: |-
One or more custom fields that are passed to the application
service to help identify the user.
description: >-
One or more custom fields that are passed to the application service
to help identify the user.
schema:
type: object
additionalProperties:
@ -112,9 +113,10 @@ paths:
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.
description: >-
The homeserver has not supplied credentials to the application
service. Optional error information can be included in the body of
this response.
content:
application/json:
schema:
@ -149,7 +151,8 @@ paths:
"/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
description: >-
Retrieve a list of Matrix portal rooms that lead to the matched
third-party location.
operationId: queryLocationByProtocol
security:
@ -164,9 +167,9 @@ paths:
type: string
- in: query
name: fields
description: |-
One or more custom fields that are passed to the application
service to help identify the third-party location.
description: >-
One or more custom fields that are passed to the application service
to help identify the third-party location.
schema:
type: object
additionalProperties:
@ -179,9 +182,10 @@ paths:
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.
description: >-
The homeserver has not supplied credentials to the application
service. Optional error information can be included in the body of
this response.
content:
application/json:
schema:
@ -216,9 +220,8 @@ paths:
/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.
description: >-
Retrieve an array of third-party network locations from a Matrix room alias.
operationId: queryLocationByAlias
security:
- homeserverAccessToken: []
@ -236,9 +239,10 @@ paths:
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.
description: >-
The homeserver has not supplied credentials to the application
service. Optional error information can be included in the body of
this response.
content:
application/json:
schema:
@ -291,9 +295,10 @@ paths:
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.
description: >-
The homeserver has not supplied credentials to the application
service. Optional error information can be included in the body of
this response.
content:
application/json:
schema:

28
data/api/application-service/query_room.yaml
View file

@ -20,12 +20,12 @@ 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.
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: []
@ -39,7 +39,7 @@ paths:
type: string
responses:
"200":
description: |-
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
@ -53,9 +53,10 @@ paths:
response:
value: {}
"401":
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
description: >-
The homeserver has not supplied credentials to the application
service. Optional error information can be included in the body of
this response.
content:
application/json:
schema:
@ -77,9 +78,10 @@ paths:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
"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.
description: >-
The application service indicates that this room alias does not
exist. Optional error information can be included in the body of
this response.
content:
application/json:
schema:

31
data/api/application-service/query_user.yaml
View file

@ -20,12 +20,13 @@ 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.
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: []
@ -39,9 +40,9 @@ paths:
type: string
responses:
"200":
description: |-
The application service indicates that this user exists. The application
service MUST create the user using the client-server API.
description: >-
The application service indicates that this user exists. The
application service MUST create the user using the client-server API.
content:
application/json:
schema:
@ -50,9 +51,10 @@ paths:
response:
value: {}
"401":
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
description: >-
The homeserver has not supplied credentials to the application
service. Optional error information can be included in the body of
this response.
content:
application/json:
schema:
@ -74,9 +76,10 @@ paths:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
"404":
description: |-
description: >-
The application service indicates that this user does not exist.
Optional error information can be included in the body of this response.
Optional error information can be included in the body of this
response.
content:
application/json:
schema:

29
data/api/application-service/transactions.yaml
View file

@ -20,20 +20,21 @@ 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.
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.
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
description: |-
description: >-
The transaction ID for this set of events. Homeservers generate
these IDs and they are used to ensure idempotency of requests.
required: true
@ -73,15 +74,19 @@ paths:
ephemeral:
type: array
x-addedInMatrixVersion: "1.13"
description: |-
A list of ephemeral data, if the `receive_ephemeral` setting was enabled in the
description: >-
A list of ephemeral data, if the `receive_ephemeral` setting
was enabled in the
[registration](/application-service-api/#registration) file.
There are only three event types that can currently occur in this list: `m.presence`,
`m.typing`, and `m.receipt`. Room-scoped ephemeral data (`m.typing` and
`m.receipt`) MUST include a `room_id` property to identify the room that they
There are only three event types that can currently occur in
this list: `m.presence`, `m.typing`, and `m.receipt`.
Room-scoped ephemeral data (`m.typing` and `m.receipt`) MUST
include a `room_id` property to identify the room that they
were sent in.
This property can be omitted if it would be empty.
items:
$ref: ../../event-schemas/schema/core-event-schema/event.yaml