Define opaque identifier grammar (#1791)

Since we already have three of these, and I'm about to add a fourth, let's pull
it out to a common definition.

We could, of course, keep defining the grammar each time it's used, but
defining it in an appendix helps us be consistent for future API design.

changelogs/appendices/newsfragments/1791.clarification

@@ -0,0 +1 @@
+Define 'Opaque Identifier Grammar'.

content/appendices.md

@@ -921,6 +921,25 @@ unique servers based on the following criteria:
     specify the servers it can. For example, a room with only 2 users in
     it would result in maximum 2 `via` parameters.
 
+### Opaque Identifiers
+
+The specification defines some identifiers to use the *Opaque Identifier
+Grammar*. This is a common grammar intended for non-user-visible identifiers
+which do not require parsing or interpretation (other than as a unique
+identifier).
+
+The grammar is defined as:
+
+* Identifiers must be entirely composed of the characters `[0-9]`, `[A-Z]`,
+  `[a-z]`, `-`, `.`, `_`, and `~`.
+* Unless otherwise specified, identifiers must be at least one character and at
+  most 255 characters in length.
+
+{{% boxes/note %}}
+The acceptable character set matches the unreserved character set in [RFC
+3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3).
+{{% /boxes/note %}}
+
 ## 3PID Types
 
 Third-party Identifiers (3PIDs) represent identifiers on other

content/client-server-api/_index.md

@@ -943,11 +943,12 @@ or completely closed registration (where the homeserver administrators create
 and distribute accounts).
 
 The token required for this authentication type is shared out of band from
-Matrix and is an opaque string with maximum length of 64 characters in the
+Matrix and is an opaque string using the [Opaque Identifier
-range `[A-Za-z0-9._~-]`. The server can keep any number of tokens for any
+Grammar](/appendices#opaque-identifiers), with maximum length of 64
-length of time/validity. Such cases might be a token limited to 100 uses or
+characters. The server can keep any number of tokens for any length of
-for the next 2 hours - after the tokens expire, they can no longer be used
+time/validity. Such cases might be a token limited to 100 uses or for the next
-to create accounts.
+2 hours - after the tokens expire, they can no longer be used to create
+accounts.
 
 To use this authentication type, clients should submit an auth dict with just
 the type, token, and session:
@@ -1201,7 +1202,7 @@ is complete, the client will need to submit a `/login` request matching
 `m.login.token`.
 
 {{< added-in v="1.7" >}} Already-authenticated clients can additionally generate
-a token for their user ID if supported by the homeserver using 
+a token for their user ID if supported by the homeserver using
 [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token).
 
 {{% http-api spec="client-server" api="login" %}}

content/client-server-api/modules/voip_events.md

@@ -96,13 +96,8 @@ Matrix clients can send DTMF as specified by WebRTC. The WebRTC standard as of A
 in the RTP payload.
 
 #### Grammar for VoIP IDs
-`call_id`s and `party_id` are explicitly defined to be between 1 and 255 characters long, consisting
-of the characters `[0-9a-zA-Z._~-]`.
 
-(Note that this matches the grammar of 'opaque IDs' from
+`call_id`s and `party_id` must follow the [Opaque Identifier Grammar](/appendices#opaque-identifiers).
-[MSC1597](https://github.com/matrix-org/matrix-spec-proposals/blob/rav/proposals/id_grammar/proposals/1597-id-grammar.md#opaque-ids),
-and that of the `id` property of the
- [`m.login.sso` flow schema](#definition-mloginsso-flow-schema).)
 
 #### Behaviour on Room Leave
 If the client sees the user it is in a call with leave the room, the client should treat this

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

@@ -40,10 +40,7 @@ properties:
           description: |-
             Opaque string chosen by the homeserver, uniquely identifying
             the IdP from other IdPs the homeserver might support. Should
-            be between 1 and 255 characters in length, containing unreserved
+            use the [Opaque identifier Grammar](/appendices#opaque-identifiers).
-            characters under [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt)
-            (`ALPHA  DIGIT  "-" / "." / "_" / "~"`). Clients are not intended
-            to parse or infer meaning from opaque strings.
           example: "com.example.idp.github"
         name:
           type: string