Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up
Appearance settings

Gregsdennis/format registry #1574

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gregsdennis merged 9 commits into main from gregsdennis/format-registry
Apr 19, 2025
Merged

Gregsdennis/format registry #1574

gregsdennis merged 9 commits into main from gregsdennis/format-registry
Apr 19, 2025

Conversation

@gregsdennis
Copy link
Member

@gregsdennis gregsdennis commented Jan 15, 2025

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.

Copy link

@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 reacted with thumbs up emoji

Copy link
Member Author

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.

ralfhandl reacted with thumbs up emoji

Copy link
Member

karenetheridge commented Jan 23, 2025
edited
Loading

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.

gregsdennis reacted with thumbs up emoji

Copy link
Member

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)

Copy link
Member Author

gregsdennis commented Jan 31, 2025
edited
Loading

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

darrelmiller reacted with thumbs up emoji

Copy link
Member Author

I'm confused... @karenetheridge

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

karenetheridge reacted with laugh emoji

Copy link
Member Author

@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.

Comment on lines 331 to 332
- SHOULD provide validation for each format attribute defined in this document
and listed in the {{format-registry}};
Copy link
Member

@jdesrosiers jdesrosiers Apr 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@gregsdennis gregsdennis Apr 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

jdesrosiers reacted with thumbs up emoji
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"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 and gregsdennis reacted with thumbs up emoji
Copy link
Member

@jdesrosiers jdesrosiers Apr 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@gregsdennis gregsdennis Apr 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated

registry, but such support MUST be configurable and disabled by default;
- SHOULD use a common parsing library or a well-known regular expression for
each format;
- SHOULD clearly document how and to what degree each format attribute is
Copy link
Member

@jdesrosiers jdesrosiers Apr 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@gregsdennis gregsdennis Apr 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

@jdesrosiers jdesrosiers Apr 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 reacted with thumbs up emoji
Copy link
Member Author

@gregsdennis gregsdennis Apr 18, 2025
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@gregsdennis gregsdennis force-pushed the gregsdennis/format-registry branch from 8c83866 to ae1edc7 Compare April 18, 2025 03:22
@gregsdennis gregsdennis merged commit 775b578 into main Apr 19, 2025
6 checks passed
@gregsdennis gregsdennis deleted the gregsdennis/format-registry branch April 19, 2025 04:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jdesrosiers jdesrosiers jdesrosiers approved these changes

+2 more reviewers

@GREsau GREsau GREsau left review comments

@ralfhandl ralfhandl ralfhandl approved these changes

Reviewers whose approvals may not affect merge requirements

Projects

Development

Successfully merging this pull request may close these issues.

AltStyle によって変換されたページ (->オリジナル) /