From aad66b5780ddca4e679c916a44750f2deaf545af Mon Sep 17 00:00:00 2001 From: "Kai A. Hiller" Date: Tue, 8 Apr 2025 19:50:32 +0200 Subject: [PATCH 1/3] EOL Signed-off-by: Kai A. Hiller --- data/api/application-service/definitions/location.yaml | 2 +- data/api/application-service/definitions/user.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/data/api/application-service/definitions/location.yaml b/data/api/application-service/definitions/location.yaml index 12cdad59..71919e7d 100644 --- a/data/api/application-service/definitions/location.yaml +++ b/data/api/application-service/definitions/location.yaml @@ -29,4 +29,4 @@ properties: } required: ['alias', 'protocol', 'fields'] title: Location -type: object \ No newline at end of file +type: object diff --git a/data/api/application-service/definitions/user.yaml b/data/api/application-service/definitions/user.yaml index 62cac033..83663d22 100644 --- a/data/api/application-service/definitions/user.yaml +++ b/data/api/application-service/definitions/user.yaml @@ -30,4 +30,4 @@ properties: } required: ['userid', 'protocol', 'fields'] title: User -type: object \ No newline at end of file +type: object From 00fe0a2a2c7595e58f892169d620d63cab9398d4 Mon Sep 17 00:00:00 2001 From: "Kai A. Hiller" Date: Tue, 8 Apr 2025 19:54:40 +0200 Subject: [PATCH 2/3] Format descriptions Signed-off-by: Kai A. Hiller --- .../definitions/namespace_list.yaml | 7 +- .../definitions/protocol.yaml | 2 +- .../definitions/protocol_base.yaml | 24 ++++--- .../definitions/protocol_instance.yaml | 6 +- .../definitions/registration.yaml | 49 ++++++++----- .../definitions/security.yaml | 3 +- data/api/application-service/ping.yaml | 14 ++-- data/api/application-service/protocols.yaml | 69 ++++++++++--------- data/api/application-service/query_room.yaml | 28 ++++---- data/api/application-service/query_user.yaml | 31 +++++---- .../api/application-service/transactions.yaml | 29 ++++---- 11 files changed, 151 insertions(+), 111 deletions(-) diff --git a/data/api/application-service/definitions/namespace_list.yaml b/data/api/application-service/definitions/namespace_list.yaml index 4f45fc3f..83f44c43 100644 --- a/data/api/application-service/definitions/namespace_list.yaml +++ b/data/api/application-service/definitions/namespace_list.yaml @@ -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 diff --git a/data/api/application-service/definitions/protocol.yaml b/data/api/application-service/definitions/protocol.yaml index eb56ab26..e5906018 100644 --- a/data/api/application-service/definitions/protocol.yaml +++ b/data/api/application-service/definitions/protocol.yaml @@ -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. diff --git a/data/api/application-service/definitions/protocol_base.yaml b/data/api/application-service/definitions/protocol_base.yaml index 0238104f..15ba37c4 100644 --- a/data/api/application-service/definitions/protocol_base.yaml +++ b/data/api/application-service/definitions/protocol_base.yaml @@ -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. diff --git a/data/api/application-service/definitions/protocol_instance.yaml b/data/api/application-service/definitions/protocol_instance.yaml index ef8f2566..40c67767 100644 --- a/data/api/application-service/definitions/protocol_instance.yaml +++ b/data/api/application-service/definitions/protocol_instance.yaml @@ -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 diff --git a/data/api/application-service/definitions/registration.yaml b/data/api/application-service/definitions/registration.yaml index ce702df0..4fcc70d1 100644 --- a/data/api/application-service/definitions/registration.yaml +++ b/data/api/application-service/definitions/registration.yaml @@ -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: diff --git a/data/api/application-service/definitions/security.yaml b/data/api/application-service/definitions/security.yaml index b2ba1293..88b5a220 100644 --- a/data/api/application-service/definitions/security.yaml +++ b/data/api/application-service/definitions/security.yaml @@ -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. diff --git a/data/api/application-service/ping.yaml b/data/api/application-service/ping.yaml index 277955ff..79500704 100644 --- a/data/api/application-service/ping.yaml +++ b/data/api/application-service/ping.yaml @@ -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: diff --git a/data/api/application-service/protocols.yaml b/data/api/application-service/protocols.yaml index 194bdeef..b4ed806f 100644 --- a/data/api/application-service/protocols.yaml +++ b/data/api/application-service/protocols.yaml @@ -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: diff --git a/data/api/application-service/query_room.yaml b/data/api/application-service/query_room.yaml index 57175637..03453bf3 100644 --- a/data/api/application-service/query_room.yaml +++ b/data/api/application-service/query_room.yaml @@ -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: diff --git a/data/api/application-service/query_user.yaml b/data/api/application-service/query_user.yaml index c8ca9781..9897e339 100644 --- a/data/api/application-service/query_user.yaml +++ b/data/api/application-service/query_user.yaml @@ -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: diff --git a/data/api/application-service/transactions.yaml b/data/api/application-service/transactions.yaml index 29512973..83ad7e97 100644 --- a/data/api/application-service/transactions.yaml +++ b/data/api/application-service/transactions.yaml @@ -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 From a3dc9646796d5b1527df41897ce85b824d1dcf94 Mon Sep 17 00:00:00 2001 From: "Kai A. Hiller" Date: Wed, 9 Apr 2025 10:23:27 +0200 Subject: [PATCH 3/3] Add newsfragment Signed-off-by: Kai A. Hiller --- changelogs/application_service/newsfragments/2131.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/application_service/newsfragments/2131.clarification diff --git a/changelogs/application_service/newsfragments/2131.clarification b/changelogs/application_service/newsfragments/2131.clarification new file mode 100644 index 00000000..4853bbaf --- /dev/null +++ b/changelogs/application_service/newsfragments/2131.clarification @@ -0,0 +1 @@ +Format Application Service schemas. \ No newline at end of file