content/client-server-api/_index.md

@@ -1486,17 +1486,17 @@ MAY reject weak passwords with an error code `M_WEAK_PASSWORD`.
 Before being able to use the authorization flow to obtain an access token, a
 client needs to obtain a `client_id` by registering itself with the server.
 
-This should be done via OAuth 2.0 Dynamic Client Registration as defined in
+One way to do that is to leverage OAuth 2.0 Dynamic Client Registration as
-[RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591).
+defined in [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591).
 
 ##### Client metadata
 
 In OAuth 2.0, clients register a set of metadata values with the authorization
-server, which associates it with a newly generated `client_id`. These values are
+server which associates it to a newly generated `client_id`. These values are
 used to describe the client to the user and define how the client interacts with
 the server.
 
-{{% definition path="schemas/oauth2-client-metadata" %}}
+{{% json-schema name="oauth2-client-metadata" %}}
 
 ###### Metadata localization
 
@@ -1539,19 +1539,20 @@ In all cases, the redirect URI MUST NOT have a fragment component.
 
 `web` clients can use redirect URIs that:
 
-- MUST use the `https` scheme.
+- MUST use the `https` scheme
-- MUST NOT use a user or password in the authority component of the URI.
+- MUST NOT use a user or password in the authority component of the URI
 - MUST use the client URI as a common base for the authority component, as
-  defined previously.
+  defined previously
-- MAY include an `application/x-www-form-urlencoded` formatted query component.
+- MAY include an `application/x-www-form-urlencoded` formatted query component
 
-For example, with `https://example.com/` as the client URI, the following are
+For example, with `https://example.com/` as the client URI,
-valid redirect URIs:
+
+These are valid redirect URIs:
 - `https://example.com/callback`
 - `https://app.example.com/callback`
 - `https://example.com:5173/?query=value`
 
-With the same client URI, the following are invalid redirect URIs:
+These are invalid redirect URIs:
 - `https://example.com/callback#fragment`
 - `http://example.com/callback`
 - `http://localhost/`
@@ -1560,25 +1561,23 @@ With the same client URI, the following are invalid redirect URIs:
 
 `native` clients can use three types of redirect URIs:
 
-1. **Private-Use URI Scheme**
+1. Private-Use URI Scheme:
-    - The scheme MUST be prefixed with the client URI hostname in reverse-DNS
+  - the scheme MUST be prefixed with the client URI hostname in reverse-DNS
     notation. For example, if the client URI is `https://example.com/`, then a
     valid custom URI scheme would be `com.example.app:/`.
-    - There MUST NOT be an authority component. This means that the URI MUST have
+  - the URI MUST NOT have an authority component. This means that it MUST have
     either a single slash or none immediately following the scheme, with no
     hostname, username, or port.
-2. **`http` URI on the loopback interface**
+2. `http` URI on the loopback interface:
-    - The scheme MUST be `http`.
+  - it MUST use the `http` scheme
-    - The host part MUST be `localhost`, `127.0.0.1`, or `[::1]`.
+  - the host part MUST be `localhost`, `127.0.0.1`, or `[::1]`
-    - There MUST NOT be a port. The homeserver MUST then accept any port number
+  - it MUST have no port. The homeserver MUST then accept any port number during
-      during the authorization flow.
+    the authorization flow.
-3. **Claimed `https` Scheme URI**
+3. Claimed `https` Scheme URI: some operating systems allow apps to claim
-
+  `https` scheme URIs in the domains they control. When the browser encounters a
-    Some operating systems allow apps to claim `https` scheme URIs in the
+  claimed URI, instead of the page being loaded in the browser, the native app
-    domains they control. When the browser encounters a claimed URI, instead of
+  is launched with the URI supplied as a launch parameter. The same rules as for
-    the page being loaded in the browser, the native app is launched with the
+  `web` clients apply.
-    URI supplied as a launch parameter. The same rules as for `web` clients
-    apply.
 
 These restrictions are the same as defined by [RFC 8252 section 7](https://tools.ietf.org/html/rfc8252#section-7).
 
@@ -1602,7 +1601,7 @@ These are invalid redirect URIs:
 
 To register, the client sends an HTTP `POST` request to the
 `registration_endpoint`, which can be found in the server metadata. The body of
-the request is the JSON-encoded [`OAuthClientMetadata`](#client-metadata).
+the request is the JSON client metadata.
 
 For example, the client could send the following registration request:
 
@@ -1639,7 +1638,7 @@ Upon successful registration, the server replies with an `HTTP 201 Created`
 response, with a JSON object containing the allocated `client_id` and all the
 registered metadata values.
 
-With the registration request above, the server might reply with:
+With the previous registration request, the server would reply with:
 
 ```json
 {

data/schemas/oauth2-client-metadata.yaml

@@ -11,7 +11,7 @@
 # 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.
-title: OAuthClientMetadata
+title: OAuth 2.0 Client Server Metadata
 type: object
 description: |-
   This definition of the metadata specifies only the fields that are meaningful

layouts/shortcodes/json-schema.html

@@ -0,0 +1,46 @@
+{{/*
+
+    This template is used to render the fields of a JSON schema that is not an
+    event.
+
+    It expects to be passed a `name` parameter, which is the name of a file
+    under /data/schemas. The file extension is omitted.
+    
+    For example:
+
+        {{% json-schema name="oauth2-client-metadata" %}}
+
+*/}}
+
+{{ $schema := index .Site.Data "schemas" .Params.name }}
+{{ $path := delimit (slice "schemas" .Params.name) "/" }}
+
+{{ $schema = partial "json-schema/resolve-refs" (dict "schema" $schema "path" $path) }}
+{{ $schema = partial "json-schema/resolve-allof" $schema }}
+
+<section class="rendered-data event">
+
+<details {{ if not .Site.Params.ui.rendered_data_collapsed }}open{{ end }}>
+<summary>
+
+<h1>
+ <code>{{ $schema.title }}</code>
+</h1>
+</summary>
+
+<hr>
+
+{{ if $schema.description -}}
+    {{ $schema.description | markdownify -}}
+{{ end -}}
+
+{{ $schema = merge $schema (dict "title" "") -}}
+
+{{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema) -}}
+{{ range $additional_types -}}
+    {{ partial "openapi/render-object-table" . -}}
+{{ end -}}
+
+</details>
+
+</section>