Add support for pattern formats for patternProperties

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

data/custom-formats.yaml

@@ -0,0 +1,33 @@
+# Copyright 2024 Commaille Kévin
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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.
+#
+# The list of custom formats supported for the `format` key and the
+# `x-pattern-format` extension (see `openapi_extensions.md` for more details).
+#
+# Each entry must use the `mx-` prefix and have the form:
+#
+# mx-custom-key:
+#   title: The title rendered in the specification
+#   url: /url/to#definition
+#   pattern: "REGEX" (not used for rendering, but allows to define the common
+#                     pattern to use for the format)
+
+mx-user-id:
+  title: User ID
+  url: /appendices#user-identifiers
+  pattern: "^@"
+mx-event-id:
+  title: Event ID
+  url: /appendices#event-ids
+  pattern: "^\\$"

data/event-schemas/schema/m.ignored_user_list.yaml

@@ -17,7 +17,7 @@ properties:
           "^@":
             type: "object"
             description: "An empty object for future enhancement"
-            x-pattern: "$USER_ID"
+            x-pattern-format: "mx-user-id"
     required:
       - ignored_users
   type:

data/event-schemas/schema/m.receipt.yaml

@@ -16,7 +16,7 @@ properties:
         patternProperties:
             "^\\$":
                 type: object
-                x-pattern: "$EVENT_ID"
+                x-pattern-format: "mx-event-id"
                 title: Event Receipts
                 description: |-
                     The collection of receipts for this event ID.
@@ -34,7 +34,7 @@ properties:
                                 description: |-
                                     The mapping of user ID to receipt. The user ID is the
                                     entity who sent this receipt.
-                                x-pattern: "$USER_ID"
+                                x-pattern-format: "mx-user-id"
                                 properties:
                                     ts:
                                         type: integer

layouts/partials/openapi/render-object-table.html

@@ -179,17 +179,47 @@
         {{/*
             If the property uses `patternProperties` to describe its
             internal structure, handle this with a bit of recursion.
-            Note that we ignore the pattern as the current definitions
+            Types are grouped by pattern format. Note that we ignore
+            patterns without a format as the current definitions
             always have a single pattern, but we might need to handle
             them later to differentiate schemas according to patterns.
         */}}
-        {{ $types := slice }}
 
-        {{ range $pattern, $schema := .patternProperties}}
+        {{/* Use a Scratch to manipulate the map easily. */}}
-            {{ $types = $types | append (partial "property-type" $schema) }}
+        {{ $scratch := newScratch }}
+
+        {{ range $pattern, $schema := .patternProperties }}
+            {{ $formatId := "string" }}
+            {{ with index $schema "x-pattern-format" }}
+                {{ $formatId = . }}
             {{ end }}
 
-        {{ $type = delimit (slice "{string: " (delimit $types "|") "}" ) "" }}
+            {{/* Initialize the map for the format if it doesn't exist. */}}
+            {{ if not (reflect.IsSlice ($scratch.Get $formatId)) }}
+                {{ $scratch.Set $formatId slice }}
+            {{ end }}
+
+            {{ $scratch.Add $formatId (partial "property-type" $schema) }}
+        {{ end }}
+
+        {{/* First generate the type string for each format. */}}
+        {{ $types := slice }}
+        {{ range $formatId, $formatTypes := $scratch.Values }}
+            {{ $formatKey := "string" }}
+            {{ if ne $formatId "string" }}
+                {{ with index site.Data "custom-formats" $formatId }}
+                    {{ $formatKey = printf "<a href=\"%s\">%s</a>" (htmlEscape .url) (htmlEscape .title) }}
+                {{ else }}
+                    {{ errorf "Unsupported value for `x-pattern-format`: %s" $formatId }}
+                {{ end }}
+            {{ end }}
+
+            {{ $formatString := printf "{%s: %s}" $formatKey (delimit $formatTypes "|") }}
+            {{ $types = $types | append $formatString }}
+        {{ end }}
+
+        {{/* Then join all the formats. */}}
+        {{ $type = delimit $types "|" }}
     {{ end }}
 
     {{ return $type }}

openapi_extensions.md

@@ -31,3 +31,12 @@ particular Matrix specification versions.
 
 Although the OpenAPI/JSON Schema specs only allow to use `$ref` to reference a
 whole example, we use it to compose examples from other examples.
+
+## Custom `x-pattern-format` key and custom formats 
+
+In JSON Schema, `format` is a property to convey semantic information about a
+schema. We define `x-pattern-format` as a key on the schemas under
+`patternProperties` with the same use as `format`, but that applies to the
+pattern of the property. We also define custom values for formats with the `mx-`
+prefix in `data/custom-formats.yaml`. Those values are recognized in the
+rendered specification and link to the definition of the format.