Skip to content

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.

Sign up for GitHub

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
merged 5 commits into from
May 18, 2025
Merged

Gregsdennis/spec versioning #1596

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4412afc
dollar sign has markdown significance
gregsdennis Mar 4, 2025
599449e
pushing to back up
gregsdennis Mar 8, 2025
784b179
update other meta-schema iris
gregsdennis Apr 12, 2025
f057ff4
Update specs/jsonschema-validation.md
gregsdennis Apr 16, 2025
4a5da5f
replace 'iteration' language
gregsdennis Apr 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 19 additions & 8 deletions specs/jsonschema-core.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -427,6 +427,16 @@ 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 identified collectively by two values: version and release
year.

A schema written to conform with the requirements of a given version is
compatible with successive specifications, which are published with the same
version and either the same or greater release year value. Thus, JSON Schema
provides a guarantee of compatibility for future releases within a version.

## Keyword Behaviors {#keyword-behaviors}

JSON Schema keywords may exhibit one or more behaviors. This specification
Expand Down Expand Up @@ -873,16 +883,17 @@ default to using the current location if a default is desireable.

## The JSON Schema Core Keywords {#core}

Keywords declared in this section, which all begin with "$", are essential to
processing JSON Schema. These keywords inform implementations how to process any
schema or meta-schema, including those split across multiple documents, or exist
to reserve keywords for purposes that require guaranteed interoperability.
Keywords declared in this section, which all begin with a dollar sign (`$`), are
essential to processing JSON Schema. These keywords inform implementations how
to process any schema or meta-schema, including those split across multiple
documents, or exist to reserve keywords for purposes that require guaranteed
interoperability.

Support for these keywords MUST be considered mandatory at all times as they are
necessary to navigate and process any schema.

The "$" prefix is reserved for use by this specification. Extensions MUST NOT
define new keywords that begin with "$".
The `$` prefix is reserved for use by this specification. Extensions MUST NOT
define new keywords that begin with `$`.

### Meta-Schemas

Expand Down Expand Up @@ -2243,7 +2254,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

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

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.

Copy link
Member Author

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

"$id": "https://example.com/tree",
"$dynamicAnchor": "node",

Expand All @@ -2262,7 +2273,7 @@ and only allows the "data" and "children" properties. An example instance with

```jsonschema "Strict-tree schema, guards against misspelled properties"
{
"$schema": "https://json-schema.org/draft/next/schema",
"$schema": "https://json-schema.org/1/2025",
"$id": "https://example.com/strict-tree",
"$dynamicAnchor": "node",

Expand Down
23 changes: 17 additions & 6 deletions specs/jsonschema-validation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,16 +103,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 specification's 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 version, the
meta-schema IRI `https://json-schema.org/1` is also recognized to represent the
Copy link
Member

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

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.

latest release within the indicated version.

The meta-schema describes a dialect consisting of all keywords defined in this
specification and the JSON Schema Core specification. Certain keywords specify
some functionality which is optional to support and is explained in detail in
the relevant sections.

Updated meta-schema IRIs MAY be published between specification drafts in order
to correct errors. Implementations SHOULD consider IRIs dated after this
specification draft and before the next to indicate the same syntax and
semantics as those listed here.
Where the meta-schema conflicts with either this specification or the JSON
Schema Core specification, the specifications take precedence, and the
meta-schema is to be considered in error. The meta-schema may be occasionally
updated to correct any such errors.

Although the IRI for the default JSON Schema dialect meta-schema is also a valid
URL, implementations MUST NOT assume that a document is provided at this
location. Rather than performing a network request to retrieve the meta-schema,
implementations SHOULD include a copy of the meta-schema and MAY encode it as
required by the language or framework used by the implementation.

## Keywords for Structural Validation

Expand Down