Document threepids

Adds the /msisdn' 3pid type and generally fleshes out what a 3pid
is and how they work.

This merges most of the work from Max Dor in #1039
with some tweaks and additions.

api/identity/lookup.yaml

@@ -1,4 +1,6 @@
 # Copyright 2016 OpenMarket Ltd
+# Copyright 2017 Kamax.io
+# Copyright 2017 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.
@@ -32,13 +34,13 @@ paths:
           type: string
           name: medium
           required: true
-          description: The literal string "email".
+          description: The medium type of the 3pid. See `Appendices`_.
           x-example: "email"
         - in: query
           type: string
           name: address
           required: true
-          description: The email address being looked up.
+          description: The address of the 3pid being looked up. See `Appendices`_.
           x-example: "louise@bobs.burgers"
       responses:
         200:
@@ -82,4 +84,4 @@ paths:
                 description: The unix timestamp at which the association was verified.
               signatures:
                 type: object
-                description: The signatures of the verifying identity service which show that the association should be trusted, if you trust the verifying identity service.
+                description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services.

specification/appendices/threepids.rst

@@ -0,0 +1,48 @@
+.. Copyright 2017 Kamax.io
+..
+.. 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.
+
+3PID Types
+----------
+3PIDs represent identifiers on other namespaces that might be associated with a
+particular person. They comprise a tuple of `medium` which is a string that
+identifies the namespace in which the identifier exists and an `address`: a
+string representing the identifier in that namespace. This must be a canonical
+form of the identifier, ie. if multiple strings could represent the same
+identifier, only one of these strings must be used in a 3PID address, in a
+well-defined manner.
+
+For example, for e-mail, the `medium` is 'email' and the `address` would be the
+email address, eg. the string 'bob@example.com'. Since domain resolution is
+case-insensitive, the email address 'bob@Example.com' also has a 3PID address
+of 'bob@example.com' and not 'bob@Example.com'.
+
+The namespaces defined by this specification are listed below. More namespaces
+may be defined in future versions of this specification.
+
+E-Mail
+~~~~~~
+Medium: `email`
+
+Represents E-Mail addresses. The `address` is the raw email address in
+user@domain form with the domain in lowercase. It must not contain other text
+such as real name, angle brackets or a mailto: prefix.
+
+PSTN Phone numbers
+~~~~~~~~~~~~~~~~~~
+Medium: `msisdn`
+
+Represents telephone numbers on the public switched telephone network.  The
+`address` is the telephone number represented as a MSISDN (Mobile Station
+International Subscriber Directory Number) as defined by the E.164 numbering
+plan. Note that MSISDNs do not include a leading '+'.

specification/identity_service_api.rst

@@ -1,4 +1,6 @@
 .. Copyright 2016 OpenMarket Ltd
+.. Copyright 2017 Kamax.io
+.. Copyright 2017 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.
@@ -52,6 +54,8 @@ necessarily provide evidence that they have validated associations, but claim to
 have done so. Establishing the trustworthiness of an individual identity service
 is left as an exercise for the client.
 
+3PID types are described in the `Appendices`_.
+
 Privacy
 -------
 
@@ -291,3 +295,4 @@ It will look up ``token`` which was stored in a call to ``store-invite``, and fe
  }
 
 .. _`Unpadded Base64`:  ../appendices.html#unpadded-base64
+.. _`Appendices`:  ../appendices.html#threepids

specification/targets.yaml

@@ -33,6 +33,7 @@ targets:
     files:
       - appendices.rst
       - appendices/base64.rst
+      - appendices/threepids.rst
       - appendices/signing_json.rst
       - appendices/identifier_grammar.rst
       - appendices/threat_model.rst