Rename custom-formats.yaml to string-formats.yaml

changelogs/internal/newsfragments/1977.clarification

@@ -0,0 +1 @@
+Rename `custom-formats.yaml` to `string-formats.yaml` and update its docs.

data/custom-formats.yaml → data/string-formats.yaml

@@ -12,15 +12,29 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# This file contains the list of custom formats supported for the `format` key
-# and the `x-pattern-format` extension (see `openapi_extensions.md` for more
-# details).
+# This file contains the list of string formats supported for the `format` key
+# and the `x-pattern-format` extension within JSON Schema objects in the
+# OpenAPI documents within the Matrix Specification. See
+# `openapi_extensions.md` [1] for more details.
 #
-# Each entry must use the `mx-` prefix and have the form:
+# [1]: https://github.com/matrix-org/matrix-spec/blob/main/openapi_extensions.md#custom-x-pattern-format-key-and-custom-formats
 #
-# mx-custom-key:
+# Custom formats defined in the Matrix specification should always use the `mx-`
+# prefix. They should link to the section containing the definition of the
+# format in the spec.
+#
+# Formats that are already supported in the JSON Schema specification should
+# link to the RFC where they are defined, and should not use a regex to allow
+# tools that recognize the format to validate it properly.
+# See <https://json-schema.org/understanding-json-schema/reference/string#built-in-formats>.
+#
+# All entries have the form:
+#
+# key:
 #   title: The title rendered in the specification
 #   url: /url/to#definition
+#   # regex: A regex that can be used to validate the custom format if possible.
+#            It should be used as the `pattern` of the string.
 
 mx-user-id:
   title: User ID
@@ -49,5 +63,4 @@ mx-mxc-uri:
 
 uri:
   title: URI
-  url: http://tools.ietf.org/html/rfc3986
-  # no regex
+  url: https://datatracker.ietf.org/doc/html/rfc3986

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

@@ -157,7 +157,7 @@
 
         {{/* If the string uses a known format, use it. */}}
         {{ with .format }}
-            {{ with partial "custom-format" . }}
+            {{ with partial "string-format" . }}
                 {{ $type = . }}
             {{ end }}
         {{ end }}
@@ -264,7 +264,7 @@
         {{ range $formatId, $formatType := $formatMap.Values }}
             {{ $formatKey := "string" }}
             {{ if ne $formatId "string" }}
-                {{ with partial "custom-format" $formatId }}
+                {{ with partial "string-format" $formatId }}
                     {{ $formatKey = . }}
                 {{ else }}
                     {{ errorf "Unsupported value for `x-pattern-format`: %s" $formatId }}
@@ -331,12 +331,12 @@
     Computes the type to display for a string format, given the identifier of
     the format as a string.
 */}} 
-{{ define "partials/custom-format" }}
-  {{ $customFormat := "" }}
+{{ define "partials/string-format" }}
+  {{ $stringFormat := "" }}
 
-  {{ with index site.Data "custom-formats" . }}
-    {{ $customFormat = printf "<a href=\"%s\">%s</a>" (htmlEscape .url) (htmlEscape .title) }}
+  {{ with index site.Data "string-formats" . }}
+    {{ $stringFormat = printf "<a href=\"%s\">%s</a>" (htmlEscape .url) (htmlEscape .title) }}
   {{ end }}
 
-  {{ return $customFormat }}
+  {{ return $stringFormat }}
 {{ end }}

openapi_extensions.md

@@ -39,8 +39,8 @@ 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.
+`data/string-formats.yaml`. The values in this file are recognized in the
+rendered specification and link to the definition of the format.
 
 ## Custom `x-weight` key