diff --git a/changelogs/client_server/newsfragments/3524.breaking b/changelogs/client_server/newsfragments/3524.breaking new file mode 100644 index 00000000..4157ed12 --- /dev/null +++ b/changelogs/client_server/newsfragments/3524.breaking @@ -0,0 +1 @@ +The `prev_content` field is now returned inside the `unsigned` property of events, rather than at the top level, as per [MSC3442](https://github.com/matrix-org/matrix-doc/pull/3442). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index c0456571..675ac594 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1354,13 +1354,11 @@ the server-server API. #### State event fields In addition to the fields of a Room Event, State Events have the -following fields. - +following field: | Key | Type | Description | |--------------|--------------|--------------------------------------------------------------------------------------------------------------| | state_key | string | **Required.** A unique key which defines the overwriting semantics for this piece of room state. This value is often a zero-length string. The presence of this key makes this event a State Event. State keys starting with an `@` are reserved for referencing user IDs, such as room members. With the exception of a few events, state events set with a given user's ID as the state key MUST only be set by that user. | -| prev_content | EventContent | Optional. The previous `content` for this event. If there is no previous content, this key will be missing. | ### Size limits diff --git a/data/event-schemas/schema/core-event-schema/sync_state_event.yaml b/data/event-schemas/schema/core-event-schema/sync_state_event.yaml index e7a061f5..7033a5e6 100644 --- a/data/event-schemas/schema/core-event-schema/sync_state_event.yaml +++ b/data/event-schemas/schema/core-event-schema/sync_state_event.yaml @@ -19,11 +19,6 @@ allOf: description: In addition to the Room Event fields, State Events have the following additional fields. properties: - prev_content: - description: Optional. The previous `content` for this event. If there is no - previous content, this key will be missing. - title: EventContent - type: object state_key: description: A unique key which defines the overwriting semantics for this piece of room state. This value is often a zero-length string. The presence of this diff --git a/data/event-schemas/schema/core-event-schema/unsigned_prop.yaml b/data/event-schemas/schema/core-event-schema/unsigned_prop.yaml index aace29ff..61c4b08d 100644 --- a/data/event-schemas/schema/core-event-schema/unsigned_prop.yaml +++ b/data/event-schemas/schema/core-event-schema/unsigned_prop.yaml @@ -32,3 +32,17 @@ properties: `PUT /_matrix/client/r0/rooms/{roomId}/send/{eventType}/{txnId}`, if the client being given the event is the same one which sent it. type: string + prev_content: + description: | + The previous `content` for this event. This field is generated + by the local homeserver, and is only returned if the event is a state event, + and the client has permission to see the previous content. + x-changedInMatrixVersion: + 1.2: | + Previously, this field was specified at the top level of returned + events rather than in `unsigned` (with the exception of the [`GET + .../notifications`](/client-server-api/#get_matrixclientv3notifications) + endpoint), though in practice no known server implementations honoured + this. + title: EventContent + type: object diff --git a/layouts/partials/changed-in.html b/layouts/partials/changed-in.html new file mode 100644 index 00000000..8a815904 --- /dev/null +++ b/layouts/partials/changed-in.html @@ -0,0 +1,14 @@ +{{/* + Renders the "Changed in [version]:" blocks for x-changedInMatrixVersion + annotations for openapi parameters + + Takes a single 'changes_dict' parameter, which should be a map of + version -> details pairs. +*/ -}} +{{ range $ver, $details := .changes_dict -}} +

+ + Changed in v{{ $ver }}: + + {{ $details | markdownify }} +{{ end }} diff --git a/layouts/partials/events/render-event.html b/layouts/partials/events/render-event.html index 4d759646..66e15db7 100644 --- a/layouts/partials/events/render-event.html +++ b/layouts/partials/events/render-event.html @@ -28,6 +28,9 @@ {{ if (index $event_data "x-addedInMatrixVersion") }} {{ partial "added-in" (dict "v" (index $event_data "x-addedInMatrixVersion")) }} {{ end }} +{{ if (index $event_data "x-changedInMatrixVersion") }} + {{ partial "changed-in" (dict "changes_dict" (index $event_data "x-changedInMatrixVersion")) }} +{{ end -}} {{ $event_data.description | markdownify }} diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html index 63a35391..e132af30 100644 --- a/layouts/partials/openapi/render-object-table.html +++ b/layouts/partials/openapi/render-object-table.html @@ -82,7 +82,13 @@ {{ $property_name }} {{ $type }} - {{ if $required }}Required: {{end}}{{ $property.description | markdownify }}{{ if eq $type "enum"}}

One of: {{ $property.enum }}.

{{ end }}{{ if (index $property "x-addedInMatrixVersion") }}{{ partial "added-in" (dict "v" (index $property "x-addedInMatrixVersion")) }}{{ end }} + + {{ if $required }}Required: {{end -}} + {{ $property.description | markdownify -}} + {{ if eq $type "enum"}}

One of: {{ $property.enum }}.

{{ end -}} + {{ if (index $property "x-addedInMatrixVersion") }}{{ partial "added-in" (dict "v" (index $property "x-addedInMatrixVersion")) }}{{ end -}} + {{ if (index $property "x-changedInMatrixVersion") }}{{ partial "changed-in" (dict "changes_dict" (index $property "x-changedInMatrixVersion")) }}{{ end -}} + {{ end }} diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html index 5b2dd533..6d516d06 100644 --- a/layouts/partials/openapi/render-operation.html +++ b/layouts/partials/openapi/render-operation.html @@ -42,6 +42,9 @@ {{ if (index $operation_data "x-addedInMatrixVersion") }} {{ partial "added-in" (dict "v" (index $operation_data "x-addedInMatrixVersion")) }} {{ end }} +{{ if (index $operation_data "x-changedInMatrixVersion") }} + {{ partial "changed-in" (dict "changes_dict" (index $operation_data "x-changedInMatrixVersion")) }} +{{ end -}}

{{ $operation_data.description | markdownify }}

diff --git a/openapi_extensions.md b/openapi_extensions.md index ea3380a3..6905d663 100644 --- a/openapi_extensions.md +++ b/openapi_extensions.md @@ -68,3 +68,8 @@ ranges (`2xx` = `200` to `299`) is valid for the schema. This property is added throughout the OpenAPI schemas to denote which version of the Matrix specification added the associated object (endpoint, parameter, property, etc). + +## Custom `x-changedInMatrixVersion` key + +A variation of the above: indicates changes to the associated parameter in +particular Matrix specification versions.