Skip to content
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

schema updates for 3.0.4 #4125

Closed
2 of 5 tasks
karenetheridge opened this issue Oct 3, 2024 · 4 comments
Closed
2 of 5 tasks

schema updates for 3.0.4 #4125

karenetheridge opened this issue Oct 3, 2024 · 4 comments
Assignees
Labels
Milestone

Comments

@karenetheridge
Copy link
Member

karenetheridge commented Oct 3, 2024

The 3.0.4 schemas need a review pass for accuracy.

  • update $comment, description and $id URIs for v3.0.3->v3.0.4 (where can an html preview of the specification be viewed?)
  • ensure links in specification (referencing schema files) are correct
    • 3.0.4 and 3.1.1 will link to https://spec.openapis.org/ which now has a subsection "Non-Normative JSON Schemas" with "view" and "download" links
  • compare specification and schema diffs from 3.0.3 and 3.0.4, thinking about any spec changes that haven't yet been reflected in the schemas, and what changes have been made to the schemas already and confirm they are accurate (this SHOULD be a no-op, but mistakes have occasionally happened before ;) )
  • ensure the .json and .yaml files are consistent
  • verify validity against the draft4 json metaschema
    (I am converting locally to draft7 so as to allow: apt-get libjson-schema-modern-perl; json-schema-eval --strict --validate-schema schemas/v3.0/schema.json)
@karenetheridge karenetheridge added this to the v3.0.4 milestone Oct 3, 2024
@karenetheridge karenetheridge self-assigned this Oct 3, 2024
@handrews handrews added the Schema label Oct 4, 2024
@handrews
Copy link
Member

handrews commented Oct 4, 2024

There are definitely improvements to be made to the 3.0 schemas, but there aren't any schema-impacting differences between 3.0.3 and 3.0.4. The only version-ish thing that should change is the date in the $id of the schemas.

AFAIK, this is true across 3.0.0 - 3.0.4, and any schema applying to one applies to all and should only mention 3.0 in comments or other text (no patch release number). Some might make an argument regarding nullable in 3.0.0 – 3.0.2 va 3.0.3 – 3.0.4. However, the official position is that the clarifications to nullable in 3.0.3 were only clarifications (it made the relationship between nullable and type behave the same way as the relationship between draft-04 exclusiveMinimum and minimum (and exclusiveMaximum and maximum).

Schemas can be viewed on the spec site. I didn't think to comment on it in the 3.1 schema issue, but I'm pretty certain the spec should just link to this page and not to anything specific. (For those not familiar with the history of "latest" schemas, we should not have a "latest" schema symlink because refining the constraints to be more accurate could cause automated systems to suddenly invalidate previously-valid OADs which is not a nice thing to do – we tried this several ways with the JSON Schema meta-schemas before deciding on the date-based $ids to avoid ever changing a schema in place).

@karenetheridge
Copy link
Member Author

Note that the PR coming from this issue will be a blocker for 3.0.4. I have some of the more trivial fixes completed already, so please poke me if I should PR those now.

@handrews
Copy link
Member

@karenetheridge how will it be a blocker?

Logically, I agree that we should have the schemas done for the release, but we never have in the past and the current 3.0 schemas won't be any worse for 3.0.4 than they are for 3.0.3. So what would break so badly that we should consider it a blocker?

(If you want to argue that we should publish the schema fixes simultaneously with the patch release just on general principle, I'd support that, but I've never been successful with that argument here in the past).

@karenetheridge
Copy link
Member Author

I agree that we should have the schemas done for the release, but we never have in the past

I see; I wasn't aware of that.

If you want to argue that we should publish the schema fixes simultaneously with the patch release just on general principle

Yes, it was my assumption that this was the case. Otherwise how can tooling vendors proceed with adding support for the new release?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

2 participants