Merge pull request #2097 from matrix-org/travis/1.0/common-themes

Specify some of the common concepts for Matrix in the index

api/server-server/keys_query.yaml

@@ -44,8 +44,10 @@ paths:
           type: string
           description: |-
             **Deprecated**. Servers should not use this parameter and instead
-            opt to return all keys, not just the requested one. The key ID to 
+            opt to return all keys, not just the requested one. The key ID to
             look up.
+
+            When excluded, the trailing slash on this endpoint is optional.
           required: false
           x-example: "ed25519:abc123"
         - in: query
@@ -53,7 +55,7 @@ paths:
           type: integer
           format: int64
           description: |-
-            A millisecond POSIX timestamp in milliseconds indicating when the returned 
+            A millisecond POSIX timestamp in milliseconds indicating when the returned
             certificates will need to be valid until to be useful to the requesting server.
 
             If not supplied, the current time as determined by the notary server is used.
@@ -114,7 +116,7 @@ paths:
                         format: int64
                         description: |-
                           A millisecond POSIX timestamp in milliseconds indicating when
-                          the returned certificates will need to be valid until to be 
+                          the returned certificates will need to be valid until to be
                           useful to the requesting server.
 
                           If not supplied, the current time as determined by the notary

api/server-server/keys_server.yaml

@@ -51,6 +51,8 @@ paths:
             **Deprecated**. Servers should not use this parameter and instead
             opt to return all keys, not just the requested one. The key ID to
             look up.
+
+            When excluded, the trailing slash on this endpoint is optional.
           required: false
           x-example: "ed25519:abc123"
           deprecated: true

changelogs/server_server/newsfragments/2097.clarification

@@ -0,0 +1 @@
+Clarify that the trailing slash is optional on ``/keys/*`` endpoints when no key ID is requested.

specification/index.rst

@@ -425,6 +425,37 @@ dedicated API.  The API is symmetrical to managing Profile data.
   Would it really be overengineered to use the same API for both profile &
   private user data, but with different ACLs?
 
+
+Common concepts
+---------------
+
+Various things are common throughout all of the Matrix APIs. They are
+documented here.
+
+.. TODO: Some words about trailing slashes. See https://github.com/matrix-org/matrix-doc/issues/2107
+
+Namespacing
+~~~~~~~~~~~
+
+Namespacing helps prevent conflicts between multiple applications and the specification
+itself. Where namespacing is used, ``m.`` prefixes are used by the specification to
+indicate that the field is controlled by the specification. Custom or non-specified
+namespaces used in the wild MUST use the Java package naming convention to prevent
+conflicts.
+
+As an example, event types defined in the specification are namespaced under the
+special ``m.`` prefix, however any client can send a custom event type, such as
+``com.example.game.score`` (assuming the client has rights to the ``com.example``
+namespace) without needing to put the event into the ``m.`` namespace.
+
+Timestamps
+~~~~~~~~~~
+
+Unless otherwise stated, timestamps are measured as milliseconds since the Unix epoch.
+Throughout the specification this may be referred to as POSIX, Unix, or just "time in
+milliseconds".
+
+
 .. _`room versions`:
 
 Room Versions