Gregsdennis/spec versioning #1596
Conversation
gregsdennis
force-pushed
the
gregsdennis/spec-versioning
branch
from
161ebf1 to
39d784b
Compare
specs/jsonschema-core.md
Outdated
|
|
||
| This specification is versioned by two values: iteration and release year. | ||
|
|
||
| A schema written to conform with the requirements of a given version (iteration and release year) is compatible with specifications published with the same iteration value and either the same or greater release year value. Thus, JSON Schema provides a guarantee of compatibility for future releases within an iteration. |
There was a problem hiding this comment.
Is the linter not working? It should have flagged this line as too long.
There was a problem hiding this comment.
Hm.. maybe. I'll update it.
specs/jsonschema-validation.md
Outdated
| `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 |
There was a problem hiding this comment.
I feel like there's some ambiguity here. You've defined the "version" as the iteration + release year. But, here you're calling the iteration "specification version".
| `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 | |
| `https://json-schema.org/1/2025`. This IRI encodes the specifications iteration | |
| and release year. Because all schemas written to conform to a given version are |
specs/jsonschema-core.md
Outdated
| @@ -415,6 +415,12 @@ keywords MUST NOT begin with this prefix. | |||
| Implementations MUST refuse to evaluate schemas which contain keywords which | |||
| they do not know how to process or explicitly choose not to process. | |||
|
|
|||
| ## Specification Versioning and Compatibility | |||
|
|
|||
| This specification is versioned by two values: iteration and release year. | |||
There was a problem hiding this comment.
The term "iteration" doesn't feel right to me. It's not very intuitive and it's never defined what it means.
There was a problem hiding this comment.
I had "iteration" at first because I wanted to avoid "version" since it seems it be such an overused term. But rereading it a few days ago, it didn't feel right. I thought I got all of them.
| `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 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. |
Co-authored-by: Jason Desrosiers <jdesrosi@gmail.com>
| This specification is identified collectively by two values: version and release | ||
| year. | ||
|
|
||
| A schema written to conform with the requirements of a given version is |
There was a problem hiding this comment.
| A schema written to conform with the requirements of a given version is | |
| A schema written to conform with the requirements of a given release is |
There was a problem hiding this comment.
I think this could go either way. Is there a compelling reason you think it should be "release"?
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.