Definition of "Standard Identifier Format" (#3171)

Spec for #2758

Author: turt2live

content/appendices.md

@@ -387,6 +387,38 @@ Some identifiers are specific to given room versions, please refer to
 the [room versions specification](/rooms) for more
 information.
 
+### Common Namespaced Identifier Grammar
+
+The specification defines some identifiers to use the *Common Namespaced
+Identifier Grammar*. This is a common grammar intended for non-user-visible
+identifiers, with a defined mechanism for implementations to create new
+identifiers.
+
+The grammar is defined as follows:
+
+ * An identifier must be at least one character and at most 255 characters
+   in length.
+ * Identifiers must start with one of the characters `[a-z]`, and be entirely
+   composed of the characters `[a-z]`, `[0-9]`, `-`, `_` and `.`.
+ * Identifiers starting with the characters `m.` are reserved for use by the
+   official Matrix specification.
+ * Identifiers which are not described in the specification should follow the
+   Java Package Naming Convention to namespace their identifier. This is typically
+   a reverse DNS format, such as `com.example.identifier`.
+
+{{% boxes/note %}}
+Identifiers can and do inherit grammar from this specification. For example, "this
+identifier uses the Common Namespaced Identifier Grammar, though without the namespacing
+requirements" - this means that `m.` is still reserved, but that implementations
+do not have to use the reverse DNS scheme to namespace their custom identifier.
+{{% /boxes/note %}}
+
+{{% boxes/rationale %}}
+ASCII characters do not have issues with homoglyphs or alternative encodings which
+might interfere with the identifier's purpose. Additionally, using lowercase
+characters prevents concerns about case sensitivity.
+{{% /boxes/rationale %}}
+
 ### Server Name
 
 A homeserver is uniquely identified by its server name. This value is

data/api/client-server/definitions/sso_login_flow.yaml

@@ -59,7 +59,6 @@ properties:
           example: "mxc://example.org/abc123"
         brand:
           type: string
-          # TODO @@TR: Actually link to "common identifier format" section when it exists.
           description: |-
             Optional UI hint for what kind of common SSO provider is being
             described in this IdP. Matrix maintains a registry of identifiers
@@ -71,7 +70,7 @@ properties:
             including those in the registry, though are expected to be able to
             present any IdP based off the `name`/`icon` to the user regardless.
 
-            Unregistered brands are permitted using the Standard Identifier Format,
+            Unregistered brands are permitted using the [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar),
             though excluding the namespace requirements. For example, `examplesso`
             is a valid brand which is not in the registry but still permitted.
             Servers should be mindful that clients might not support their unregistered