Clarify that sdpMid and sdpMLineIndex are not required in `m.call.candidates` (#1742)

* Convert m.call.candidates schema to YAML

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Clarify that sdpMid and sdpMLineIndex are not required in `m.call.candidates`

MSC2746, merged in v1.17,
introduced the end-of-candidates candidate,
where only the `candidate` property is set to an empty string.

Besides, the [WebRTC specification](https://www.w3.org/TR/webrtc/)
says that only one of those fields is required in a normal candidate.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add changelog

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Link to the "End-of-candidates" section, and clarify what "empty" means

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

---------

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

changelogs/client_server/newsfragments/1742.clarification

@@ -0,0 +1 @@
+Clarify that `sdpMid` and `sdpMLineIndex` are not required in `m.call.candidates`.

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

@@ -1,45 +1,49 @@
-{
+type: object
-    "type": "object",
+description: |-
-    "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.",
+  This event is sent by callers after sending an invite and by the callee after
-    "allOf": [{
+  answering. Its purpose is to give the other party additional ICE candidates to
-        "$ref": "core-event-schema/room_event.yaml"
+  try using to communicate.
-    }],
+allOf:
-    "properties": {
+  - $ref: core-event-schema/room_event.yaml
-        "content": {
+properties:
-            "type": "object",
+  content:
-            "allOf": [{
+    type: object
-                "$ref": "core-event-schema/call_event.yaml"
+    allOf:
-            }],
+      - $ref: core-event-schema/call_event.yaml
-            "properties": {
+    properties:
-                "candidates": {
+      candidates:
-                    "type": "array",
+        type: array
-                    "description": "Array of objects describing the candidates.",
+        description: Array of objects describing the candidates.
-                    "items": {
+        items:
-                        "type": "object",
+          type: object
-                        "title": "Candidate",
+          title: Candidate
-                        "properties": {
+          properties:
-                            "sdpMid": {
+            sdpMid:
-                                "type": "string",
+              type: string
-                                "description": "The SDP media type this candidate is intended for."
+              description: |-
-                            },
+                The SDP media type this candidate is intended for.
-                            "sdpMLineIndex": {
+
-                                "type": "number",
+                At least one of `sdpMid` or `sdpMLineIndex` is required, unless
-                                "description": "The index of the SDP 'm' line this candidate is intended for."
+                this an end-of-candidates candidate.
-                            },
+            sdpMLineIndex:
-                            "candidate": {
+              type: number
-                                "type": "string",
+              description: |-
-                                "description": "The SDP 'a' line of the candidate."
+                The index of the SDP 'm' line this candidate is intended for.
-                            }
+
-                        },
+                At least one of `sdpMid` or `sdpMLineIndex` is required, unless
-                        "required": ["candidate", "sdpMLineIndex", "sdpMid"]
+                this an end-of-candidates candidate.
-                    }
+            candidate:
-                }
+              type: string
-            },
+              description: |-
-            "required": ["candidates"]
+                The SDP 'a' line of the candidate.
-        },
+
-        "type": {
+                If this is an [end-of-candidates](/client-server-api/#end-of-candidates)
-            "type": "string",
+                candidate, this is the empty string.
-            "enum": ["m.call.candidates"]
+          required:
-        }
+            - candidate
-    }
+    required:
-}
+      - candidates
+  type:
+    type: string
+    enum:
+      - m.call.candidates