* 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
In #1042 I incorrectly wrote that the conflicted state set is a set of
pairs (K, V). We later take the union of the conflicted state set and
the auth difference. The latter is a set of events (V) only.
Fix this by making the conflicted state set a set of events rather than
a set of pairs. That is, the conflicted state set is a a `Set[Event]`
instead of a `Set[((type, state key), event)]`.
* 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.
* clarify federation Authorization header an add destination property
* add changelogs
* some clarifications
* more clarifications, fixes
* use HTML in the added-in/changed-in shortcodes
* Apply suggestions from code review
Co-authored-by: Travis Ralston <travpc@gmail.com>
* Italicise primes and brackets in state res desc
I don't like it but it seems to make things look decent in Firefox.
This is probably good enough---we're not Knuth, after all.
Additionally I have avoided the use of `*E*'s` as in "E's prev_events"
since the apostrophe looks poor here.
Resolves#774.
An alternative to #1040.
* Changelog
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
* Fix m.login.appservice -> m.login.application_service
Implementations seem to agree with the proposal, so I'd suggest we fix the typo in the spec. I don't *think* this needs a MSC as the original proposal was fine, and this was just a copy error.
* Create 3711.clarification
* Update 3711.clarification
* Update changelogs/3711.clarification
Co-authored-by: Travis Ralston <travisr@matrix.org>
Co-authored-by: Travis Ralston <travisr@matrix.org>
* Fix knock->leave transition in auth rules
This was an oversight from knocking being added.
For safety, this has been verified as at least intended by Synapse to work:
f5e2cde3f5/synapse/event_auth.py (L390-L391)
* changelog
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 documentation style & fix room version heading order
Also add a missing signing key section to v6.
This additionally contains various edits to the fragments to have them make a little bit more sense in context.
Finally, this updates various aspects of the documentation style which haven't previously been considered - they're added here considering we're in the area.
* changelog
* enhanced changelogs
* Minor wording adjustments
* Apply suggestions from code review
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>
* 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>
* Copy spec PR near-verbatim from past PR
With light review being addressed.
https://github.com/matrix-org/matrix-doc/pull/3168
* Alter for modern day
* Add changelog
* specify that we're using the grammar
* 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 a bunch of fields from the `unsigned` property of PDUs. These things
shouldn't be passed over the Federation API, and they *really* shouldn't be
trusted if they are sent by another server.
* `replaces_state` *is* returned by Synapse, but probably shouldn't
be.
* `redacted_because`, `prev_sender` and `prev_content` are not sent by Synapse.
Split the text about event IDs and event formats into separate sections. This
is largely to make it easier to link to, but I think the resulting text makes
more sense too.
* 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>
* Remove extra pyprojects and update changelog docs
* Add script for rendering the changelog
* Add docs for how to release the spec
* Move legacy changelogs out of the way
* 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>
This tweaks the DAG to be simpler, with two linear event chains E4 -> E3
-> E2 -> E1 and E6 -> E5 -> E2 -> E1. The extremities of the DAG are now
the first and only point in the DAG where multiple event parents occur.
Since the point of the diagram is to demonstrate this very situation,
it's better didactically if there is only one such situation in the
diagram.
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
Apparently, in response to a /_matrix/federation/v1/user/devices/{userId} request, Synapse actually returns a key called "self_signing_key" instead of "self_signing_keys".
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
Part of MSC2140
Convert status codes to strings if there is a string status code. Fixes a build error when we mix 4xx and 403 in the same definition. We also have to correct stringified numbers to pass the build.
The server-server specification describes a "reference hash" of an event
and how to calculate it, but is otherwise not mentioned anywhere else in
the document. This change adds a sentence to explain that they are used
for event identifiers in later room versions, which are described in
other documents.
Signed-off-by: Jimmy Cuadra <jimmy@jimmycuadra.com>
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>
Fixes https://github.com/matrix-org/matrix-doc/issues/1166
Fixes https://github.com/matrix-org/matrix-doc/issues/1527
Fixes https://github.com/matrix-org/matrix-doc/issues/1827
Note: In order to fix the "state events have the following fields: [no words]" bug (1827) we need to resolve references on common event types. When doing this we ultimately end up with more fields than may be required to explain the section, however this commit alters the section descriptions to just say "these fields" instead of "these additional fields".
This is also preferable over trying to get the inheritance reversed in the common event types, as the `/sync` endpoint has a high amount of reliance on partial events definitions.
Fixes https://github.com/matrix-org/matrix-doc/issues/2066
The expectation everywhere is that the `sender` is required. `/initialSync` references StrippedState through a `m.room.member` event reference, and does not need editing.
Fixes https://github.com/matrix-org/matrix-doc/issues/1987
Note: Synapse currently does not care, however the spirit of the text in the spec implies that completed == done forever, so we're just reinforcing it here.
Alexey Rusakov