* Arrange a few titles
Before this change, PublicRoomsChunk in the spec text could be found in
two places (actually three but the third one is identical to the first
one), defining two (_mostly_ identical but) different schemas.
Ctrl-F'ing through the spec may confuse you with the "wrong" definition.
This commit gives distinct schemas distinct names; aside from
PublicRoomChunk, the same story happens with the derivative of
stripped_state.yaml used in space_hierarchy.yaml (it's not exactly
StrippedStateEvent either).
As for the removal of `PublicRoomsChunks` (plural) - this title is
unnecessary because the tooling would place rather self-explanatory
`[PublicRoomsChunk]` without it, whereas the plural title ends up with
no definition in the spec text.
* Add changelog
* keys.yml: fix one_time_keys object contents
The alternatives previously listed under two additionalProperties levels
are actually one _more_ level deeper; we still can't define them in
a formal way before moving to OpenAPI 3 but at least let's be honest
and say there's always a dict where there's always a dict. Also,
since the same data structure is used in three places now, at least
give it a name, and document the actual definition (once) separately
(not using it now because it's OpenAPI 3).
* Changelog
* openapi_extensions.md: fix typos and leftovers
dump-swagger had to substitute things in the past - these days it
just merges definitions.
* Changelog
* Commit to show changes to rich replies section
* Move rich replies to a module
* Add remainder of MSC2674
* Pivot away from MSC3440: Threads
* Add changelog entries so far
* Make a note for why we have aggregations/relations if nothing uses it
* Outright remove threads references
Apparently this breaks the table of contents
* Define MSC2675
* Define MSC3666
* Add note for rich replies?
* Update content/client-server-api/_index.md
Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com>
* Clarify how ignoring works for aggregations.
* Try to clarify redactions a bit
* Clarify using parent/child language
* Add missing bits of MSC2675
* Add changelog for aggregations
* Appease the linters
* Update data/api/client-server/relations.yaml
Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com>
* Apply suggestions from code review
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
* Apply suggestions from code review
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
* Try to clarify the return of /relations
* Fix required attribute
* Fix wording round 1
* Try to fix pagination
* Copy/paste the endpoint to make Open API happy
* Fix code block examples for rich replies
* Apply suggestions from code review
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
* Apply suggestions on all 3 endpoints
* Fix description of relationships API
* Fix warning about server-side aggregation/bundling
Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
* Clarification on historical power level handling
* Revert "Clarification on historical power level handling"
This reverts commit f443b3d5a9.
* Clean up
* Let us try this again not using VS Code
* Markdown is full of mysteries
* Move stringy power levels to room versions
* Describe range
* Fix minor issues with previous room version stuff
* Copy/paste v9 into v10
* Describe deprecated formatting
* Paste unmodified auth rules from v8 into v10
* Move 9.1 to 9.3, add 9.1 and 9.2 for integer enforcement
* Add knock_restricted to v10 auth
* Misc cleanup and clarification for fragments
* Describe `knock_restricted` client changes
* Changelogs
* spelling
* Apply suggestions from code review
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
* Apply code review suggestions manually
* Fix v9 redactions
* Fix auth rules clarity issues
* Apply suggestions from code review
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
* Remove false integer requirements
Co-authored-by: Neil Alexander <neilalexander@users.noreply.github.com>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
* room_type is not a required parameter in practice
In practice servers seem to mirror what the room create event does and
leave out the room_type when unset.
Signed-off-by: Nicolas Werner <n.werner@famedly.com>
* Add changelog
Signed-off-by: Nicolas Werner <n.werner@famedly.com>
* Also make room_type and allowed_room_ids optional in the openapi
They are optional according to the text, but the openapi marks them as
required instead.
Signed-off-by: Nicolas Werner <n.werner@famedly.com>
* Fix copy and paste error of newsfragment
Signed-off-by: Nicolas Werner <n.werner@famedly.com>
* fix: spaces hierarchy paramater types
- changed `limit` parameter type to integer
- changed `query` parameter type to integer
A floating number does not make any sense here. Also, at least Synapse
does not allow floating point numbers in here.
Signed-off-by: TheOneWithTheBraid <the-one@with-the-braid.cf>
* Update changelogs/client_server/newsfragments/1097.clarification
Co-authored-by: Travis Ralston <travpc@gmail.com>
* Reference MSCs where MSCs were not being referenced.
* Alter language to appear consistent and from a single voice.
* Bundle and group various changes together (will affect the final changelog - the rendered one still doesn't bundle appropriately).
* Move entries to the spec area they are intended to be in.
The spec had an erroneous `room_id` field in a m.typing EDU entry of /sync, `m.read` receipts in `/sync`, and `m.fully_read` room account data objects in the spec. None of these are necessary nor used in practice.
Checking part of the ecosystem for whether clients look for, or homeservers include, these room_id fields, I found that:
Element does not require them, nor does Synapse include them.
Ruma does not include them.
Dendrite does not include them.
nheko/mtxclient does not look for them.
This change removes room_id from the example and OpenAPI schema in each case mentioned above. It only affects the Client-Server spec - the Server-Server spec text remains unchanged.
The field was initially introduced in 0f28f83.
Fixes#3641
The spec says the name field in m.room.name events must not exceed 255 bytes but no servers actually enforce this over the C-S API. Clients should probably already be truncating room names to an appropriate length for their user interface.
Signed-off-by: Aaron Raimist <aaron@raim.ist>
* Fix membership state table and diagram
There were 2 missing cases which are legal:
* `invite->knock` (a fairly silly thing to do, but legal under the auth rules)
* `external->leave (via /kick)` (another somewhat silly thing to do, but no different than `external->ban (via /ban)`)
The state table considered the first as illegal, which is untrue.
* Changelog
* Make the graph prettier
* Update changelogs/client_server/newsfragments/3730.clarification
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
As per MSC3567, the `from` parameter is now optional for the `/messages` endpoint to allow fetching first or latest room content without having to rely on `/sync`
https://github.com/matrix-org/matrix-doc/pull/3567
Fixes#3305Fixes#3380
The idea here is to better distinguish between a 'raw' event (as we send over the wire), and the
'serialised' format, as sent in responses to the C-S api and in `PUT /_matrix/app/v1/transactions/{txnId}`.
It's made more complicated by the fact that there are _two_ serialisation formats, one used by `/sync`
and `/notifications`, and one by everything else (the difference being whether `room_id` is included).
In an ideal world, we wouldn't repeat `SerialisedEvent` every time it's used, and instead just link to the
first reference, but that's a job for another day.
Another job for another day is to get rid of things like `sync_state_event.yaml` (which is now used
only in one place, so should be inlined.)
* Update several spots where C-S API was still using r0 APIs
Signed-off-by: Aaron Raimist <aaron@raim.ist>
* Add changelog
Signed-off-by: Aaron Raimist <aaron@raim.ist>
Fixes#2237.
Corrects the response schemas for:
```
PUT /user/{user_id}/account_data/{account_dataType}
PUT /user/{user_id}/rooms/{roomId}/account_data/{type}
PUT /directory/list/room/{roomId}
PUT /sendToDevice/{eventType}/{txnId}
POST /account/3pid
POST /account/3pid/add
POST /account/3pid/bind
```
* Room versions 8 and 9: Restricted rooms
MSCs:
* https://github.com/matrix-org/matrix-doc/pull/3083
* https://github.com/matrix-org/matrix-doc/pull/3289
* https://github.com/matrix-org/matrix-doc/pull/3375
* Changelogs
* Capitalization
Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com>
* Remove verbiage for spaces because they don't exist
* Iterations on text
* Another clarification
* Make error code descriptions consistent
* Apply suggestions from code review
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
* Incorporate from merge
* Misc language update per review
* Update accuracy before splitting auth rules
* fix wtf moment
* Fix up v8 and v9 to match "fully specify room versions"
* Scope auth events selection to room version
* Apply consistency
* Add changelogs
* Review part 1
* Apply suggestions from code review
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
* Split out redaction sections
* Clarify general case of join conditions
Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
* First iteration of specifying Spaces
MSCs:
* https://github.com/matrix-org/matrix-doc/pull/3288
* https://github.com/matrix-org/matrix-doc/pull/2946
* https://github.com/matrix-org/matrix-doc/pull/1772
Note that this makes modifications to the underlying MSCs as well. These are intended to be minor edits to aid clarity/accuracy of the MSCs, as per the proposal process. Functionally, clients and servers might need to change their behaviour slightly as is expected of implementing this stuff early. Synapse has these changes (alongside backwards compatibility) here: https://github.com/matrix-org/synapse/pull/11667
* add changelogs
* Accuracy per review
* Apply suggestions from code review
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
* fully prefix new endpoints
* Fully prefix endpoint in 3616 too
* Fix ordering example
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
* Add registration token UIA type
MSC: https://github.com/matrix-org/matrix-doc/pull/3231
**Note**: This introduces the endpoint as v1 rather than r0 given the global versioning changes landed between the acceptance of the MSC and now.
* Fix swagger
* Changelogs
* Update data/api/client-server/registration_tokens.yaml
Co-authored-by: Hubert Chathi <hubert@uhoreg.ca>
Co-authored-by: Hubert Chathi <hubert@uhoreg.ca>
* Add HTTP 403 to possible profile responses
Some servers may not allow profile lookup over federation, and thus
respond to GET /_matrix/client/v3/profile/{userId} with an HTTP 403.
For example, Synapse can be configured to behave in this way by setting:
allow_profile_lookup_over_federation=false
Thus, this behavior already exists in the wild, and may cause issues for
clients such as https://github.com/vector-im/element-web/issues/17269.
Synapse could alter its behavior and return an HTTP 404 in these cases,
but amending the Spec seems preferable to align with extant behavior.
Further, allowing HTTP 403 gives clients more specific information as to
why a request has failed, enabling more precise error handling.
Signed-off-by: Dan Callahan <danc@element.io>
* Update changelogs/client_server/newsfragments/3530.clarification
Co-authored-by: Travis Ralston <travpc@gmail.com>
* Annotate misc data about error
Co-authored-by: Travis Ralston <travpc@gmail.com>
Co-authored-by: Travis Ralston <travisr@matrix.org>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Co-authored-by: Hubert Chathi <hubertc@matrix.org>
Co-authored-by: Travis Ralston <travisr@matrix.org>
Fixes#3465. The change adds a line explicitly warning developers that the base_url of client well_known may or may not include a trailing slash and to be prepared to handle both cases.
* Clarify that E0 and E1 are not returned
* Clarify that ASCII art diagram 2 refers to diagram 1
* Correct third ASCII art diagram
To match the spacing in. Borked in the move to new docs format.
55aed1d296/specification/client_server_api.rst (L1610-L1615)
* Make ASCII art 3 follow from ASCII art 2
* Explain how to fill the gap
* Create 3543.clarification
* Update content/client-server-api/_index.md
Co-authored-by: Travis Ralston <travisr@matrix.org>
* Remove entries which don't affect the rendered spec (sorry people using the swagger schemas - we'll have to figure out a changelog for you). See https://github.com/matrix-org/matrix-doc/issues/3475
* Note that a breaking change is removed by this commit: key backup was introduced in this release cycle, so is not breaking.
* Use uniform references to MSCs ("as per MSC0000").
* General rewording to be consistent with the overall voice of the changelog.
* Condensing of entries where needed to make them fit in the changelog.
* Rewording to collapse entries into fewer lines.
* Spell "deprecation" correctly in file extension.
This fixes the behaviour to match what synapse implements in practice.
If you use threepidCreds, you will just get an error about a missing
threepid_creds field. Synapse also treats this as an object. All clients
also seem to send threepid_creds, if they work on Synapse. Since
matrix.org requires an email currently for registration, most clients
that implement registration, will hit this issue.
a0f48ee89d/synapse/handlers/ui_auth/checkers.py (L145)fixes#3156fixes#2189
Signed-off-by: Nicolas Werner <nicolas.werner@hotmail.de>
* Clarify how redacted_because actually works for events
* changelog
* mention federation
* Fix wording
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
The Pagination section in the C-S API was, basically, full of rubbish. I think that anything of any value it contained was repeated either directly on the API definitions or in the text specific to syncing at https://spec.matrix.org/unstable/client-server-api/#syncing.
The conventions I've added to the Appendices are based on the discussions in #1898. They are there because I don't want to have to go through it all again next time we add a paginated API.
Fixes: #1898Fixes: #2268
The regex of allowed characters for a `client_secret` parameter is `[0-9a-zA-Z.=_-]`.
This PR updates the `client_secret` spec examples, which currently include an invalid character (an apostrophe).
* add a base file
* Fix directory name
* Added translation using Weblate (English)
* Translated using Weblate (English)
Currently translated at 1.6% (1 of 64 strings)
Translation: matrix-doc/SAS Emoji v1
Translate-URL: https://translate.riot.im/projects/matrix-doc/sas-emoji-v1/en_EN/
* add english files
* delete english files
* Added translation using Weblate (English)
* Added translation using Weblate (English)
* Do manual translations
* Deleted translation using Weblate (English)
* Deleted translation using Weblate (English)
* Add a script to update the definitions with the translations
* update i18n
* Add a note to the spec about translations
* changelog
* Ensure translations end with json
Currently the *m.key.verification.start* event appears twice with the
exact same title, in the "Key verification framework" section and the
"Short Authentication (SAS) verification" section. It's not immediately
clear that the first occurrence describes the format of the event in
general terms and that the second occurrence describes the fields when
the *m.sas.v1* verification method is being used. This is a similar
relationship to the *m.room.message* event and its various *msgtype*
variants.
This commit does three things:
* It tweaks the generation of the documentation to change the title
of the second occurrence of *m.key.verification.start* to
distinguish it from the first.
* It updates the language in the description of the two versions of the
event to better describe the relationship between the two.
* It adds the optional `next_method` field to the schema of the
*m.sas.v1* variant, as specified in the general form of
*m.key.verification.start*.
Signed-off-by: Jimmy Cuadra <jimmy@jimmycuadra.com>
m.room.message msgtypes.
Now that content referenced by the *m.audio*, *m.file*, *m.image*, and
*m.video* message types can be encrypted, the `url` field is required
*only* if the content is unencrypted. The "required" designation in the
event schemas (which prefixes the field description with "Required" in
bold in the generated HTML) is used to indicate fields which must always
be present, and this is no longer the case.
Signed-off-by: Jimmy Cuadra <jimmy@jimmycuadra.com>
Alexey Rusakov