Merge pull request #1068 from matrix-org/dbkr/threepid_add_msisdn

Document threepids

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 the `3PID Types`_ Appendix.
           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 the `3PID Types`_ Appendix.
           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
+----------
+Third Party Identifiers (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, *i.e.* 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, *e.g.* the string ``bob@example.com``. Since domain resolution is
+case-insensitive, the email address ``bob@Example.com`` is also has the 3PID address
+of ``bob@example.com`` (without the capital 'e') rather than ``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 `3PID Types`_ Appendix.
+
 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
+.. _`3PID Types`:  ../appendices.html#pid-types

specification/targets.yaml

@@ -35,6 +35,7 @@ targets:
       - appendices/base64.rst
       - appendices/signing_json.rst
       - appendices/identifier_grammar.rst
+      - appendices/threepids.rst
       - appendices/threat_model.rst
       - appendices/test_vectors.rst
 groups:  # reusable blobs of files when prefixed with 'group:'