Move common VoIP fields into a call event type.

content/client-server-api/modules/voip_events.md

@@ -122,6 +122,12 @@ or not there have been any changes to the Matrix spec.
 
 #### Events
 
+##### Common Fields
+
+{{% event-fields event_type="call_event" %}}
+
+##### Events
+
 {{% event-group group_name="m.call" %}}
 
 #### Client behaviour

data/event-schemas/schema/core-event-schema/call_event.yaml

@@ -0,0 +1,26 @@
+allOf:
+- "$ref": room_event.yaml
+  description: "All call events share a set of common fields: those of room events
+    and some additional VoIP specific fields."
+properties:
+  call_id:
+    type: string
+    description: The ID of the call this event relates to.
+  version:
+    type: string
+    description: The version of the VoIP specification this message adheres to.
+      This specification is version 1. This field is a string such that experimental
+      implementations can use non-integer versions. This field was an integer
+      in the previous spec version and implementations must accept an integer
+      0.
+  party_id:
+    type: string
+    description: 'This identifies the party that sent this event. A client may
+      choose to re-use the device ID from end-to-end cryptography for the value
+      of this field. '
+required:
+- call_id
+- version
+- party_id
+title: CallEvent
+type: object

data/event-schemas/schema/m.call.answer.yaml

@@ -2,16 +2,12 @@
     "type": "object",
     "description": "This event is sent by the callee when they wish to answer the call.",
     "allOf": [{
-        "$ref": "core-event-schema/room_event.yaml"
+        "$ref": "core-event-schema/call_event.yaml"
     }],
     "properties": {
         "content": {
             "type": "object",
             "properties": {
-                "call_id": {
-                    "type": "string",
-                    "description": "The ID of the call this event relates to."
-                },
                 "answer": {
                     "type": "object",
                     "title": "Answer",
@@ -28,17 +24,9 @@
                         }
                     },
                     "required": ["type", "sdp"]
-                },
-                "version": {
-                    "type": "string",
-                    "description": "The version of the VoIP specification this message adheres to. This specification is version 1. This field is a string such that experimental implementations can use non-integer versions. This field was an integer in the previous spec version and implementations must accept an integer 0"
-                },
-                "party_id": {
-                    "type": "string",
-                    "description": "This identifies the party that sent this event. A client may choose to re-use the device ID from end-to-end cryptography for the value of this field. "
                 }
             },
