mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-02-17 11:33:42 +01:00
Merge branch 'main' into reduce-table-margin
This commit is contained in:
Richard van der Hoff
GitHub
commit
10a0d1bc1b
|
|
@ -1 +0,0 @@
|
|||
Clarify that arbitrary unicode is allowed in user/room IDs and room aliases.
|
||||
|
|
@ -1 +0,0 @@
|
|||
The `POST /_matrix/client/v3/rooms/{roomId}/initialSync` endpoint is no longer deprecated, as it is still used for peeking.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify wording in the `/join` endpoints' summaries and descriptions. Contributed by @HarHarLinks.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify formats of string types.
|
||||
|
|
@ -1,2 +0,0 @@
|
|||
Document the `instance_id` field of `Protocol Instance` in the responses to
|
||||
`GET /_matrix/client/v3/thirdparty/protocols` and `GET /_matrix/client/v3/thirdparty/protocol/{protocol}`.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Applying redactions is a SHOULD for clients.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Remove `server_name` parameter from `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}` as per [MSC4213](https://github.com/matrix-org/matrix-spec-proposals/pull/4213).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify which rooms are returned from `/hierarchy`.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Clarify behaviour when the `topic` key of a `m.room.topic` event is absent, null, or empty.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Fix the example of the `GET /sync` endpoint and the `m.room.member` example used in several places.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Generate the changelog release info with Hugo, rather than the changelog generation script.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Update release steps documentation.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Remove unused `release_date` from Hugo config.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify that v1.0 of Matrix was a release prior to the current global versioning system.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix syntax highlighting and click-to-copy buttons for code blocks by purging less CSS.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix the version of the Identity Service API when Matrix 1.0 was introduced.
|
||||
1
changelogs/internal/newsfragments/2115.clarification
Normal file
1
changelogs/internal/newsfragments/2115.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Add [well-known funding manifest urls](https://floss.fund/funding-manifest/) to spec to authorise https://matrix.org/funding.json. Contributed by @HarHarLinks.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Remove the `origin` field in `PUT /send_join` responses, because it was never sent in the first place.
|
||||
|
|
@ -67,7 +67,7 @@ current_version_url = "https://spec.matrix.org/latest"
|
|||
# The following is used when status = "stable", and is displayed in various UI elements on a released version
|
||||
# of the spec.
|
||||
# major = "1"
|
||||
# minor = "13"
|
||||
# minor = "14"
|
||||
|
||||
# User interface configuration
|
||||
[params.ui]
|
||||
|
|
|
|||
93
content/changelog/v1.14.md
Normal file
93
content/changelog/v1.14.md
Normal file
|
|
@ -0,0 +1,93 @@
|
|||
---
|
||||
title: v1.14 Changelog
|
||||
linkTitle: v1.14
|
||||
type: docs
|
||||
layout: changelog
|
||||
outputs:
|
||||
- html
|
||||
- checklist
|
||||
date: 2025-03-27
|
||||
---
|
||||
|
||||
## Client-Server API
|
||||
|
||||
**New Endpoints**
|
||||
|
||||
- Add `POST /_matrix/client/v3/users/{userId}/report`, as per [MSC4260](https://github.com/matrix-org/matrix-spec-proposals/pull/4260). ([#2093](https://github.com/matrix-org/matrix-spec/issues/2093))
|
||||
|
||||
**Removed Endpoints**
|
||||
|
||||
- Remove `server_name` parameter from `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}`, as per [MSC4213](https://github.com/matrix-org/matrix-spec-proposals/pull/4213). ([#2059](https://github.com/matrix-org/matrix-spec/issues/2059))
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- The `POST /_matrix/client/v3/rooms/{roomId}/initialSync` endpoint is no longer deprecated, as it is still used for peeking. ([#2036](https://github.com/matrix-org/matrix-spec/issues/2036))
|
||||
- Clarify wording in the `/join` endpoints' summaries and descriptions. Contributed by @HarHarLinks. ([#2038](https://github.com/matrix-org/matrix-spec/issues/2038))
|
||||
- Clarify formats of string types. ([#2046](https://github.com/matrix-org/matrix-spec/issues/2046))
|
||||
- Fix various typos throughout the specification. ([#2047](https://github.com/matrix-org/matrix-spec/issues/2047), [#2048](https://github.com/matrix-org/matrix-spec/issues/2048), [#2080](https://github.com/matrix-org/matrix-spec/issues/2080), [#2091](https://github.com/matrix-org/matrix-spec/issues/2091))
|
||||
- Document the `instance_id` field of `Protocol Instance` in the responses to `GET /_matrix/client/v3/thirdparty/protocols` and `GET /_matrix/client/v3/thirdparty/protocol/{protocol}`. ([#2051](https://github.com/matrix-org/matrix-spec/issues/2051))
|
||||
- Applying redactions is a SHOULD for clients. ([#2055](https://github.com/matrix-org/matrix-spec/issues/2055))
|
||||
- Clarify which rooms are returned from `/hierarchy`. ([#2064](https://github.com/matrix-org/matrix-spec/issues/2064))
|
||||
- Clients can choose which history visibility options they offer to users when creating rooms. ([#2072](https://github.com/matrix-org/matrix-spec/issues/2072))
|
||||
|
||||
|
||||
## Server-Server API
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- Remove the `origin` field in `PUT /send_join` responses, because it was never sent in the first place. ([#2050](https://github.com/matrix-org/matrix-spec/issues/2050))
|
||||
- Clarify that `m.join_rules` should be in the `auth_events` of an `m.room.member` event with a `membership` of `knock`. ([#2063](https://github.com/matrix-org/matrix-spec/issues/2063))
|
||||
- Remove an erroneous `room_id` field in a few examples. ([#2076](https://github.com/matrix-org/matrix-spec/issues/2076))
|
||||
|
||||
|
||||
## Application Service API
|
||||
|
||||
No significant changes.
|
||||
|
||||
|
||||
## Identity Service API
|
||||
|
||||
No significant changes.
|
||||
|
||||
|
||||
## Push Gateway API
|
||||
|
||||
No significant changes.
|
||||
|
||||
|
||||
## Room Versions
|
||||
|
||||
**Backwards Compatible Changes**
|
||||
|
||||
- Update the default room version to 11, as per [MSC4239](https://github.com/matrix-org/matrix-spec-proposals/pull/4239). ([#2105](https://github.com/matrix-org/matrix-spec/issues/2105))
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- For room versions 6 and 7, clarify in the authorization rules that `m.federate` must be checked and that events with rejected auth events must be rejected, for parity with all the other room versions. ([#2065](https://github.com/matrix-org/matrix-spec/issues/2065))
|
||||
- Fix various typos throughout the specification. ([#2066](https://github.com/matrix-org/matrix-spec/issues/2066))
|
||||
- Refactor PDU definitions to reduce duplication. ([#2070](https://github.com/matrix-org/matrix-spec/issues/2070))
|
||||
- Clarify the maximum `depth` value for room versions 6, 7, 8, 9, 10, and 11. ([#2114](https://github.com/matrix-org/matrix-spec/issues/2114))
|
||||
|
||||
|
||||
## Appendices
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- Clarify that arbitrary unicode is allowed in user/room IDs and room aliases. ([#1506](https://github.com/matrix-org/matrix-spec/issues/1506))
|
||||
|
||||
|
||||
## Internal Changes/Tooling
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- Generate the changelog release info with Hugo, rather than the changelog generation script. ([#2033](https://github.com/matrix-org/matrix-spec/issues/2033))
|
||||
- Update release steps documentation. ([#2041](https://github.com/matrix-org/matrix-spec/issues/2041))
|
||||
- Remove unused `release_date` from Hugo config. ([#2042](https://github.com/matrix-org/matrix-spec/issues/2042))
|
||||
- Clarify that v1.0 of Matrix was a release prior to the current global versioning system. ([#2045](https://github.com/matrix-org/matrix-spec/issues/2045))
|
||||
- Fix syntax highlighting and click-to-copy buttons for code blocks by purging less CSS. ([#2049](https://github.com/matrix-org/matrix-spec/issues/2049))
|
||||
- Fix the version of the Identity Service API when Matrix 1.0 was introduced. ([#2061](https://github.com/matrix-org/matrix-spec/issues/2061))
|
||||
- Fix parsing of nested slices in `resolve-refs` and `resolve-allof` partials. ([#2069](https://github.com/matrix-org/matrix-spec/issues/2069))
|
||||
- Deduplicate the definition of `RoomKeysUpdateResponse`. ([#2073](https://github.com/matrix-org/matrix-spec/issues/2073))
|
||||
- Deduplicate the definitions of `Invite3pid`. ([#2074](https://github.com/matrix-org/matrix-spec/issues/2074))
|
||||
- Support more locations for examples in OpenAPI definitions and JSON schemas. ([#2076](https://github.com/matrix-org/matrix-spec/issues/2076))
|
||||
- Add link to the git commit for the unstable changelog. ([#2078](https://github.com/matrix-org/matrix-spec/issues/2078))
|
||||
|
|
@ -43,11 +43,8 @@ setting at that time was more restrictive.
|
|||
|
||||
#### Client behaviour
|
||||
|
||||
Clients that implement this module MUST present to the user the possible
|
||||
options for setting history visibility when creating a room.
|
||||
|
||||
Clients may want to display a notice that their events may be read by
|
||||
non-joined people if the value is set to `world_readable`.
|
||||
Clients may want to display a notice that events may be read by
|
||||
non-joined people if the history visibility is set to `world_readable`.
|
||||
|
||||
#### Server behaviour
|
||||
|
||||
|
|
|
|||
|
|
@ -29,3 +29,9 @@ is in before accepting a report.
|
|||
based on whether or not the reporting user is joined to the room. This is
|
||||
because users can be exposed to harmful content without being joined to a
|
||||
room. For instance, through room directories or invites.
|
||||
|
||||
{{% added-in v="1.14" %}} Similarly, servers MUST NOT restrict user reports
|
||||
based on whether or not the reporting user is joined to any rooms that the
|
||||
reported user is joined to. This is because users can be exposed to harmful
|
||||
content without being joined to a room. For instance, through user
|
||||
directories or invites.
|
||||
|
|
|
|||
|
|
@ -58,7 +58,7 @@ available on all their clients. Unless the user specifies otherwise,
|
|||
clients will try to use the default key to decrypt secrets.
|
||||
|
||||
Clients that want to present a simplified interface to users by not supporting
|
||||
multiple keys should use the default key if one is specified. If not default
|
||||
multiple keys should use the default key if one is specified. If no default
|
||||
key is specified, the client may behave as if there is no key is present at
|
||||
all. When such a client creates a key, it should mark that key as being the
|
||||
default key.
|
||||
|
|
|
|||
|
|
@ -52,7 +52,7 @@ stable and unstable periodically for a variety of reasons, including
|
|||
discovered security vulnerabilities and age.
|
||||
|
||||
Clients should not ask room administrators to upgrade their rooms if the
|
||||
room is running a stable version. Servers SHOULD use **room version 10** as
|
||||
room is running a stable version. Servers SHOULD use **room version 11** as
|
||||
the default room version when creating new rooms.
|
||||
|
||||
The available room versions are:
|
||||
|
|
|
|||
4
content/rooms/fragments/v6-event-format.md
Normal file
4
content/rooms/fragments/v6-event-format.md
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
|
||||
Events in rooms of this version have the following structure:
|
||||
|
||||
{{% definition path="api/server-server/definitions/pdu_v6" %}}
|
||||
|
|
@ -51,7 +51,7 @@ inconsistencies may occur.
|
|||
|
||||
Events in version 1 rooms have the following structure:
|
||||
|
||||
{{% definition path="api/server-server/definitions/pdu" %}}
|
||||
{{% definition path="api/server-server/definitions/pdu_v1" %}}
|
||||
|
||||
#### Deprecated event content schemas
|
||||
|
||||
|
|
|
|||
|
|
@ -281,7 +281,7 @@ completeness.
|
|||
|
||||
### Event format
|
||||
|
||||
{{% rver-fragment name="v4-event-format" %}}
|
||||
{{% rver-fragment name="v6-event-format" %}}
|
||||
|
||||
### State resolution
|
||||
|
||||
|
|
|
|||
|
|
@ -49,7 +49,7 @@ completeness.
|
|||
|
||||
Events in rooms of this version have the following structure:
|
||||
|
||||
{{% definition path="api/server-server/definitions/pdu" %}}
|
||||
{{% definition path="api/server-server/definitions/pdu_v1" %}}
|
||||
|
||||
#### Deprecated event content schemas
|
||||
|
||||
|
|
|
|||
|
|
@ -39,6 +39,13 @@ in [room version 5](/rooms/v5).
|
|||
|
||||
[See above](#redactions).
|
||||
|
||||
### Event format
|
||||
|
||||
{{% added-in v=6 %}} Through enforcement of [Canonical JSON](#canonical-json),
|
||||
the `depth` limit has been reduced in this room version.
|
||||
|
||||
{{% rver-fragment name="v6-event-format" %}}
|
||||
|
||||
### Authorization rules
|
||||
|
||||
{{% added-in v=6 %}} Rule 4, which related specifically to events
|
||||
|
|
@ -88,14 +95,20 @@ The rules are as follows:
|
|||
version, reject.
|
||||
4. If `content` has no `creator` property, reject.
|
||||
5. Otherwise, allow.
|
||||
2. Reject if event has `auth_events` that:
|
||||
1. have duplicate entries for a given `type` and `state_key` pair
|
||||
2. have entries whose `type` and `state_key` don't match those
|
||||
2. Considering the event's `auth_events`:
|
||||
1. If there are duplicate entries for a given `type` and `state_key` pair,
|
||||
reject.
|
||||
2. If there are entries whose `type` and `state_key` don't match those
|
||||
specified by the [auth events
|
||||
selection](/server-server-api#auth-events-selection)
|
||||
algorithm described in the server specification.
|
||||
3. If event does not have a `m.room.create` in its `auth_events`,
|
||||
reject.
|
||||
algorithm described in the server specification, reject.
|
||||
3. If there are entries which were themselves rejected under the [checks
|
||||
performed on receipt of a
|
||||
PDU](/server-server-api/#checks-performed-on-receipt-of-a-pdu), reject.
|
||||
4. If there is no `m.room.create` event among the entries, reject.
|
||||
3. If the `content` of the `m.room.create` event in the room state has the
|
||||
property `m.federate` set to `false`, and the `sender` domain of the event
|
||||
does not match the `sender` domain of the create event, reject.
|
||||
4. If type is `m.room.member`:
|
||||
1. If there is no `state_key` property, or no `membership` property in
|
||||
`content`, reject.
|
||||
|
|
@ -223,10 +236,6 @@ completeness.
|
|||
|
||||
{{% rver-fragment name="v4-event-ids" %}}
|
||||
|
||||
### Event format
|
||||
|
||||
{{% rver-fragment name="v4-event-format" %}}
|
||||
|
||||
#### Deprecated event content schemas
|
||||
|
||||
{{% rver-fragment name="v1-deprecated-formatting-off-spec" %}}
|
||||
|
|
|
|||
|
|
@ -74,14 +74,20 @@ The rules are as follows:
|
|||
version, reject.
|
||||
4. If `content` has no `creator` property, reject.
|
||||
5. Otherwise, allow.
|
||||
2. Reject if event has `auth_events` that:
|
||||
1. have duplicate entries for a given `type` and `state_key` pair
|
||||
2. have entries whose `type` and `state_key` don't match those
|
||||
2. Considering the event's `auth_events`:
|
||||
1. If there are duplicate entries for a given `type` and `state_key` pair,
|
||||
reject.
|
||||
2. If there are entries whose `type` and `state_key` don't match those
|
||||
specified by the [auth events
|
||||
selection](/server-server-api#auth-events-selection)
|
||||
algorithm described in the server specification.
|
||||
3. If event does not have a `m.room.create` in its `auth_events`,
|
||||
reject.
|
||||
algorithm described in the server specification, reject.
|
||||
3. If there are entries which were themselves rejected under the [checks
|
||||
performed on receipt of a
|
||||
PDU](/server-server-api/#checks-performed-on-receipt-of-a-pdu), reject.
|
||||
4. If there is no `m.room.create` event among the entries, reject.
|
||||
3. If the `content` of the `m.room.create` event in the room state has the
|
||||
property `m.federate` set to `false`, and the `sender` domain of the event
|
||||
does not match the `sender` domain of the create event, reject.
|
||||
4. If type is `m.room.member`:
|
||||
1. If there is no `state_key` property, or no `membership` property in
|
||||
`content`, reject.
|
||||
|
|
@ -219,7 +225,7 @@ completeness.
|
|||
|
||||
### Event format
|
||||
|
||||
{{% rver-fragment name="v4-event-format" %}}
|
||||
{{% rver-fragment name="v6-event-format" %}}
|
||||
|
||||
#### Deprecated event content schemas
|
||||
|
||||
|
|
|
|||
|
|
@ -109,7 +109,7 @@ completeness.
|
|||
|
||||
### Event format
|
||||
|
||||
{{% rver-fragment name="v4-event-format" %}}
|
||||
{{% rver-fragment name="v6-event-format" %}}
|
||||
|
||||
#### Deprecated event content schemas
|
||||
|
||||
|
|
|
|||
|
|
@ -74,7 +74,7 @@ completeness.
|
|||
|
||||
### Event format
|
||||
|
||||
{{% rver-fragment name="v4-event-format" %}}
|
||||
{{% rver-fragment name="v6-event-format" %}}
|
||||
|
||||
#### Deprecated event content schemas
|
||||
|
||||
|
|
|
|||
|
|
@ -537,7 +537,7 @@ the following subset of the room state:
|
|||
- If type is `m.room.member`:
|
||||
|
||||
- The target's current `m.room.member` event, if any.
|
||||
- If `membership` is `join` or `invite`, the current
|
||||
- If `membership` is `join`, `invite` or `knock`, the current
|
||||
`m.room.join_rules` event, if any.
|
||||
- If membership is `invite` and `content` contains a
|
||||
`third_party_invite` property, the current
|
||||
|
|
@ -1337,7 +1337,7 @@ calculated as follows.
|
|||
The *content hash* of an event covers the complete event including the
|
||||
*unredacted* contents. It is calculated as follows.
|
||||
|
||||
First, any existing `unsigned`, `signature`, and `hashes` members are
|
||||
First, any existing `unsigned`, `signatures`, and `hashes` properties are
|
||||
removed. The resulting object is then encoded as [Canonical
|
||||
JSON](/appendices#canonical-json), and the JSON is hashed using
|
||||
SHA-256.
|
||||
|
|
|
|||
|
|
@ -131,32 +131,7 @@ paths:
|
|||
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
|
||||
description: |-
|
||||
The kind of address being passed in the address field, for example `email`
|
||||
(see [the list of recognised values](/appendices/#3pid-types)).
|
||||
address:
|
||||
type: string
|
||||
description: The invitee's third-party identifier.
|
||||
required:
|
||||
- id_server
|
||||
- id_access_token
|
||||
- medium
|
||||
- address
|
||||
$ref: definitions/invite_3pid.yaml
|
||||
room_version:
|
||||
type: string
|
||||
description: |-
|
||||
|
|
|
|||
45
data/api/client-server/definitions/invite_3pid.yaml
Normal file
45
data/api/client-server/definitions/invite_3pid.yaml
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
# Copyright 2025 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: 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
|
||||
description: |-
|
||||
The kind of address being passed in the address field, for example `email`
|
||||
(see [the list of recognised values](/appendices/#3pid-types)).
|
||||
address:
|
||||
type: string
|
||||
description: The invitee's third-party identifier.
|
||||
required:
|
||||
- id_server
|
||||
- id_access_token
|
||||
- medium
|
||||
- address
|
||||
example: {
|
||||
"id_server": "matrix.org",
|
||||
"id_access_token": "abc123_OpaqueString",
|
||||
"medium": "email",
|
||||
"address": "cheeky@monkey.com"
|
||||
}
|
||||
|
|
@ -438,22 +438,7 @@ paths:
|
|||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
title: RoomKeysUpdateResponse
|
||||
properties:
|
||||
etag:
|
||||
description: |-
|
||||
The new etag value representing stored keys in the backup.
|
||||
See `GET /room_keys/version/{version}` for more details.
|
||||
type: string
|
||||
example: abcdefg
|
||||
count:
|
||||
description: The number of keys stored in the backup
|
||||
type: integer
|
||||
example: 10
|
||||
required:
|
||||
- etag
|
||||
- count
|
||||
$ref: "#/components/schemas/RoomKeysUpdateResponse"
|
||||
"403":
|
||||
description: |-
|
||||
The version specified does not match the current backup version.
|
||||
|
|
@ -571,22 +556,7 @@ paths:
|
|||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
title: RoomKeysUpdateResponse
|
||||
properties:
|
||||
etag:
|
||||
description: |-
|
||||
The new etag value representing stored keys in the backup.
|
||||
See `GET /room_keys/version/{version}` for more details.
|
||||
type: string
|
||||
example: abcdefg
|
||||
count:
|
||||
description: The number of keys stored in the backup
|
||||
type: integer
|
||||
example: 10
|
||||
required:
|
||||
- etag
|
||||
- count
|
||||
$ref: "#/components/schemas/RoomKeysUpdateResponse"
|
||||
"404":
|
||||
description: The backup was not found.
|
||||
content:
|
||||
|
|
@ -644,22 +614,7 @@ paths:
|
|||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
title: RoomKeysUpdateResponse
|
||||
properties:
|
||||
etag:
|
||||
description: |-
|
||||
The new etag value representing stored keys in the backup.
|
||||
See `GET /room_keys/version/{version}` for more details.
|
||||
type: string
|
||||
example: abcdefg
|
||||
count:
|
||||
description: The number of keys stored in the backup
|
||||
type: integer
|
||||
example: 10
|
||||
required:
|
||||
- etag
|
||||
- count
|
||||
$ref: "#/components/schemas/RoomKeysUpdateResponse"
|
||||
"403":
|
||||
description: |-
|
||||
The version specified does not match the current backup version.
|
||||
|
|
@ -778,22 +733,7 @@ paths:
|
|||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
title: RoomKeysUpdateResponse
|
||||
properties:
|
||||
etag:
|
||||
description: |-
|
||||
The new etag value representing stored keys in the backup.
|
||||
See `GET /room_keys/version/{version}` for more details.
|
||||
type: string
|
||||
example: abcdefg
|
||||
count:
|
||||
description: The number of keys stored in the backup
|
||||
type: integer
|
||||
example: 10
|
||||
required:
|
||||
- etag
|
||||
- count
|
||||
$ref: "#/components/schemas/RoomKeysUpdateResponse"
|
||||
"404":
|
||||
description: The backup was not found.
|
||||
content:
|
||||
|
|
@ -866,22 +806,7 @@ paths:
|
|||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
title: RoomKeysUpdateResponse
|
||||
properties:
|
||||
etag:
|
||||
description: |-
|
||||
The new etag value representing stored keys in the backup.
|
||||
See `GET /room_keys/version/{version}` for more details.
|
||||
type: string
|
||||
example: abcdefg
|
||||
count:
|
||||
description: The number of keys stored in the backup
|
||||
type: integer
|
||||
example: 10
|
||||
required:
|
||||
- etag
|
||||
- count
|
||||
$ref: "#/components/schemas/RoomKeysUpdateResponse"
|
||||
"403":
|
||||
description: |-
|
||||
The version specified does not match the current backup version.
|
||||
|
|
@ -1007,22 +932,7 @@ paths:
|
|||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
title: RoomKeysUpdateResponse
|
||||
properties:
|
||||
etag:
|
||||
description: |-
|
||||
The new etag value representing stored keys in the backup.
|
||||
See `GET /room_keys/version/{version}` for more details.
|
||||
type: string
|
||||
example: abcdefg
|
||||
count:
|
||||
description: The number of keys stored in the backup
|
||||
type: integer
|
||||
example: 10
|
||||
required:
|
||||
- etag
|
||||
- count
|
||||
$ref: "#/components/schemas/RoomKeysUpdateResponse"
|
||||
"404":
|
||||
description: The backup was not found.
|
||||
content:
|
||||
|
|
@ -1056,6 +966,26 @@ servers:
|
|||
basePath:
|
||||
default: /_matrix/client/v3
|
||||
components:
|
||||
schemas:
|
||||
RoomKeysUpdateResponse:
|
||||
type: object
|
||||
title: RoomKeysUpdateResponse
|
||||
properties:
|
||||
etag:
|
||||
description: |-
|
||||
The new etag value representing stored keys in the backup.
|
||||
|
||||
See [`GET /room_keys/version/{version}`](client-server-api/#get_matrixclientv3room_keysversionversion)
|
||||
for more details.
|
||||
type: string
|
||||
example: abcdefg
|
||||
count:
|
||||
description: The number of keys stored in the backup
|
||||
type: integer
|
||||
example: 10
|
||||
required:
|
||||
- etag
|
||||
- count
|
||||
securitySchemes:
|
||||
accessTokenQuery:
|
||||
$ref: definitions/security.yaml#/accessTokenQuery
|
||||
|
|
|
|||
|
|
@ -214,7 +214,7 @@ paths:
|
|||
- public
|
||||
description: |-
|
||||
Whether this room is visible to the `/publicRooms` API
|
||||
or not."
|
||||
or not.
|
||||
account_data:
|
||||
type: array
|
||||
description: |-
|
||||
|
|
|
|||
|
|
@ -45,7 +45,9 @@ paths:
|
|||
properties:
|
||||
reason:
|
||||
type: string
|
||||
description: The reason the room is being reported.
|
||||
description: The reason the room is being reported. May be blank.
|
||||
required:
|
||||
- reason
|
||||
required: true
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
|
|
@ -88,12 +90,11 @@ paths:
|
|||
Reports an event as inappropriate to the server, which may then notify
|
||||
the appropriate people. The caller must be joined to the room to report
|
||||
it.
|
||||
|
||||
It might be possible for clients to deduce whether an event exists by
|
||||
timing the response, as only a report for an event that does exist
|
||||
will require the homeserver to check whether a user is joined to
|
||||
the room. To combat this, homeserver implementations should add
|
||||
a random delay when generating a response.
|
||||
|
||||
Furthermore, it might be possible for clients to deduce whether a reported
|
||||
event exists by timing the response. This is because only a report for an
|
||||
existing event will require the homeserver to do further processing. To
|
||||
combat this, homeservers MAY add a random delay when generating a response.
|
||||
operationId: reportEvent
|
||||
parameters:
|
||||
- in: path
|
||||
|
|
@ -164,6 +165,88 @@ paths:
|
|||
}
|
||||
tags:
|
||||
- Reporting content
|
||||
"/users/{userId}/report":
|
||||
post:
|
||||
x-addedInMatrixVersion: "1.14"
|
||||
summary: Report a user as inappropriate.
|
||||
description: |-
|
||||
Reports a user as inappropriate to the server, which may then notify
|
||||
the appropriate people. How such information is delivered is left up to
|
||||
implementations. The caller is not required to be joined to any rooms
|
||||
that the reported user is joined to.
|
||||
|
||||
Clients may wish to [ignore](#ignoring-users) users after reporting them.
|
||||
|
||||
Clients could infer whether a reported user exists based on the 404 response.
|
||||
Homeservers that wish to conceal this information MAY return 200 responses
|
||||
regardless of the existence of the reported user.
|
||||
|
||||
Furthermore, it might be possible for clients to deduce whether a reported
|
||||
user exists by timing the response. This is because only a report for an
|
||||
existing user will require the homeserver to do further processing. To
|
||||
combat this, homeservers MAY add a random delay when generating a response.
|
||||
operationId: reportUser
|
||||
parameters:
|
||||
- in: path
|
||||
name: userId
|
||||
description: The user being reported.
|
||||
required: true
|
||||
example: "@someguy:example.com"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
example: {
|
||||
"reason": "this makes me sad"
|
||||
}
|
||||
properties:
|
||||
reason:
|
||||
type: string
|
||||
description: The reason the room is being reported. May be blank.
|
||||
required:
|
||||
- reason
|
||||
required: true
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
- accessTokenBearer: []
|
||||
responses:
|
||||
"200":
|
||||
description: |
|
||||
The user has been reported successfully or the server chose
|
||||
to not disclose whether the users exists.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
examples:
|
||||
response:
|
||||
value: {}
|
||||
"404":
|
||||
description: |-
|
||||
The user was not found on the homeserver.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "The user was not found."
|
||||
}
|
||||
"429":
|
||||
description: This request was rate-limited.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/rate_limited.yaml
|
||||
tags:
|
||||
- Reporting content
|
||||
servers:
|
||||
- url: "{protocol}://{hostname}{basePath}"
|
||||
variables:
|
||||
|
|
|
|||
|
|
@ -96,7 +96,7 @@ paths:
|
|||
- public
|
||||
description: |-
|
||||
Whether this room is visible to the `/publicRooms` API
|
||||
or not."
|
||||
or not.
|
||||
account_data:
|
||||
type: array
|
||||
description: The private data that this user has attached to this room.
|
||||
|
|
|
|||
|
|
@ -441,17 +441,57 @@ paths:
|
|||
"state": {
|
||||
"events": [
|
||||
{
|
||||
"$ref": "../../event-schemas/examples/m.room.member.yaml"
|
||||
"content": {
|
||||
"avatar_url": "mxc://example.org/SFHyPlCeYUSFFxlgbQYZmoEoe",
|
||||
"displayname": "Example user",
|
||||
"membership": "join"
|
||||
},
|
||||
"event_id": "$143273976499sgjks:example.org",
|
||||
"origin_server_ts": 1432735824653,
|
||||
"sender": "@example:example.org",
|
||||
"state_key": "@example:example.org",
|
||||
"type": "m.room.member",
|
||||
"unsigned": {
|
||||
"age": 45603,
|
||||
"membership": "join"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"timeline": {
|
||||
"events": [
|
||||
{
|
||||
"$ref": "../../event-schemas/examples/m.room.member.yaml"
|
||||
"content": {
|
||||
"avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
|
||||
"displayname": "Alice Margatroid",
|
||||
"membership": "join",
|
||||
"reason": "Looking for support"
|
||||
},
|
||||
"event_id": "$143273582443PhrSn:example.org",
|
||||
"origin_server_ts": 1432735824653,
|
||||
"sender": "@alice:example.org",
|
||||
"state_key": "@alice:example.org",
|
||||
"type": "m.room.member",
|
||||
"unsigned": {
|
||||
"age": 1234,
|
||||
"membership": "join"
|
||||
}
|
||||
},
|
||||
{
|
||||
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
|
||||
"content": {
|
||||
"body": "This is an example text message",
|
||||
"format": "org.matrix.custom.html",
|
||||
"formatted_body": "<b>This is an example text message</b>",
|
||||
"msgtype": "m.text"
|
||||
},
|
||||
"event_id": "$143273582443PhrSn:example.org",
|
||||
"origin_server_ts": 1432735824653,
|
||||
"sender": "@example:example.org",
|
||||
"type": "m.room.message",
|
||||
"unsigned": {
|
||||
"age": 1234,
|
||||
"membership": "join"
|
||||
}
|
||||
}
|
||||
],
|
||||
"limited": true,
|
||||
|
|
|
|||
|
|
@ -76,37 +76,7 @@ paths:
|
|||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
example: {
|
||||
"id_server": "matrix.org",
|
||||
"id_access_token": "abc123_OpaqueString",
|
||||
"medium": "email",
|
||||
"address": "cheeky@monkey.com"
|
||||
}
|
||||
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
|
||||
description: |-
|
||||
The kind of address being passed in the address field, for example
|
||||
`email` (see [the list of recognised values](/appendices/#3pid-types)).
|
||||
address:
|
||||
type: string
|
||||
description: The invitee's third-party identifier.
|
||||
required:
|
||||
- id_server
|
||||
- id_access_token
|
||||
- medium
|
||||
- address
|
||||
$ref: definitions/invite_3pid.yaml
|
||||
required: true
|
||||
responses:
|
||||
"200":
|
||||
|
|
|
|||
|
|
@ -0,0 +1,45 @@
|
|||
# Copyright 2025 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
|
||||
description: |-
|
||||
The auth_events and prev_events fields of PDUs for room version 4
|
||||
and beyond.
|
||||
properties:
|
||||
auth_events:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Event ID.
|
||||
description: |-
|
||||
Event IDs for the authorization events that would
|
||||
allow this event to be in the room.
|
||||
|
||||
Must contain less than or equal to 10 events. Note that if the relevant
|
||||
auth event selection rules are used, this restriction should never be
|
||||
encountered.
|
||||
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
|
||||
prev_events:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Event ID.
|
||||
description: |-
|
||||
Event IDs for the most recent events in the room
|
||||
that the homeserver was aware of when it made this event.
|
||||
|
||||
Must contain less than or equal to 20 events.
|
||||
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
|
||||
required:
|
||||
- auth_events
|
||||
- prev_events
|
||||
|
|
@ -12,10 +12,7 @@
|
|||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
type: object
|
||||
title: Unsigned Persistent Data Unit
|
||||
description: An unsigned persistent data unit (event)
|
||||
example:
|
||||
$ref: "../examples/unsigned_pdu_base.json"
|
||||
description: Common fields for all PDU versions
|
||||
properties:
|
||||
room_id:
|
||||
type: string
|
||||
|
|
@ -44,49 +41,22 @@ properties:
|
|||
type: object
|
||||
description: The content of the event.
|
||||
example: {"key": "value"}
|
||||
prev_events:
|
||||
type: array
|
||||
hashes:
|
||||
$ref: "event_hash.yaml"
|
||||
signatures:
|
||||
type: object
|
||||
description: |-
|
||||
Event IDs and reference hashes for the most recent events in the room
|
||||
that the homeserver was aware of when it made this event.
|
||||
|
||||
Must contain less than or equal to 20 events.
|
||||
items:
|
||||
type: array
|
||||
maxItems: 2
|
||||
minItems: 2
|
||||
items:
|
||||
anyOf:
|
||||
- type: string
|
||||
title: Event ID
|
||||
example: "$abc123:matrix.org"
|
||||
- $ref: "event_hash.yaml"
|
||||
depth:
|
||||
type: integer
|
||||
description: |-
|
||||
The maximum depth of the `prev_events`, plus one. Must be less than the
|
||||
maximum value for an integer (2^63 - 1). If the room's depth is already at
|
||||
the limit, the depth must be set to the limit.
|
||||
example: 12
|
||||
auth_events:
|
||||
type: array
|
||||
description: |-
|
||||
Event IDs and reference hashes for the authorization events that would
|
||||
allow this event to be in the room.
|
||||
|
||||
Must contain less than or equal to 10 events. Note that if the relevant
|
||||
auth event selection rules are used, this restriction should never be
|
||||
encountered.
|
||||
items:
|
||||
type: array
|
||||
maxItems: 2
|
||||
minItems: 2
|
||||
items:
|
||||
anyOf:
|
||||
- type: string
|
||||
title: Event ID
|
||||
example: "$abc123:matrix.org"
|
||||
- $ref: "event_hash.yaml"
|
||||
Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
|
||||
example: {
|
||||
"example.com": {
|
||||
"ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent"
|
||||
}
|
||||
}
|
||||
additionalProperties:
|
||||
type: object
|
||||
title: Server Signatures
|
||||
additionalProperties:
|
||||
type: string
|
||||
unsigned:
|
||||
type: object
|
||||
title: UnsignedData
|
||||
|
|
@ -99,12 +69,11 @@ properties:
|
|||
description: The number of milliseconds that have passed since this message was sent.
|
||||
example: 4612
|
||||
required:
|
||||
- event_id
|
||||
- room_id
|
||||
- sender
|
||||
- origin_server_ts
|
||||
- type
|
||||
- content
|
||||
- prev_events
|
||||
- depth
|
||||
- auth_events
|
||||
- hashes
|
||||
- signatures
|
||||
77
data/api/server-server/definitions/pdu_v1.yaml
Normal file
77
data/api/server-server/definitions/pdu_v1.yaml
Normal file
|
|
@ -0,0 +1,77 @@
|
|||
# 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
|
||||
title: Persistent Data Unit
|
||||
description: A persistent data unit (event) for room versions 1 and 2.
|
||||
example:
|
||||
$ref: "../examples/pdu_v1.json"
|
||||
allOf:
|
||||
- $ref: "components/pdu_base.yaml"
|
||||
- type: object
|
||||
properties:
|
||||
event_id:
|
||||
type: string
|
||||
description: The event ID for the PDU.
|
||||
example: "$a4ecee13e2accdadf56c1025:example.com"
|
||||
redacts:
|
||||
type: string
|
||||
description: For redaction events, the ID of the event being redacted.
|
||||
example: "$def456:matrix.org"
|
||||
depth:
|
||||
type: integer
|
||||
description: |-
|
||||
The maximum depth of the `prev_events`, plus one. Must be less than the
|
||||
maximum value for an integer (2^63 - 1). If the room's depth is already at
|
||||
the limit, the depth must be set to the limit.
|
||||
example: 12
|
||||
auth_events:
|
||||
type: array
|
||||
description: |-
|
||||
Event IDs and reference hashes for the authorization events that would
|
||||
allow this event to be in the room.
|
||||
|
||||
Must contain less than or equal to 10 events. Note that if the relevant
|
||||
auth event selection rules are used, this restriction should never be
|
||||
encountered.
|
||||
items:
|
||||
type: array
|
||||
maxItems: 2
|
||||
minItems: 2
|
||||
items:
|
||||
anyOf:
|
||||
- type: string
|
||||
title: Event ID
|
||||
example: "$abc123:matrix.org"
|
||||
- $ref: "components/event_hash.yaml"
|
||||
prev_events:
|
||||
type: array
|
||||
description: |-
|
||||
Event IDs and reference hashes for the most recent events in the room
|
||||
that the homeserver was aware of when it made this event.
|
||||
|
||||
Must contain less than or equal to 20 events.
|
||||
items:
|
||||
type: array
|
||||
maxItems: 2
|
||||
minItems: 2
|
||||
items:
|
||||
anyOf:
|
||||
- type: string
|
||||
title: Event ID
|
||||
example: "$abc123:matrix.org"
|
||||
- $ref: "components/event_hash.yaml"
|
||||
required:
|
||||
- event_id
|
||||
- auth_events
|
||||
- prev_events
|
||||
|
|
@ -17,53 +17,16 @@ description: A persistent data unit (event) for room version 11 and beyond.
|
|||
example:
|
||||
$ref: "../examples/pdu_v11.json"
|
||||
allOf:
|
||||
# v11 is the v4 event, but without redacts. Copy the auth_events/prev_events
|
||||
# from pdu_v4.yaml and hashes and signatures from pdu_v3.yaml.
|
||||
- $ref: "unsigned_pdu_base.yaml"
|
||||
# v11 is the v6 event, but without redacts.
|
||||
- $ref: "components/pdu_base.yaml"
|
||||
- $ref: "components/auth_events_prev_events_v4.yaml"
|
||||
- type: object
|
||||
properties:
|
||||
auth_events:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Event ID.
|
||||
# v6 enforces Canonical JSON and therefore needs a depth limit change
|
||||
depth:
|
||||
type: integer
|
||||
description: |-
|
||||
Event IDs for the authorization events that would
|
||||
allow this event to be in the room.
|
||||
|
||||
Must contain less than or equal to 10 events. Note that if the relevant
|
||||
auth event selection rules are used, this restriction should never be
|
||||
encountered.
|
||||
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
|
||||
prev_events:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Event ID.
|
||||
description: |-
|
||||
Event IDs for the most recent events in the room
|
||||
that the homeserver was aware of when it made this event.
|
||||
|
||||
Must contain less than or equal to 20 events.
|
||||
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
|
||||
hashes:
|
||||
$ref: "event_hash.yaml"
|
||||
signatures:
|
||||
type: object
|
||||
description: |-
|
||||
Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
|
||||
example: {
|
||||
"example.com": {
|
||||
"ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent"
|
||||
}
|
||||
}
|
||||
additionalProperties:
|
||||
type: object
|
||||
title: Server Signatures
|
||||
additionalProperties:
|
||||
type: string
|
||||
required:
|
||||
- auth_events
|
||||
- prev_events
|
||||
- hashes
|
||||
- signatures
|
||||
The maximum depth of the `prev_events`, plus one. Must be less than the
|
||||
maximum value for an integer (2^53 - 1). If the room's depth is already at
|
||||
the limit, the depth must be set to the limit.
|
||||
example: 12
|
||||
|
|
@ -13,17 +13,24 @@
|
|||
# limitations under the License.
|
||||
type: object
|
||||
title: Persistent Data Unit
|
||||
description: A persistent data unit (event) for room version 3 and beyond.
|
||||
description: A persistent data unit (event) for room version 3.
|
||||
example:
|
||||
$ref: "../examples/pdu_v3.json"
|
||||
allOf:
|
||||
- $ref: "unsigned_pdu_base.yaml"
|
||||
- $ref: "components/pdu_base.yaml"
|
||||
- type: object
|
||||
properties:
|
||||
redacts:
|
||||
type: string
|
||||
description: For redaction events, the ID of the event being redacted.
|
||||
example: "$def/456+oldevent"
|
||||
depth:
|
||||
type: integer
|
||||
description: |-
|
||||
The maximum depth of the `prev_events`, plus one. Must be less than the
|
||||
maximum value for an integer (2^63 - 1). If the room's depth is already at
|
||||
the limit, the depth must be set to the limit.
|
||||
example: 12
|
||||
auth_events:
|
||||
type: array
|
||||
items:
|
||||
|
|
@ -48,24 +55,6 @@ allOf:
|
|||
|
||||
Must contain less than or equal to 20 events.
|
||||
example: ["$base64EncodedHash", "$AnotherEvent"]
|
||||
hashes:
|
||||
$ref: "event_hash.yaml"
|
||||
signatures:
|
||||
type: object
|
||||
description: |-
|
||||
Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
|
||||
example: {
|
||||
"example.com": {
|
||||
"ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent"
|
||||
}
|
||||
}
|
||||
additionalProperties:
|
||||
type: object
|
||||
title: Server Signatures
|
||||
additionalProperties:
|
||||
type: string
|
||||
required:
|
||||
- auth_events
|
||||
- prev_events
|
||||
- hashes
|
||||
- signatures
|
||||
|
|
|
|||
|
|
@ -13,41 +13,23 @@
|
|||
# limitations under the License.
|
||||
type: object
|
||||
title: Persistent Data Unit
|
||||
description: A persistent data unit (event) for room version 4 and beyond.
|
||||
description: |-
|
||||
A persistent data unit (event) for room versions 4, 5, 6, 7, 8, 9 and 10.
|
||||
example:
|
||||
$ref: "../examples/pdu_v4.json"
|
||||
allOf:
|
||||
- $ref: "pdu_v3.yaml"
|
||||
- $ref: "components/pdu_base.yaml"
|
||||
- $ref: "components/auth_events_prev_events_v4.yaml"
|
||||
- type: object
|
||||
properties:
|
||||
redacts:
|
||||
type: string
|
||||
description: For redaction events, the ID of the event being redacted.
|
||||
example: "$def_456-oldevent"
|
||||
auth_events:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Event ID.
|
||||
depth:
|
||||
type: integer
|
||||
description: |-
|
||||
Event IDs for the authorization events that would
|
||||
allow this event to be in the room.
|
||||
|
||||
Must contain less than or equal to 10 events. Note that if the relevant
|
||||
auth event selection rules are used, this restriction should never be
|
||||
encountered.
|
||||
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
|
||||
prev_events:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Event ID.
|
||||
description: |-
|
||||
Event IDs for the most recent events in the room
|
||||
that the homeserver was aware of when it made this event.
|
||||
|
||||
Must contain less than or equal to 20 events.
|
||||
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
|
||||
required:
|
||||
- auth_events
|
||||
- prev_events
|
||||
The maximum depth of the `prev_events`, plus one. Must be less than the
|
||||
maximum value for an integer (2^63 - 1). If the room's depth is already at
|
||||
the limit, the depth must be set to the limit.
|
||||
example: 12
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Copyright 2018 New Vector Ltd
|
||||
# Copyright 2025 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.
|
||||
|
|
@ -13,33 +13,24 @@
|
|||
# limitations under the License.
|
||||
type: object
|
||||
title: Persistent Data Unit
|
||||
description: A persistent data unit (event) for room versions 1 and 2.
|
||||
description: |-
|
||||
A persistent data unit (event) for room versions 4, 5, 6, 7, 8, 9 and 10.
|
||||
example:
|
||||
$ref: "../examples/pdu.json"
|
||||
$ref: "../examples/pdu_v4.json"
|
||||
allOf:
|
||||
- $ref: "unsigned_pdu.yaml"
|
||||
- $ref: "components/pdu_base.yaml"
|
||||
- $ref: "components/auth_events_prev_events_v4.yaml"
|
||||
- type: object
|
||||
properties:
|
||||
redacts:
|
||||
type: string
|
||||
description: For redaction events, the ID of the event being redacted.
|
||||
example: "$def456:matrix.org"
|
||||
hashes:
|
||||
$ref: "event_hash.yaml"
|
||||
signatures:
|
||||
type: object
|
||||
example: "$def_456-oldevent"
|
||||
# v6 enforces Canonical JSON and therefore needs a depth limit change
|
||||
depth:
|
||||
type: integer
|
||||
description: |-
|
||||
Signatures for the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events).
|
||||
example: {
|
||||
"example.com": {
|
||||
"ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent"
|
||||
}
|
||||
}
|
||||
additionalProperties:
|
||||
type: object
|
||||
title: Server Signatures
|
||||
additionalProperties:
|
||||
type: string
|
||||
required:
|
||||
- hashes
|
||||
- signatures
|
||||
The maximum depth of the `prev_events`, plus one. Must be less than the
|
||||
maximum value for an integer (2^53 - 1). If the room's depth is already at
|
||||
the limit, the depth must be set to the limit.
|
||||
example: 12
|
||||
|
|
@ -1,28 +0,0 @@
|
|||
# Copyright 2018-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.
|
||||
type: object
|
||||
title: Unsigned Persistent Data Unit
|
||||
description: An unsigned persistent data unit (event)
|
||||
example:
|
||||
$ref: "../examples/unsigned_pdu.json"
|
||||
allOf:
|
||||
- $ref: "unsigned_pdu_base.yaml"
|
||||
- type: object
|
||||
properties:
|
||||
event_id:
|
||||
type: string
|
||||
description: The event ID for the PDU.
|
||||
example: "$a4ecee13e2accdadf56c1025:example.com"
|
||||
required:
|
||||
- event_id
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
{
|
||||
"auth_events": [
|
||||
"$urlsafe_base64_encoded_eventid",
|
||||
"$a-different-event-id"
|
||||
],
|
||||
"prev_events": [
|
||||
"$urlsafe_base64_encoded_eventid",
|
||||
"$a-different-event-id"
|
||||
]
|
||||
}
|
||||
21
data/api/server-server/examples/components/pdu_base.json
Normal file
21
data/api/server-server/examples/components/pdu_base.json
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
{
|
||||
"room_id": "!UcYsUzyxTGDxLBEvLy:example.org",
|
||||
"sender": "@alice:example.com",
|
||||
"origin_server_ts": 1404838188000,
|
||||
"depth": 12,
|
||||
"type": "m.room.message",
|
||||
"content": {
|
||||
"key": "value"
|
||||
},
|
||||
"hashes": {
|
||||
"sha256": "thishashcoversallfieldsincasethisisredacted"
|
||||
},
|
||||
"signatures": {
|
||||
"example.com": {
|
||||
"ed25519:key_version": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
|
||||
}
|
||||
},
|
||||
"unsigned": {
|
||||
"age": 4612
|
||||
}
|
||||
}
|
||||
|
|
@ -1,11 +0,0 @@
|
|||
{
|
||||
"$ref": "unsigned_pdu.json",
|
||||
"hashes": {
|
||||
"sha256": "thishashcoversallfieldsincasethisisredacted"
|
||||
},
|
||||
"signatures": {
|
||||
"example.com": {
|
||||
"ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -1,25 +1,16 @@
|
|||
{
|
||||
"room_id": "!UcYsUzyxTGDxLBEvLy:example.org",
|
||||
"sender": "@alice:example.com",
|
||||
"origin_server_ts": 1404838188000,
|
||||
"depth": 12,
|
||||
"$ref": "components/pdu_base.json",
|
||||
"event_id": "$a4ecee13e2accdadf56c1025:example.com",
|
||||
"auth_events": [
|
||||
[
|
||||
"$af232176:example.org",
|
||||
{"sha256": "abase64encodedsha256hashshouldbe43byteslong"}
|
||||
]
|
||||
],
|
||||
"type": "m.room.message",
|
||||
"prev_events": [
|
||||
[
|
||||
"$af232176:example.org",
|
||||
{"sha256": "abase64encodedsha256hashshouldbe43byteslong"}
|
||||
]
|
||||
],
|
||||
"content": {
|
||||
"key": "value"
|
||||
},
|
||||
"unsigned": {
|
||||
"age": 4612
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
@ -1,19 +1,6 @@
|
|||
{
|
||||
"$ref": "unsigned_pdu_base.json",
|
||||
"hashes": {
|
||||
"sha256": "thishashcoversallfieldsincasethisisredacted"
|
||||
},
|
||||
"signatures": {
|
||||
"example.com": {
|
||||
"ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
|
||||
}
|
||||
},
|
||||
"auth_events": [
|
||||
"$urlsafe_base64_encoded_eventid",
|
||||
"$a-different-event-id"
|
||||
],
|
||||
"prev_events": [
|
||||
"$urlsafe_base64_encoded_eventid",
|
||||
"$a-different-event-id"
|
||||
"allOf": [
|
||||
{ "$ref": "components/pdu_base.json" },
|
||||
{ "$ref": "components/auth_events_prev_events_v4.json" }
|
||||
]
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,13 +1,5 @@
|
|||
{
|
||||
"$ref": "unsigned_pdu_base.json",
|
||||
"hashes": {
|
||||
"sha256": "thishashcoversallfieldsincasethisisredacted"
|
||||
},
|
||||
"signatures": {
|
||||
"example.com": {
|
||||
"ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
|
||||
}
|
||||
},
|
||||
"$ref": "components/pdu_base.json",
|
||||
"auth_events": [
|
||||
"$base64encodedeventid",
|
||||
"$adifferenteventid"
|
||||
|
|
|
|||
|
|
@ -1,12 +1,7 @@
|
|||
{
|
||||
"$ref": "pdu_v3.json",
|
||||
"auth_events": [
|
||||
"$urlsafe_base64_encoded_eventid",
|
||||
"$a-different-event-id"
|
||||
],
|
||||
"prev_events": [
|
||||
"$urlsafe_base64_encoded_eventid",
|
||||
"$a-different-event-id"
|
||||
],
|
||||
"redacts": "$some-old_event"
|
||||
"allOf": [
|
||||
{ "$ref": "components/pdu_base.json" },
|
||||
{ "$ref": "components/auth_events_prev_events_v4.json" },
|
||||
{ "redacts": "$some-old_event" }
|
||||
]
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,8 +1,5 @@
|
|||
{
|
||||
"$ref": "unsigned_pdu_base.json",
|
||||
"hashes": {
|
||||
"sha256": "thishashcoversallfieldsincasethisisredacted"
|
||||
},
|
||||
"$ref": "components/pdu_base.json",
|
||||
"signatures": {
|
||||
"example.com": {
|
||||
"ed25519:key_version": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
|
||||
|
|
|
|||
|
|
@ -1,4 +0,0 @@
|
|||
{
|
||||
"$ref": "unsigned_pdu_base.json",
|
||||
"event_id": "$a4ecee13e2accdadf56c1025:example.com"
|
||||
}
|
||||
|
|
@ -75,22 +75,6 @@ paths:
|
|||
example:
|
||||
$ref: ../../event-schemas/examples/invite_room_state.json
|
||||
type: object
|
||||
example: {
|
||||
"room_id": "!somewhere:example.org",
|
||||
"type": "m.room.member",
|
||||
"state_key": "@joe:elsewhere.com",
|
||||
"origin": "example.org",
|
||||
"origin_server_ts": 1549041175876,
|
||||
"sender": "@someone:example.org",
|
||||
"content": {
|
||||
"membership": "invite"
|
||||
},
|
||||
"signatures": {
|
||||
"example.com": {
|
||||
"ed25519:key_version": "SomeSignatureHere"
|
||||
},
|
||||
}
|
||||
}
|
||||
required: true
|
||||
responses:
|
||||
"200":
|
||||
|
|
|
|||
|
|
@ -78,25 +78,6 @@ paths:
|
|||
required:
|
||||
- room_version
|
||||
- event
|
||||
example: {
|
||||
"room_version": "2",
|
||||
"event": {
|
||||
"room_id": "!somewhere:example.org",
|
||||
"type": "m.room.member",
|
||||
"state_key": "@joe:elsewhere.com",
|
||||
"origin": "example.org",
|
||||
"origin_server_ts": 1549041175876,
|
||||
"sender": "@someone:example.org",
|
||||
"content": {
|
||||
"membership": "invite"
|
||||
},
|
||||
"signatures": {
|
||||
"example.com": {
|
||||
"ed25519:key_version": "SomeSignatureHere"
|
||||
},
|
||||
}
|
||||
}
|
||||
}
|
||||
required: true
|
||||
responses:
|
||||
"200":
|
||||
|
|
|
|||
|
|
@ -140,7 +140,6 @@ paths:
|
|||
- type
|
||||
- content
|
||||
example: {
|
||||
"room_id": "!somewhere:example.org",
|
||||
"type": "m.room.member",
|
||||
"state_key": "@someone:example.org",
|
||||
"origin": "example.org",
|
||||
|
|
|
|||
|
|
@ -270,7 +270,6 @@ paths:
|
|||
- type
|
||||
- content
|
||||
example: {
|
||||
"room_id": "!somewhere:example.org",
|
||||
"type": "m.room.member",
|
||||
"state_key": "@someone:example.org",
|
||||
"origin": "example.org",
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
{
|
||||
"$ref": "core/state_event.json",
|
||||
"state_key": "@alice:example.org",
|
||||
"sender": "@alice:example.org",
|
||||
"type": "m.room.member",
|
||||
"content": {
|
||||
"membership": "join",
|
||||
|
|
|
|||
|
|
@ -1,7 +1,14 @@
|
|||
---
|
||||
allOf:
|
||||
- $ref: core-event-schema/state_event.yaml
|
||||
description: 'A topic is a short message detailing what is currently being discussed in the room. It can also be used as a way to display extra information about the room, which may not be suitable for the room name. The room topic can also be set when creating a room using `/createRoom` with the `topic` key.'
|
||||
description: |-
|
||||
A topic is a short message detailing what is currently being discussed in the room.
|
||||
It can also be used as a way to display extra information about the room, which may not
|
||||
be suitable for the room name.
|
||||
The room topic can also be set when creating a room using `/createRoom` with the `topic` key.'
|
||||
|
||||
If the `topic` property is absent, null, or empty then the topic is unset. In other words,
|
||||
an empty `topic` property effectively resets the room to having no topic.
|
||||
properties:
|
||||
content:
|
||||
properties:
|
||||
|
|
|
|||
|
|
@ -48,8 +48,8 @@ properties:
|
|||
session_id:
|
||||
type: string
|
||||
description: |-
|
||||
Required of `code` is not `m.no_olm`. The session ID of the key
|
||||
that this event is aboutis for.
|
||||
Required if `code` is not `m.no_olm`. The session ID of the key
|
||||
that this event is about.
|
||||
sender_key:
|
||||
type: string
|
||||
description: |-
|
||||
|
|
|
|||
|
|
@ -31,9 +31,17 @@
|
|||
<h1>{{ .Title }}</h1>
|
||||
|
||||
<table class="release-info">
|
||||
{{ if ne $version "unstable" -}}
|
||||
{{ $commitLink := printf "https://github.com/matrix-org/matrix-spec/tree/%s" $version -}}
|
||||
{{ $rev := $version }}
|
||||
{{ if eq $version "unstable" -}}
|
||||
{{- /*
|
||||
Extract the git SHA from the frontmatter of the changelog, where
|
||||
it was stashed by `generate-changelog.sh`.
|
||||
*/ -}}
|
||||
{{ $rev = .Params.commit -}}
|
||||
{{ end -}}
|
||||
{{ $commitLink := printf "https://github.com/matrix-org/matrix-spec/tree/%s" $rev -}}
|
||||
<tr><th>Git commit</th><td><a href="{{ $commitLink }}">{{ $commitLink }}</a></td>
|
||||
{{ if ne $version "unstable" }}
|
||||
<tr><th>Release date</th><td>{{ .Date | time.Format ":date_long" }}</td>
|
||||
{{ end -}}
|
||||
{{ $checklist := .OutputFormats.Get "checklist" -}}
|
||||
|
|
|
|||
|
|
@ -13,10 +13,4 @@
|
|||
{{ $path := delimit (slice "event-schemas/examples" .name) "/" }}
|
||||
|
||||
{{ $example_content := partial "json-schema/resolve-refs" (dict "schema" .schema "path" $path) }}
|
||||
{{ $example_json := jsonify (dict "indent" " ") $example_content }}
|
||||
{{ $example_json = replace $example_json "\\u003c" "<" }}
|
||||
{{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
|
||||
|
||||
```json
|
||||
{{ $example_json }}
|
||||
```
|
||||
{{ partial "render-example" (dict "example" $example_content) }}
|
||||
|
|
|
|||
|
|
@ -24,6 +24,14 @@
|
|||
|
||||
{{ range $original }}
|
||||
{{ $resolved := partial "json-schema/resolve-allof" . }}
|
||||
{{ if reflect.IsSlice $resolved }}
|
||||
{{/*
|
||||
If $resolved is a slice, `append` will add the items of $resolved to
|
||||
$ret, but we want to add $resolved itself to $ret, so we always wrap
|
||||
it into another slice.
|
||||
*/}}
|
||||
{{ $resolved = slice $resolved }}
|
||||
{{ end }}
|
||||
{{ $ret = $ret | append $resolved }}
|
||||
{{ end }}
|
||||
{{ else if reflect.IsMap $original }}
|
||||
|
|
|
|||
|
|
@ -1,46 +0,0 @@
|
|||
{{/*
|
||||
|
||||
For complex objects, example content is sometimes attached to the
|
||||
object's individual properties (and subproperties...), so to get
|
||||
a complete example for the whole object we need to iterate through
|
||||
its properties (and subproperties...) and assemble them.
|
||||
|
||||
That's what this template does.
|
||||
|
||||
*/}}
|
||||
|
||||
{{ $this_object := . }}
|
||||
|
||||
{{ $example := $this_object.example }}
|
||||
|
||||
{{ if not $example }}
|
||||
|
||||
{{ if eq $this_object.type "object" }}
|
||||
{{ $example = dict }}
|
||||
|
||||
{{ range $key, $property := $this_object.properties}}
|
||||
{{ $this_property_example := partial "json-schema/resolve-example" $property }}
|
||||
{{ if $this_property_example }}
|
||||
{{ $example = merge (dict $key $this_property_example) $example }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
|
||||
{{ else if eq $this_object.type "array" }}
|
||||
|
||||
{{/* the "items" within an array can either be an object (where we have a
|
||||
list of items which match the schema), or a list (for tuple
|
||||
validation, where each item has a different schema).
|
||||
|
||||
TODO: support tuple validation here.
|
||||
*/}}
|
||||
{{ if reflect.IsMap $this_object.items }}
|
||||
{{ $items_example := partial "json-schema/resolve-example" $this_object.items }}
|
||||
{{ if $items_example }}
|
||||
{{ $example = slice $items_example }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
|
||||
{{ end }}
|
||||
|
||||
{{ return $example }}
|
||||
71
layouts/partials/json-schema/resolve-examples.html
Normal file
71
layouts/partials/json-schema/resolve-examples.html
Normal file
|
|
@ -0,0 +1,71 @@
|
|||
{{/*
|
||||
|
||||
Find examples in the given JSON schema.
|
||||
|
||||
Tries to find examples in the `examples` and `example` keys of the schema
|
||||
first.
|
||||
|
||||
If it doesn't succeed, iterates through the properties and subproperties to
|
||||
collect their examples, to merge them into a complete example for the whole
|
||||
object.
|
||||
|
||||
Parameter: the JSON schema to extract the examples from.
|
||||
|
||||
*/}}
|
||||
|
||||
{{ $this_object := . }}
|
||||
{{ $examples := slice }}
|
||||
|
||||
{{ if $this_object.examples }}
|
||||
{{/* This is an array of examples, we can just use it */}}
|
||||
{{ $examples = $this_object.examples }}
|
||||
{{ else if $this_object.example }}
|
||||
{{ $examples = slice $this_object.example }}
|
||||
{{ else }}
|
||||
{{/* Resolve the nested examples */}}
|
||||
{{ if eq $this_object.type "object" }}
|
||||
{{ $example := dict }}
|
||||
|
||||
{{ range $key, $property := $this_object.properties}}
|
||||
{{ $this_property_examples := partial "json-schema/resolve-examples" $property }}
|
||||
{{/*
|
||||
It would be too complex to handle several nested examples,
|
||||
just use the first one.
|
||||
*/}}
|
||||
{{ with index $this_property_examples 0 }}
|
||||
{{ $example = merge (dict $key .) $example }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
|
||||
{{/*
|
||||
Add the assembled example to the list if either (a) the example is
|
||||
non-empty, or (b) the object itself is meant to be empty (so an
|
||||
empty example is correct).
|
||||
*/}}
|
||||
{{ if (or $example (not $this_object.properties)) }}
|
||||
{{ $examples = slice $example }}
|
||||
{{ end }}
|
||||
|
||||
{{ else if eq $this_object.type "array" }}
|
||||
|
||||
{{/* the "items" within an array can either be an object (where we have a
|
||||
list of items which match the schema), or a list (for tuple
|
||||
validation, where each item has a different schema).
|
||||
|
||||
TODO: support tuple validation here.
|
||||
*/}}
|
||||
{{ if reflect.IsMap $this_object.items }}
|
||||
{{ $items_examples := partial "json-schema/resolve-examples" $this_object.items }}
|
||||
{{/*
|
||||
It would be too complex to handle several nested examples,
|
||||
just use the first one.
|
||||
*/}}
|
||||
{{ with index $items_examples 0 }}
|
||||
{{ $examples = slice (slice .) }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
|
||||
{{ end }}
|
||||
|
||||
{{ return $examples }}
|
||||
|
|
@ -69,6 +69,14 @@
|
|||
|
||||
{{ range $schema }}
|
||||
{{ $resolved := partial "json-schema/resolve-refs" (dict "schema" . "path" $path) }}
|
||||
{{ if reflect.IsSlice $resolved }}
|
||||
{{/*
|
||||
If $resolved is a slice, `append` will add the items of $resolved to
|
||||
$result_slice, but we want to add $resolved itself to $result_slice,
|
||||
so we wrap it into another slice.
|
||||
*/}}
|
||||
{{ $resolved = slice $resolved }}
|
||||
{{ end }}
|
||||
{{ $result_slice = $result_slice | append $resolved }}
|
||||
{{ end }}
|
||||
|
||||
|
|
|
|||
104
layouts/partials/openapi/render-media-type-objects.html
Normal file
104
layouts/partials/openapi/render-media-type-objects.html
Normal file
|
|
@ -0,0 +1,104 @@
|
|||
{{/*
|
||||
|
||||
Render a map of [Media Type Objects](https://spec.openapis.org/oas/v3.1.1#media-type-object).
|
||||
This map can be found as the `content` field of requests and responses.
|
||||
|
||||
Parameters:
|
||||
|
||||
* `content`: A map of MIME type to Media Type Object
|
||||
* `kind`: the kind of object that is rendered, either `request` or `response`.
|
||||
* `anchor_base`: a prefix to add to the HTML anchors generated for each object
|
||||
|
||||
This template renders:
|
||||
|
||||
* Object tables if the map contains an `application/json` MIME type, or a
|
||||
table with the MIME types and the corresponding description of the object.
|
||||
* The examples of the Media Type Objects.
|
||||
|
||||
*/}}
|
||||
|
||||
{{/*
|
||||
Request and response bodies can have several content types. If there is a
|
||||
JSON type, we display that; otherwise we just show the content types and
|
||||
descriptions.
|
||||
*/}}
|
||||
{{ $json_body := index .content "application/json" }}
|
||||
{{ if $json_body }}
|
||||
{{/*
|
||||
Display the JSON schemas
|
||||
*/}}
|
||||
|
||||
{{ $schema := $json_body.schema }}
|
||||
|
||||
{{/*
|
||||
All this is to work out how to express the content of the response
|
||||
in the case where it is an array.
|
||||
*/}}
|
||||
{{ if eq $schema.type "array" }}
|
||||
{{ $type_of := "" }}
|
||||
{{ if $schema.items.anyOf }}
|
||||
{{ $types := slice }}
|
||||
{{ range $schema.items.anyOf }}
|
||||
{{ if .title }}
|
||||
{{ $types = $types | append .title}}
|
||||
{{ else }}
|
||||
{{ $types = $types | append .type }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
{{ $type_of = delimit $types ", "}}
|
||||
{{ else }}
|
||||
{{ $type_of = $schema.items.title }}
|
||||
{{ end }}
|
||||
<p>Array of <code>{{ $type_of }}</code>.</p>
|
||||
{{ end }}
|
||||
|
||||
{{/*
|
||||
Render object tables for any objects referenced in the request/response.
|
||||
|
||||
This will be a no-op for request/response body types which aren't
|
||||
objects or arrays.
|
||||
*/}}
|
||||
{{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" .anchor_base) }}
|
||||
{{ range $additional_types }}
|
||||
{{ partial "openapi/render-object-table" . }}
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
{{/*
|
||||
Show the content types and description.
|
||||
*/}}
|
||||
{{ partial "openapi/render-content-type" (dict "content_types" .content) }}
|
||||
{{ end }}
|
||||
|
||||
{{/*
|
||||
Show all the examples.
|
||||
*/}}
|
||||
{{ if eq .kind "request" }}
|
||||
<h3>Request body example</h3>
|
||||
{{ end }}
|
||||
|
||||
{{ range $mime, $body := .content }}
|
||||
{{ $examples := slice }}
|
||||
|
||||
{{/*
|
||||
Find the examples to display, with the following priority:
|
||||
|
||||
1. The `examples` field
|
||||
2. The `example` field
|
||||
3. The examples in the `schema` field
|
||||
*/}}
|
||||
{{ if $body.examples }}
|
||||
{{/* This is a map of string to Example Object */}}
|
||||
{{ range $key, $example := $body.examples }}
|
||||
{{/* The example is in the `value` field of the object */}}
|
||||
{{ $examples = $examples | append (slice $example.value) }}
|
||||
{{ end }}
|
||||
{{ else if $body.example }}
|
||||
{{ $examples = slice $body.example }}
|
||||
{{ else if $body.schema }}
|
||||
{{ $examples = partial "json-schema/resolve-examples" $body.schema }}
|
||||
{{ end }}
|
||||
|
||||
{{ range $examples }}
|
||||
{{ partial "render-example" (dict "example" . "mime" $mime) }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
|
|
@ -33,65 +33,8 @@
|
|||
|
||||
{{ if $request_body }}
|
||||
<h3>Request body</h3>
|
||||
{{/*
|
||||
A request can have several content types.
|
||||
*/}}
|
||||
{{ $json_body := index $request_body.content "application/json" }}
|
||||
{{ if $json_body }}
|
||||
{{/*
|
||||
Display the JSON schemas
|
||||
*/}}
|
||||
{{ $schema := $json_body.schema }}
|
||||
|
||||
{{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor) }}
|
||||
{{ range $additional_types }}
|
||||
{{ partial "openapi/render-object-table" . }}
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
{{/*
|
||||
Show the content types and description.
|
||||
*/}}
|
||||
{{ partial "openapi/render-content-type" (dict "content_types" $request_body.content) }}
|
||||
{{ end }}
|
||||
|
||||
<h3>Request body example</h3>
|
||||
{{/*
|
||||
Show all the examples.
|
||||
*/}}
|
||||
{{ range $mime, $body := $request_body.content }}
|
||||
{{ $example := dict }}
|
||||
|
||||
{{ if $body.schema }}
|
||||
{{ $example = partial "json-schema/resolve-example" $body.schema }}
|
||||
{{ end }}
|
||||
|
||||
{{ if and (eq ($example | len) 0) $body.example }}
|
||||
{{/*
|
||||
If no example was generated from the schema, fallback to the
|
||||
main example.
|
||||
*/}}
|
||||
{{ $example = $body.example }}
|
||||
{{ end }}
|
||||
|
||||
{{ if eq $mime "application/json" }}
|
||||
{{ $example_json := jsonify (dict "indent" " ") $example }}
|
||||
{{ $example_json = replace $example_json "\\u003c" "<" }}
|
||||
{{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
|
||||
```json
|
||||
{{ $example_json }}
|
||||
```
|
||||
{{ else }}
|
||||
{{ $example = $example | safeHTML }}
|
||||
{{/*
|
||||
We need to set a language for the code otherwise the styling
|
||||
is different than other examples.
|
||||
*/}}
|
||||
```json
|
||||
{{ $example }}
|
||||
```
|
||||
{{ end }}
|
||||
|
||||
{{ end }}
|
||||
{{ partial "openapi/render-media-type-objects" (dict "content" $request_body.content "kind" "request" "anchor_base" $anchor) }}
|
||||
{{ end }}
|
||||
|
||||
{{ else }}
|
||||
|
|
|
|||
|
|
@ -59,72 +59,6 @@
|
|||
{{ partial "openapi/render-object-table" (dict "title" "Headers" "properties" $headers_dict) }}
|
||||
{{ end }}
|
||||
|
||||
{{/*
|
||||
A response can have several content types.
|
||||
*/}}
|
||||
{{ $json_body := index $response.content "application/json" }}
|
||||
{{ if $json_body }}
|
||||
{{/*
|
||||
Display the JSON schemas
|
||||
*/}}
|
||||
|
||||
{{ $schema := $json_body.schema }}
|
||||
|
||||
{{/*
|
||||
All this is to work out how to express the content of the response
|
||||
in the case where it is an array.
|
||||
*/}}
|
||||
{{ if eq $schema.type "array" }}
|
||||
{{ $type_of := "" }}
|
||||
{{ if $schema.items.anyOf }}
|
||||
{{ $types := slice }}
|
||||
{{ range $schema.items.anyOf }}
|
||||
{{ if .title }}
|
||||
{{ $types = $types | append .title}}
|
||||
{{ else }}
|
||||
{{ $types = $types | append .type }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
{{ $type_of = delimit $types ", "}}
|
||||
{{ else }}
|
||||
{{ $type_of = $schema.items.title }}
|
||||
{{ end }}
|
||||
<p>Array of <code>{{ $type_of }}</code>.</p>
|
||||
{{ end }}
|
||||
|
||||
|
||||
{{/*
|
||||
render object tables for any objects referenced in the
|
||||
response. (This will be a no-op for response types which aren't
|
||||
objects or arrays.)
|
||||
*/}}
|
||||
{{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor) }}
|
||||
{{ range $additional_types }}
|
||||
{{ partial "openapi/render-object-table" . }}
|
||||
{{ end }}
|
||||
|
||||
{{/*
|
||||
render an example. currently this is only supported for arrays and objects.
|
||||
*/}}
|
||||
{{ if or (eq $schema.type "object") (eq $schema.type "array") }}
|
||||
{{ $example := partial "json-schema/resolve-example" $schema }}
|
||||
{{ if $json_body.examples }}
|
||||
{{ $example = $json_body.examples.response.value }}
|
||||
{{ end }}
|
||||
|
||||
{{ $example_json := jsonify (dict "indent" " ") $example }}
|
||||
{{ $example_json = replace $example_json "\\u003c" "<" }}
|
||||
{{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
|
||||
|
||||
```json
|
||||
{{ $example_json }}
|
||||
```
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
{{/*
|
||||
Show the content types and description.
|
||||
*/}}
|
||||
{{ partial "openapi/render-content-type" (dict "content_types" $response.content) }}
|
||||
{{ end }}
|
||||
{{ partial "openapi/render-media-type-objects" (dict "content" $response.content "kind" "response" "anchor_base" $anchor) }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
|
|
|
|||
40
layouts/partials/render-example.html
Normal file
40
layouts/partials/render-example.html
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
{{/*
|
||||
|
||||
Renders an example to be included in HTML, with support for pretty-printing
|
||||
JSON.
|
||||
|
||||
Parameters:
|
||||
|
||||
* `example`: the example
|
||||
* `mime`: the mime type of the example. Used to pretty-print JSON and for
|
||||
syntax highlighting. If it is not provided, it is assumed to be
|
||||
`application/json`.
|
||||
|
||||
*/}}
|
||||
|
||||
{{ $example := .example }}
|
||||
|
||||
{{/*
|
||||
We need to convert the mime type to a recognized language.
|
||||
For simplicity we only support JSON, which is also the default. Other mime
|
||||
types are not highlighted.
|
||||
*/}}
|
||||
{{ $language := "json" }}
|
||||
|
||||
{{ if (and .mime (ne .mime "application/json")) }}
|
||||
{{/*
|
||||
`no-highlight` treats the value as plain text, but still styles the code
|
||||
block like the ones with proper syntax highlighting.
|
||||
*/}}
|
||||
{{ $language = "no-highlight" }}
|
||||
{{ end }}
|
||||
|
||||
{{ if eq $language "json" }}
|
||||
{{ $example = jsonify (dict "indent" " ") $example }}
|
||||
{{ $example = replace $example "\\u003c" "<" }}
|
||||
{{ $example = replace $example "\\u003e" ">" }}
|
||||
{{ end }}
|
||||
|
||||
```{{ $language }}
|
||||
{{ $example | safeHTML }}
|
||||
```
|
||||
|
|
@ -58,13 +58,14 @@
|
|||
{{ partial "openapi/render-object-table" . }}
|
||||
{{end}}
|
||||
|
||||
{{ $examples := partial "json-schema/resolve-examples" $definition }}
|
||||
{{ if $examples }}
|
||||
<h2>Examples</h2>
|
||||
|
||||
{{ $example := partial "json-schema/resolve-example" $definition }}
|
||||
|
||||
```json
|
||||
{{ jsonify (dict "indent" " ") $example }}
|
||||
```
|
||||
{{ range $examples }}
|
||||
{{ partial "render-example" (dict "example" .) }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
|
||||
</details>
|
||||
|
||||
|
|
|
|||
|
|
@ -44,8 +44,18 @@ outputs:
|
|||
- html
|
||||
- checklist
|
||||
date: $(date -Idate)
|
||||
---
|
||||
EOF
|
||||
|
||||
# Add the commit hash for the unstable versions. It is used to generate a
|
||||
# link to the commit on the repository.
|
||||
if [ "$VERSION" == "vUNSTABLE" ]; then
|
||||
echo "params:"
|
||||
echo " commit: $(git rev-parse --short HEAD)"
|
||||
fi
|
||||
|
||||
# Close the frontmatter.
|
||||
echo "---"
|
||||
|
||||
# Remove trailing whitespace (such as our intentionally blank RST headings)
|
||||
sed -e "s/[ ]*$//" rendered.md
|
||||
} > ../content/changelog/$FILENAME
|
||||
|
|
|
|||
1
static/.well-known/funding-manifest-urls
Normal file
1
static/.well-known/funding-manifest-urls
Normal file
|
|
@ -0,0 +1 @@
|
|||
https://matrix.org/funding.json
|
||||
Loading…
Reference in a new issue