From 91c40bb6d05e55292a2c085836e14332a9db1f56 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 15 Oct 2024 11:55:49 +0200 Subject: [PATCH 1/4] Rename custom-formats to string-formats MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit It does not contain only custom formats, so the name didn't fit anymore. Update also the docs to reflect that. Signed-off-by: Kévin Commaille --- ...custom-formats.yaml => string-formats.yaml} | 18 ++++++++++++++---- .../partials/openapi/render-object-table.html | 14 +++++++------- openapi_extensions.md | 4 ++-- 3 files changed, 23 insertions(+), 13 deletions(-) rename data/{custom-formats.yaml => string-formats.yaml} (63%) diff --git a/data/custom-formats.yaml b/data/string-formats.yaml similarity index 63% rename from data/custom-formats.yaml rename to data/string-formats.yaml index 7d52861f1..0b7a9b45a 100644 --- a/data/custom-formats.yaml +++ b/data/string-formats.yaml @@ -12,15 +12,26 @@ # 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 +# This file contains the list of string 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: +# 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. # -# mx-custom-key: +# 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 . +# +# 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 @@ -50,4 +61,3 @@ mx-mxc-uri: uri: title: URI url: http://tools.ietf.org/html/rfc3986 - # no regex diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html index 656f556a7..577da0143 100644 --- a/layouts/partials/openapi/render-object-table.html +++ b/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 }} @@ -319,12 +319,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 "%s" (htmlEscape .url) (htmlEscape .title) }} + {{ with index site.Data "string-formats" . }} + {{ $stringFormat = printf "%s" (htmlEscape .url) (htmlEscape .title) }} {{ end }} - {{ return $customFormat }} + {{ return $stringFormat }} {{ end }} diff --git a/openapi_extensions.md b/openapi_extensions.md index e8fd1002a..3d8ec2f64 100644 --- a/openapi_extensions.md +++ b/openapi_extensions.md @@ -39,5 +39,5 @@ 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. From 2e0806f1de10320cbb57305f9f52667350103ca6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 15 Oct 2024 11:57:44 +0200 Subject: [PATCH 2/4] Update link to RFC3986 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous link was a redirect to the new link. Signed-off-by: Kévin Commaille --- data/string-formats.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/string-formats.yaml b/data/string-formats.yaml index 0b7a9b45a..2adf6fdb5 100644 --- a/data/string-formats.yaml +++ b/data/string-formats.yaml @@ -60,4 +60,4 @@ mx-mxc-uri: uri: title: URI - url: http://tools.ietf.org/html/rfc3986 + url: https://datatracker.ietf.org/doc/html/rfc3986 From 93f2b499bc2d9ebdfdf411dd96affb431da6d119 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 15 Oct 2024 12:02:03 +0200 Subject: [PATCH 3/4] Add changelog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/internal/newsfragments/1977.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/internal/newsfragments/1977.clarification diff --git a/changelogs/internal/newsfragments/1977.clarification b/changelogs/internal/newsfragments/1977.clarification new file mode 100644 index 000000000..3a5e10993 --- /dev/null +++ b/changelogs/internal/newsfragments/1977.clarification @@ -0,0 +1 @@ +Rename `custom-formats.yaml` to `string-formats.yaml` and update its docs. From 785b0121171dbfab5056aff52cea94552be3de5d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Wed, 30 Oct 2024 17:44:22 +0100 Subject: [PATCH 4/4] Improve docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- data/string-formats.yaml | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/data/string-formats.yaml b/data/string-formats.yaml index 2adf6fdb5..e4ebc523a 100644 --- a/data/string-formats.yaml +++ b/data/string-formats.yaml @@ -13,8 +13,11 @@ # limitations under the License. # This file contains the list of string formats supported for the `format` key -# and the `x-pattern-format` extension (see `openapi_extensions.md` for more -# details). +# 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. +# +# [1]: https://github.com/matrix-org/matrix-spec/blob/main/openapi_extensions.md#custom-x-pattern-format-key-and-custom-formats # # Custom formats defined in the Matrix specification should always use the `mx-` # prefix. They should link to the section containing the definition of the