Gregsdennis/spec versioning #1596
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
gregsdennis
force-pushed
the
gregsdennis/spec-versioning
branch
from
161ebf1 to
39d784b
Compare
jdesrosiers
reviewed
Apr 12, 2025
|
|
||
| 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.
| @@ -88,16 +88,27 @@ specification. | |||
| ## Meta-Schema {#meta-schema} | |||
|
|
|||
| The current IRI for the default JSON Schema dialect meta-schema is | |||
| `https://json-schema.org/draft/next/schema`. For schema author convenience, this | |||
| meta-schema describes a dialect consisting of all keywords defined in this | |||
| `https://json-schema.org/1/2025`. This IRI encodes the specifications version | |||
There was a problem hiding this comment.
Suggested change
| `https://json-schema.org/1/2025`. This IRI encodes the specifications version | |
| `https://json-schema.org/1/2025`. This IRI encodes the specification's version |
Comment on lines
+91
to
+92
| `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".
Suggested change
| `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 |
| @@ -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.
| `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.
| @@ -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.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.