diff --git a/content/appendices.md b/content/appendices.md index c622c0e9..0138b1c3 100644 --- a/content/appendices.md +++ b/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 diff --git a/data/api/client-server/definitions/sso_login_flow.yaml b/data/api/client-server/definitions/sso_login_flow.yaml index 0dd011b3..464a5f89 100644 --- a/data/api/client-server/definitions/sso_login_flow.yaml +++ b/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