Gregsdennis/format registry

[gregsdennis]

What kind of change does this PR introduce?

Feature

Issue & Discussion References

Related to #1552

Summary

• Adds a format registry file and includes OpenAPI 3.1.1 formats. In the issue, I mocked up the registry with an array at the root, but realized an object would be good since we really shouldn't have multiple definitions for the same format. (I have other thoughts on this that I'll post in the issue and update here if necessary.)
• Adds text defining the registry and requirements for implementations to support them. Having a link to a later section feels weird to me. Maybe it's not? Happy to reorganize if others think it's off.

Does this PR introduce a breaking change?

No. There is a new "SHOULD" requirement to support the registry formats. I'd like this to be slightly less required than the ones defined by JSON Schema, but "MAY" seems not required enough. Open to entertaining ideas.

[ralfhandl]

@gregsdennis What about the formats registered in https://spec.openapis.org/registry/format/index.html?
Will they be eventually registered here, too?

And what will be the process/hurdles for registering formats?

Goal would be to retire the OAS format registry and instead redirect here.

[gregsdennis]

I didn't know that page existed. I was just looking at your spec.

Yeah, I expect those can be pulled in as well. The plan was to transfer your registry to us.

Given the sheer volume of formats, I'm more inclined to use "MAY" for the registry formats, but also reserve those names so that they can only mean what's registered. That way if those names are supported, they MUST be these formats.

[karenetheridge]

We'll want to support an array for hyperlinks that reference the specification, as I think we'll want to specify multiple versions of reference documents. For example, it's useful to note the earliest version of the OAS spec that added mention of a format, but there are also cases where the reference specification for a format has changed over time (e.g. for json-schema's hostname format, draft7 uses RFC1034, draft2019-09+ uses RFC1123 and that information shouldn't be hidden by simply linking to draft7 and draft2019-09. Perhaps we could say something like "RFC1034 via draft7, RFC1123 via draft2019-09 and draft2020-12", but I'm not sure how that could be visibly represented in a compact yet readable way.

The formats listed here so far are present in OpenAPI v3.1.1, but we should also start out by listing all the formats available in various drafts of JSON Schema itself.

Also note that the current OAS format registry is at https://spec.openapis.org/registry/format/index.html and we should include the information contained there if we agree to take on hosting of that registry, although I've spotted a few errors in that data so those will need to be fixed.

(This is a partial regurgitation of the metadata discussed here: #1552 (comment))

Also, as part of the addition of this data file (which the webpage will be generated, via some sort of Github Action presumably) we'll want a json schema that describes the format of this file, which will be evaluated whenever a PR is submitted to make an addition to the file. This will allow us to accept updates from tooling vendors etc and dynamically publish them to the registry after approval.

[karenetheridge]

I didn't know that page existed. I was just looking at your spec.

I'm confused, we talked about proposing a transfer of the registry several months ago here? #1552 (comment)

[gregsdennis]

I've imported all of the formats. It was processed by GH Copilot.

[gregsdennis]

I'm confused... @karenetheridge

The answer is in your remark: "several months ago" 😆