-
-
Notifications
You must be signed in to change notification settings - Fork 351
Gregsdennis/spec versioning #1596
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
Conversation
161ebf1 to
39d784b
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not sold on this idea at all. What other ideas were considered? Is there a discussion that I missed?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- what is "indicated iteration"?
- using a URI that can change meaning depending on the current state of the spec feels really dodgy to me -- just like "https://json-schema.org/latest" would be, because the mapping of this value can change at any time, unexpectedly, which can be disruptive to both schema authors and implementation authors.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
using a URI that can change meaning depending on the current state of the spec feels really dodgy to me -- just like "https://json-schema.org/latest" would be, because the mapping of this value can change at any time, unexpectedly, which can be disruptive to both schema authors and implementation authors.
That's why we stated the compatibility guarantee. Any https://json-schema.org/1/x schema is compatible with all https://json-schema.org/1/x+i specifications. As long as the version (1 in this case) is the same, that compatibility guarantee holds. Because of this, it's safe to have https://json-schema.org/1 as a $schema value. Future releases within the same version will not break schemas.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Putting the iteration before the year is not going to sort very well, and I imagine it could easily be confused with a date.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The compatibility guarantee stated here necessitates that the version be first.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It actually does sort well. Both values are only ever going to increase.
1/2025
1/2026
1/2027
2/2028
2/2029
3/2030
(Hopefully we maintain compatibility better than that, but you get the point.)
I'm not sold on this idea at all. What other ideas were considered? Is there a discussion that I missed? - @karenetheridge
There is the issue linked at the top of this PR as well as this discussion thread (the rest of the discussion is worth reading as well). We also have our PROCESS.md file.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I find this representation of the version to be really confusing. It's not at all clear to me what the next version after "1/2025" would be. Is the version intended to be "1" and "2025" a subversion? or is the full version "1/2025"? What combinations of numbers are intended to be grouped into one family and which are to be compatible with each other?
Whatever we go with should be intuitive to observers without having to read the spec, and I don't think we have that with the current proposal.
@karenetheridge the discussion about this format has been open for quite a long time.
- Spec Update: Specify how the stable URI works #1421
- https://github.com/orgs/json-schema-org/discussions/438
- https://github.com/orgs/json-schema-org/discussions/671#discussioncomment-8753266
Ultimately, we landed on a simple "version" number (indicates a sort of compatibility grouping) and a release year. /1 (the latest of version 1), /1/2025 (version 1, released in 2025), /1/2026 (version 1, released in 2026) all carry the same compatibility.
This communicates that the 2026 release retains full compatibility with the 2025 release. If you write a schema to the 2025 release, you can safely use an implementation that supports any version 1 released in 2025 or after. If you write a schema that requires 2026 features, then, yeah, you can't use an implementation that only supports up to 2025, but you could use an implementation that supports 2027 or 2035 or whatever as long as the version number remains the same.
If (God forbid) we have to change something in a way that breaks compatibility with the previous release, then we increment the version number. We make every effort to prevent this, but we can't guarantee it.
In essence, it's exactly the same as with the drafts except that we're adding a compatibility indicator to the URI so that there's a safe way to use "latest".
At this point, given how long this discussion has been open for input, I'm not really interested in changing this approach. If it's inadequately described, I'm open to input on how to help increase clarity.
Co-authored-by: Jason Desrosiers <jdesrosi@gmail.com>
994d860 to
4a5da5f
Compare
The approach is good. If it needs clarity, we can address that in a follow-up PR.
What kind of change does this PR introduce?
clarification
Issue & Discussion References
Summary
Update meta-schema IRIs and provide some explanation of the path meaning. Probably could use a bit more explanation, but would like to get others' opinions.
Does this PR introduce a breaking change?
No? Maybe? I'm not sure how this applies since it's a necessary change.