Move `prev_content` to unsigned (#3524)

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).

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
 

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

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

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 -}}
+    <br><br>
+    <strong>
+      Changed in <code>v{{ $ver }}</code>:
+    </strong>
+    {{ $details | markdownify }}
+{{ end }}

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 }}
 

layouts/partials/openapi/render-object-table.html

@@ -82,7 +82,13 @@
  <tr>
   <td><code>{{ $property_name }}</code></td>
   <td><code>{{ $type }}</code></td>
-  <td>{{ if $required }}<strong>Required: </strong>{{end}}{{ $property.description | markdownify }}{{ if eq $type "enum"}}<p>One of: <code>{{ $property.enum }}</code>.</p>{{ end }}{{ if (index $property "x-addedInMatrixVersion") }}{{ partial "added-in" (dict "v" (index $property "x-addedInMatrixVersion")) }}{{ end }}</td>
+  <td>
+    {{ if $required }}<strong>Required: </strong>{{end -}}
+    {{ $property.description | markdownify -}}
+    {{ if eq $type "enum"}}<p>One of: <code>{{ $property.enum }}</code>.</p>{{ 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 -}}
+  </td>
  </tr>
 
     {{ end }}

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 -}}
 
 <p>{{ $operation_data.description | markdownify }}</p>
 

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.