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" 😆

[gregsdennis]

@json-schema-org/tsc I think thisi is one that we can pull in and even publish before we release the spec.

There's still a fair amount of planning, design, and work to do to get it on the website, but this is a critical step for that to take place.

[jdesrosiers]

I can see the registry growing to have hundreds of entries. I don't think suggesting that implementations should implement all of them is realistic.

[gregsdennis]

We need a middle ground between SHOULD and MAY for the registry. Kind of a "hey it's a good idea if you want to, but you don't, no big deal."

[GREsau]

"Implementations are encouraged to X" is a pattern I've noticed in a few RFCs, is that the type of thing you're looking for?

e.g.

- SHOULD provide validation for each format attribute defined in this document;
- are encouraged to provide validation for format attributes listed in the {{format-registry}};

[jdesrosiers]

I like "encouraged". How about something like, "implementations are encouraged implement formats from the registry and SHOULD (MUST?) provide an extension mechanism for formats they don't support".

The idea is that you either need to provide support for every format in the registry or provide a mechanism for the user to plug in support for anything that's missing.

[gregsdennis]

Updated

[jdesrosiers]

I don't think this bullet point makes sense. We don't allow partial validation anymore, so full validation is the only valid way to validate a format.

[gregsdennis]

I agree, but realistically implementations are going to support formats only as far as they care to, even if we include a bunch of edge-case tests. I think having a note that requires implementations to declare their support (or maybe their limitations) covers that base.

[jdesrosiers]

I see what you're saying, but I feel like it gives permission for incomplete validation, which we don't want.

(or maybe their limitations)

Yeah, that. I think that's better. You shouldn't have to say you support what you're required to support. You should only have declare when your support is lacking in some way.

[gregsdennis]

Updated. Limitations is what I intended for implementations to document.