Move prev_content to unsigned

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.

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:
+      this: |
+        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/openapi/render-object-table.html

@@ -82,7 +82,21 @@
  <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") -}}
+        {{ range $ver, $details := index $property "x-changedInMatrixVersion" }}
+            <br><br>
+            <strong>
+                Changed in {{ if (eq $ver "this") }}this version{{ else }}`v{{ $ver }}`{{ end }}:
+            </strong>
+            {{ $details | markdownify }}
+        {{ end }}
+    {{ end }}
+  </td>
  </tr>
 
     {{ end }}