From 7f200c53e8f159f630f4b8ba4525875a5bb2fd5f Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Thu, 2 Dec 2021 17:22:58 +0000
Subject: [PATCH] Move `prev_content` to unsigned (#3524)
---
.../client_server/newsfragments/3524.breaking | 1 +
content/client-server-api/_index.md | 4 +---
.../schema/core-event-schema/sync_state_event.yaml | 5 -----
.../schema/core-event-schema/unsigned_prop.yaml | 14 ++++++++++++++
layouts/partials/changed-in.html | 14 ++++++++++++++
layouts/partials/events/render-event.html | 3 +++
layouts/partials/openapi/render-object-table.html | 8 +++++++-
layouts/partials/openapi/render-operation.html | 3 +++
openapi_extensions.md | 5 +++++
9 files changed, 48 insertions(+), 9 deletions(-)
create mode 100644 changelogs/client_server/newsfragments/3524.breaking
create mode 100644 layouts/partials/changed-in.html
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.