-            "required": ["call_id", "answer", "version", "party_id"]
+            "required": ["answer"]
         },
         "type": {
             "type": "string",

data/event-schemas/schema/m.call.candidates.yaml

@@ -2,16 +2,12 @@
     "type": "object",
     "description": "This event is sent by callers after sending an invite and by the callee after answering. Its purpose is to give the other party additional ICE candidates to try using to communicate.",
     "allOf": [{
-        "$ref": "core-event-schema/room_event.yaml"
+        "$ref": "core-event-schema/call_event.yaml"
     }],
     "properties": {
         "content": {
             "type": "object",
             "properties": {
-                "call_id": {
-                    "type": "string",
-                    "description": "The ID of the call this event relates to."
-                },
                 "candidates": {
                     "type": "array",
                     "description": "Array of objects describing the candidates.",
@@ -34,17 +30,9 @@
                         },
                         "required": ["candidate", "sdpMLineIndex", "sdpMid"]
                     }
-                },
-                "party_id": {
-                    "type": "string",
-                    "description": "This identifies the party that sent this event. A client may choose to re-use the device ID from end-to-end cryptography for the value of this field. "
-                },
-                "version": {
-                    "type": "string",
-                    "description": "The version of the VoIP specification this message adheres to. This specification is version 1. This field is a string such that experimental implementations can use non-integer versions. This field was an integer in the previous spec version and implementations must accept an integer 0."
                 }
             },
-            "required": ["call_id", "candidates", "version", "party_id"]
+            "required": ["candidates"]
         },
         "type": {
             "type": "string",

data/event-schemas/schema/m.call.hangup.yaml

@@ -22,26 +22,11 @@ description: |
    * `unknown_error`: Some other failure occurred that meant the client was unable to continue the call
       rather than the user choosing to end it.
 allOf:
-- "$ref": core-event-schema/room_event.yaml
+- "$ref": core-event-schema/call_event.yaml
 properties:
   content:
     type: object
     properties:
-      call_id:
-        type: string
-        description: The ID of the call this event relates to.
-      version:
-        type: string
-        description: The version of the VoIP specification this message adheres to.
-          This specification is version 1. This field is a string such that experimental
-          implementations can use non-integer versions. This field was an integer
-          in the previous spec version and implementations must accept an integer
-          0.
-      party_id:
-        type: string
-        description: This identifies the party that sent this event. A client may
-          choose to re-use the device ID from end-to-end cryptography for the value
-          of this field.
       reason:
         type: string
         description: Reason for the hangup. Note that this was optional in
@@ -56,9 +41,6 @@ properties:
         - user_busy
         - unknown_error
     required:
-    - call_id
-    - version
-    - party_id
     - reason
   type:
     type: string

data/event-schemas/schema/m.call.invite.yaml

@@ -2,16 +2,12 @@
     "type": "object",
     "description": "This event is sent by the caller when they wish to establish a call.",
     "allOf": [{
-        "$ref": "core-event-schema/room_event.yaml"
+        "$ref": "core-event-schema/call_event.yaml"
     }],
     "properties": {
         "content": {
             "type": "object",
             "properties": {
-                "call_id": {
-                    "type": "string",
-                    "description": "A unique identifier for the call."
-                },
                 "offer": {
                     "type": "object",
                     "title": "Offer",
@@ -29,14 +25,6 @@
                     },
                     "required": ["type", "sdp"]
                 },
-                "version": {
-                    "type": "string",
-                    "description": "The version of the VoIP specification this message adheres to. This specification is version 1. This field is a string such that experimental implementations can use non-integer versions. This field was an integer in the previous spec version and implementations must accept an integer 0."
-                },
-                "party_id": {
-                    "type": "string",
-                    "description": "This identifies the party that sent this event. A client may choose to re-use the device ID from end-to-end cryptography for the value of this field. "
-                },
                 "lifetime": {
                     "type": "integer",
                     "description": "The time in milliseconds that the invite is valid for. Once the invite age exceeds this value, clients should discard it. They should also no longer show the call as awaiting an answer in the UI."
@@ -46,7 +34,7 @@
                     "description": "The ID of the user being called. If omitted, any user in the room can answer.",
                 }
             },
-            "required": ["call_id", "offer", "version", "lifetime", "party_id"]
+            "required": ["offer", "lifetime"]
         },
         "type": {
             "type": "string",

data/event-schemas/schema/m.call.negotiate.yaml

@@ -34,26 +34,11 @@ description: |
   attempt to validate the `type` field, but simply pass the object into the
   WebRTC API.
 allOf:
-- "$ref": core-event-schema/room_event.yaml
+- "$ref": core-event-schema/call_event.yaml
 properties:
   content:
     type: object
     properties:
-      call_id:
-        type: string
-        description: The ID of the call this event relates to.
-      version:
-        type: string
-        description: The version of the VoIP specification this message adheres to.
-          This specification is version 1. This field is a string such that experimental
-          implementations can use non-integer versions. This field was an integer
-          in the previous spec version and implementations must accept an integer
-          0.
-      party_id:
-        type: string
-        description: This identifies the party that sent this event. A client may
-          choose to re-use the device ID from end-to-end cryptography for the value
-          of this field.
       offer:
         type: object
         title: Offer
@@ -77,9 +62,6 @@ properties:
           They should also no longer show the call as awaiting an answer in the
           UI.
     required:
-    - call_id
-    - version
-    - party_id
     - offer
     - lifetime
   type:

data/event-schemas/schema/m.call.reject.yaml

@@ -13,26 +13,11 @@ description: |
 
   The meanings of the `reason` codes are the same as in [`m.call.hangup`](#mcallhangup).
 allOf:
-- "$ref": core-event-schema/room_event.yaml
+- "$ref": core-event-schema/call_event.yaml
 properties:
   content:
     type: object
     properties:
-      call_id:
-        type: string
-        description: The ID of the call this event relates to.
-      version:
-        type: string
-        description: The version of the VoIP specification this message adheres to.
-          This specification is version 1. This field is a string such that experimental
-          implementations can use non-integer versions. This field was an integer
-          in the previous spec version and implementations must accept an integer
-          0.
-      party_id:
-        type: string
-        description: 'This identifies the party that sent this event. A client may
-          choose to re-use the device ID from end-to-end cryptography for the value
-          of this field. '
       reason:
         type: string
         description: Reason for the hangup. Note that this was optional in
@@ -47,9 +32,7 @@ properties:
         - user_busy
         - unknown_error
     required:
-    - call_id
-    - version
-    - party_id
+    - reason
   type:
     type: string
     enum:

data/event-schemas/schema/m.call.select_answer.yaml

@@ -2,30 +2,18 @@
     "type": "object",
     "description": "This event is sent by the caller's client once it has decided which other client to talk to, by selecting one of multiple possible incoming `m.call.answer` events. Its `selected_party_id` field indicates the answer it's chosen. The `call_id` and `party_id` of the caller is also included. If the callee's client sees a `select_answer` for an answer with party ID other than the one it sent, it ends the call and informs the user the call was answered elsewhere. It does not send any events. Media can start flowing before this event is seen or even sent.  Clients that implement previous versions of this specification will ignore this event and behave as they did before.",
     "allOf": [{
-        "$ref": "core-event-schema/room_event.yaml"
+        "$ref": "core-event-schema/call_event.yaml"
     }],
     "properties": {
         "content": {
             "type": "object",
             "properties": {
-                "call_id": {
-                    "type": "string",
-                    "description": "The ID of the call this event relates to."
-                },
-                "version": {
-                    "type": "string",
-                    "description": "The version of the VoIP specification this message adheres to. This specification is version 1. This field is a string such that experimental implementations can use non-integer versions. This field was an integer in the previous spec version and implementations must accept an integer 0."
-                },
-                "party_id": {
-                    "type": "string",
-                    "description": "This identifies the party that sent this event. A client may choose to re-use the device ID from end-to-end cryptography for the value of this field. "
-                },
                 "selected_party_id": {
                     "type": "string",
                     "description": "The `party_id` field from the answer event that the caller chose."
                 },
             },
-            "required": ["call_id", "version"]
+            "required": ["selected_party_id"]
         },
         "type": {
             "type": "string",