Skip to content

Commit

Permalink
Rename custom-formats.yaml to string-formats.yaml (#1977)
Browse files Browse the repository at this point in the history
It does not contain only custom formats, so the name didn't fit anymore.
Update also the docs to reflect that.
  • Loading branch information
zecakeh authored Oct 30, 2024
1 parent 88f0c56 commit 1e0919a
Show file tree
Hide file tree
Showing 4 changed files with 30 additions and 16 deletions.
1 change: 1 addition & 0 deletions changelogs/internal/newsfragments/1977.clarification
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Rename `custom-formats.yaml` to `string-formats.yaml` and update its docs.
27 changes: 20 additions & 7 deletions data/custom-formats.yaml → data/string-formats.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
14 changes: 7 additions & 7 deletions layouts/partials/openapi/render-object-table.html
Original file line number Diff line number Diff line change
Expand Up @@ -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 }}
Expand Down Expand Up @@ -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 }}
Expand Down Expand Up @@ -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 }}
4 changes: 2 additions & 2 deletions openapi_extensions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down

0 comments on commit 1e0919a

Please sign in to comment.