Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up
Appearance settings

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

Merged
jdesrosiers merged 5 commits into main from gregsdennis/spec-versioning
May 18, 2025
Merged

Gregsdennis/spec versioning #1596

jdesrosiers merged 5 commits into main from gregsdennis/spec-versioning
May 18, 2025

Conversation

Copy link
Member

@gregsdennis gregsdennis commented Apr 12, 2025

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.

Copy link
Member

@karenetheridge karenetheridge left a 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?

`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
Copy link
Member

@karenetheridge karenetheridge Apr 13, 2025

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.

Copy link
Member Author

@gregsdennis gregsdennis Apr 16, 2025

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.

@@ -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",
Copy link
Member

@karenetheridge karenetheridge Apr 13, 2025

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.

Copy link
Member Author

@gregsdennis gregsdennis Apr 16, 2025

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.

jdesrosiers reacted with thumbs up emoji
Copy link
Member Author

@gregsdennis gregsdennis May 14, 2025

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.)

Copy link
Member Author

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.

Copy link
Member

@karenetheridge karenetheridge left a 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.

Copy link
Member Author

gregsdennis commented May 14, 2025
edited
Loading

@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. /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.

@gregsdennis gregsdennis force-pushed the gregsdennis/spec-versioning branch from 994d860 to 4a5da5f Compare May 16, 2025 21:52
@gregsdennis gregsdennis dismissed karenetheridge’s stale review May 16, 2025 21:54

The approach is good. If it needs clarity, we can address that in a follow-up PR.

@jdesrosiers jdesrosiers merged commit 298aa14 into main May 18, 2025
12 checks passed
@jdesrosiers jdesrosiers deleted the gregsdennis/spec-versioning branch May 18, 2025 20:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@jdesrosiers jdesrosiers jdesrosiers approved these changes

@karenetheridge karenetheridge karenetheridge left review comments

Assignees
No one assigned
Projects
Development

Successfully merging this pull request may close these issues.

Spec Update: Specify how the stable URI works

AltStyle によって変換されたページ (->オリジナル) /