Fix indentation and schema references in the identity service spec

api/identity/associations.yaml

@@ -75,6 +75,8 @@ paths:
               "errcode": "M_SESSION_NOT_VALIDATED",
               "error": "This validation session has not yet been completed"
             }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
         404:
           description: The Session ID or client secret were not found
           examples:
@@ -82,6 +84,8 @@ paths:
               "errcode": "M_NO_VALID_SESSION",
               "error": "No valid session was found matching that sid and client secret"
             }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
   "/bind":
     post:
       summary: Publish an association between a session and a Matrix user ID.
@@ -159,6 +163,7 @@ paths:
               signatures:
                 type: object
                 description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services.
+                $ref: "../../schemas/server-signatures.yaml"
             required:
               - address
               - medium
@@ -179,6 +184,8 @@ paths:
               "errcode": "M_SESSION_NOT_VALIDATED",
               "error": "This validation session has not yet been completed"
             }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
         404:
           description: The Session ID or client secret were not found
           examples:
@@ -186,3 +193,5 @@ paths:
               "errcode": "M_NO_VALID_SESSION",
               "error": "No valid session was found matching that sid and client secret"
             }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"

api/identity/email_associations.yaml

@@ -100,6 +100,13 @@ paths:
 
             - ``M_INVALID_EMAIL``: The email address provided was invalid.
             - ``M_EMAIL_SEND_ERROR``: The validation email could not be sent.
+          examples:
+            application/json: {
+              "errcode": "M_INVALID_EMAIL",
+              "error": "The email address is not valid"
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
   "/validate/email/submitToken":
     post:
       summary: Validate ownership of an email address.

api/identity/invitation_signing.yaml

@@ -68,6 +68,7 @@ paths:
               signatures:
                 type: object
                 description: The signature of the mxid, sender, and token.
+                $ref: "../../schemas/server-signatures.yaml"
               token:
                 type: string
                 description: The token for the invitation.
@@ -85,7 +86,10 @@ paths:
             }
         404:
           description: Token was not found.
-          example: {
+          examples: 
+            application/json: {
               "errcode": "M_UNRECOGNIZED",
               "error": "Didn't recognize token"
             }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"

api/identity/lookup.yaml

@@ -55,7 +55,6 @@ paths:
               "not_before": 1428825849161,
               "not_after": 4582425849161,
               "ts": 1428825849161,
-
               "signatures": {
                 "matrix.org": {
                   "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
@@ -86,6 +85,7 @@ paths:
               signatures:
                 type: object
                 description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services.
+                $ref: "../../schemas/server-signatures.yaml"
             required:
               - address
               - medium
@@ -118,9 +118,11 @@ paths:
                 items:
                   type: array
                   title: 3PID mappings
+                  minItems: 2
+                  maxItems: 2
                   items:
-                    type: string
+                    - type: 3PID Medium
-                    title: 3PID medium or address
+                    - type: 3PID Address
                 description: an array of arrays containing the `3PID Types`_ with the ``medium`` in first position and the ``address`` in second position.
             required:
               - "threepids"
@@ -142,9 +144,12 @@ paths:
                 items:
                   type: array
                   title: 3PID mappings
+                  minItems: 3
+                  maxItems: 3
                   items:
-                    type: string
+                    - type: 3PID Medium
-                    title: 3PID medium or address or the Matrix ID
+                    - type: 3PID Address
+                    - type: Matrix User ID
                 description: an array of array containing the `3PID Types`_ with the ``medium`` in first position, the ``address`` in second position and Matrix ID in third position.
             required:
               - "threepids"

api/identity/phone_associations.yaml

@@ -106,6 +106,13 @@ paths:
 
             - ``M_INVALID_ADDRESS``: The phone number provided was invalid.
             - ``M_SEND_ERROR``: The validation SMS could not be sent.
+          examples:
+            application/json: {
+              "errcode": "M_INVALID_ADDRESS",
+              "error": "The phone number is not valid"
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
   "/validate/msisdn/submitToken":
     post:
       summary: Validate ownership of a phone number.

api/identity/pubkey.yaml

@@ -52,6 +52,18 @@ paths:
             properties:
               public_key:
                 type: string
+                description: Unpadded Base64 encoded public key.
+            required: ['public_key']
+        404:
+          description:
+            The public key was not found.
+          examples:
+            application/json: {
+              "errcode": "M_NOT_FOUND",
+              "error": "The public key was not found"
+            }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"
   "/pubkey/isvalid":
     get:
       summary: Check whether a long-term public key is valid.

api/identity/store_invite.yaml

@@ -113,3 +113,5 @@ paths:
               "error": "Binding already known",
               "mxid": mxid
             }
+          schema:
+            $ref: "../client-server/definitions/errors/error.yaml"

schemas/server-signatures.yaml

@@ -0,0 +1,24 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+type: object
+example: {
+  "example.com": {
+    "ed25519:0": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
+  }
+}
+additionalProperties:
+  type: object
+  title: Server Signatures
+  additionalProperties:
+    type: string

specification/identity_service_api.rst

@@ -23,7 +23,7 @@ user identifiers. From time to time, it is useful to refer to users by other
 number. This identity service specification describes how mappings between
 third-party identifiers and Matrix user identifiers can be established,
 validated, and used. This description technically may apply to any 3pid, but in
-practice has only been applied specifically to email addresses.
+practice has only been applied specifically to email addresses and phone numbers.
 
 .. contents:: Table of Contents
 .. sectnum::