Gregsdennis/spec versioning #1596
Conversation
gregsdennis
force-pushed
the
gregsdennis/spec-versioning
branch
from
161ebf1 to
39d784b
Compare
| `https://json-schema.org/1/2025`. This IRI encodes the specifications version | ||
| and release year. Because all schemas written to conform to a given version are | ||
| guaranteed to be compatible with later releases within the same iteration, the | ||
| meta-schema IRI `https://json-schema.org/1` is also recognized to represent the |
There was a problem hiding this comment.
- 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.
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.
| @@ -2188,7 +2195,7 @@ and only allows the "data" and "children" properties. An example instance with | |||
|
|
|||
| ```jsonschema "Tree schema, extensible" | |||
| { | |||
| "$schema": "https://json-schema.org/draft/next/schema", | |||
| "$schema": "https://json-schema.org/1/2025", | |||
There was a problem hiding this comment.
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.
The compatibility guarantee stated here necessitates that the version be first.
There was a problem hiding this comment.
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.)
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.
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.
Ultimately, we landed on a simple "version" number (indicates a sort of compatibility grouping) and a release year. 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. |
gregsdennis
force-pushed
the
gregsdennis/spec-versioning
branch
from
994d860 to
4a5da5f
Compare
gregsdennis
dismissed
karenetheridge’s stale review
The approach is good. If it needs clarity, we can address that in a follow-up PR.
github-project-automation
bot
moved this from In Progress
to Done
in Stable Release Development
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.