Skip to content

stop using the term "draft" to mean "version", and fix the remaining mentions of draft-next (now v1) #791

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 1 commit into from
Nov 4, 2025
Merged

stop using the term "draft" to mean "version", and fix the remaining mentions of draft-next (now v1) #791

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
23 changes: 11 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@ The recommended workflow of this test suite is to clone the `main` branch of thi

## Coverage

All JSON Schema specification releases should be well covered by this suite, including drafts 2020-12, 2019-09, 07, 06, 04 and 03.
Drafts 04 and 03 are considered "frozen" in that less effort is put in to backport new tests to these versions.
All JSON Schema specification releases should be well covered by this suite, including versions draft-2020-12, draft-2019-09, draft-07, draft-06, draft-04 and draft-03.
Versions draft-04 and draft-03 are considered "frozen" in that less effort is put in to backport new tests to these versions.

Additional coverage is always welcome, particularly for bugs encountered in real-world implementations.
If you see anything missing or incorrect, please feel free to [file an issue](https://github.com/json-schema-org/JSON-Schema-Test-Suite/issues) or [submit a PR](https://github.com/json-schema-org/JSON-Schema-Test-Suite).
Expand All @@ -31,14 +31,13 @@ Inside that directory is a subdirectory for each released version of the specifi

The structure and contents of each file in these directories is described below.

In addition to the version-specific subdirectories, two additional directories are present:
In addition to the version-specific subdirectories, one additional directory is present:

1. `draft-next/`: containing tests for the next version of the specification whilst it is in development
2. `latest/`: a symbolic link which points to the directory which is the most recent release (which may be useful for implementations providing specific entry points for validating against the latest version of the specification)
1. `latest/`: a symbolic link which points to the directory which is the most recent release (which may be useful for implementations providing specific entry points for validating against the latest version of the specification)

Inside each version directory there are a number of `.json` files each containing a collection of related tests.
Often the grouping is by property under test, but not always.
In addition to the `.json` files, each version directory contains one or more special subdirectories whose purpose is [described below](#subdirectories-within-each-draft), and which contain additional `.json` files.
In addition to the `.json` files, each version directory contains one or more special subdirectories whose purpose is [described below](#subdirectories-within-each-version-directory), and which contain additional `.json` files.

Each `.json` file consists of a single JSON array of test cases.

Expand Down Expand Up @@ -78,9 +77,9 @@ Here is a single *test case*, containing one or more tests:
}
```

### Subdirectories Within Each Draft
### Subdirectories Within Each Version directory

There is currently only one additional subdirectory that may exist within each draft test directory.
There is currently only one additional subdirectory that may exist within each specification version test directory.

This is:

Expand All @@ -107,8 +106,8 @@ The precise steps described do not need to be followed exactly, but the results

To test a specific version:

* For 2019-09 and later published drafts, implementations that are able to detect the draft of each schema via `$schema` SHOULD be configured to do so
* For draft-07 and earlier, draft-next, and implementations unable to detect via `$schema`, implementations MUST be configured to expect the draft matching the test directory name
* For 2019-09 and later published versions, implementations that are able to detect the version of each schema via `$schema` SHOULD be configured to do so
* For draft-07 and earlier, v1 (not yet released), and implementations unable to detect via `$schema`, implementations MUST be configured to expect the version matching the test directory name
Copy link
Member

@jdesrosiers jdesrosiers Nov 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure why draft-next was included in this bullet. That doesn't seem correct to me and I don't think it's correct for v1 either.

Suggested change
* For draft-07 and earlier, v1 (not yet released), and implementations unable to detect via `$schema`, implementations MUST be configured to expect the version matching the test directory name
* For draft-07 and earlier, and implementations unable to detect via `$schema`, implementations MUST be configured to expect the version matching the test directory name

Copy link
Member Author

@karenetheridge karenetheridge Nov 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm going to leave this for now, as it's still not clear to me (nor is it in the latest version of the spec documents in json-schema-spec main branch) whether the name of the draft is actually intended to be "v1" or "v1/<year>" and how $schema keywords would refer to it.

As far as the test suite is concerned, as long as everything consistently refers to "v1" then test harnesses or implementations can just skip this directory entirely for now, as they would have done for "draft-next".

* Load any remote references [described below](#additional-assumptions) and configure your implementation to retrieve them via their URIs
* Walk the filesystem tree for that version's subdirectory and for each `.json` file found:

Expand All @@ -135,7 +134,7 @@ If your implementation supports multiple versions, run the above procedure for e

### Additional Assumptions

1. The suite, notably in its `refRemote.json` file in each draft, expects a number of remote references to be configured.
1. The suite, notably in its `refRemote.json` file in each specification version directory, expects a number of remote references to be configured.
These are JSON documents, identified by URI, which are used by the suite to test the behavior of the `$ref` keyword (and related keywords).
Depending on your implementation, you may configure how to "register" these *either*:

Expand All @@ -158,7 +157,7 @@ If your implementation supports multiple versions, run the above procedure for e
}
```
2. Test cases found within [special subdirectories](#subdirectories-within-each-draft) may require additional configuration to run.
2. Test cases found within [special subdirectories](#subdirectories-within-each-version-directory) may require additional configuration to run.
In particular, when running tests within the `optional/format` subdirectory, test runners should configure implementations to enable format validation, where the implementation supports it.
### Invariants & Guarantees
Expand Down
6 changes: 3 additions & 3 deletions output-tests/draft-next/content/general.json → output-tests/v1/content/general.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
"description": "failed validation produces no annotations",
"schema": {
"$schema": "https://json-schema.org/draft/next/schema",
"$id": "https://json-schema.org/tests/content/draft-next/general/0",
"$id": "https://json-schema.org/tests/content/v1/general/0",
"type": "string",
"readOnly": true
},
Expand All @@ -13,14 +13,14 @@
"data": 1,
"output": {
"list": {
"$id": "https://json-schema.org/tests/content/draft-next/general/0/tests/0/basic",
"$id": "https://json-schema.org/tests/content/v1/general/0/tests/0/basic",
"$ref": "/draft/next/output/schema",
"properties": {
"details": {
"contains": {
"properties": {
"evaluationPath": {"const": ""},
"schemaLocation": {"const": "https://json-schema.org/tests/content/draft-next/general/0#"},
"schemaLocation": {"const": "https://json-schema.org/tests/content/v1/general/0#"},
"instanceLocation": {"const": ""},
"annotations": false,
"droppedAnnotations": {
Expand Down
6 changes: 3 additions & 3 deletions ...ut-tests/draft-next/content/readOnly.json → output-tests/v1/content/readOnly.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
"description": "readOnly generates its value as an annotation",
"schema": {
"$schema": "https://json-schema.org/draft/next/schema",
"$id": "https://json-schema.org/tests/content/draft-next/readOnly/0",
"$id": "https://json-schema.org/tests/content/v1/readOnly/0",
"readOnly": true
},
"tests": [
Expand All @@ -12,14 +12,14 @@
"data": 1,
"output": {
"list": {
"$id": "https://json-schema.org/tests/content/draft-next/readOnly/0/tests/0/basic",
"$id": "https://json-schema.org/tests/content/v1/readOnly/0/tests/0/basic",
"$ref": "/draft/next/output/schema",
"properties": {
"details": {
"contains": {
"properties": {
"evaluationPath": {"const": ""},
"schemaLocation": {"const": "https://json-schema.org/tests/content/draft-next/readOnly/0#"},
"schemaLocation": {"const": "https://json-schema.org/tests/content/v1/readOnly/0#"},
"instanceLocation": {"const": ""},
"annotations": {
"properties": {
Expand Down
6 changes: 3 additions & 3 deletions output-tests/draft-next/content/type.json → output-tests/v1/content/type.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
"description": "incorrect type",
"schema": {
"$schema": "https://json-schema.org/draft/next/schema",
"$id": "https://json-schema.org/tests/content/draft-next/type/0",
"$id": "https://json-schema.org/tests/content/v1/type/0",
"type": "string"
},
"tests": [
Expand All @@ -12,14 +12,14 @@
"data": 1,
"output": {
"list": {
"$id": "https://json-schema.org/tests/content/draft-next/type/0/tests/0/basic",
"$id": "https://json-schema.org/tests/content/v1/type/0/tests/0/basic",
"$ref": "/draft/next/output/schema",
"properties": {
"details": {
"contains": {
"properties": {
"evaluationPath": {"const": ""},
"schemaLocation": {"const": "https://json-schema.org/tests/content/draft-next/type/0#"},
"schemaLocation": {"const": "https://json-schema.org/tests/content/v1/type/0#"},
"instanceLocation": {"const": ""},
"annotations": false,
"errors": {
Expand Down
0 output-tests/draft-next/output-schema.json → output-tests/v1/output-schema.json
View file
Open in desktop
File renamed without changes.
8 changes: 4 additions & 4 deletions tests/v1/optional/unknownKeyword.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,21 +9,21 @@
"not": {
"array_of_schemas": [
{
"$id": "https://localhost:1234/draft-next/unknownKeyword/my_identifier.json",
"$id": "https://localhost:1234/v1/unknownKeyword/my_identifier.json",
"type": "null"
}
]
}
},
"real_id_in_schema": {
"$id": "https://localhost:1234/draft-next/unknownKeyword/my_identifier.json",
"$id": "https://localhost:1234/v1/unknownKeyword/my_identifier.json",
"type": "string"
},
"id_in_unknown1": {
"not": {
"object_of_schemas": {
"foo": {
"$id": "https://localhost:1234/draft-next/unknownKeyword/my_identifier.json",
"$id": "https://localhost:1234/v1/unknownKeyword/my_identifier.json",
"type": "integer"
}
}
Expand All @@ -33,7 +33,7 @@
"anyOf": [
{ "$ref": "#/$defs/id_in_unknown0" },
{ "$ref": "#/$defs/id_in_unknown1" },
{ "$ref": "https://localhost:1234/draft-next/unknownKeyword/my_identifier.json" }
{ "$ref": "https://localhost:1234/v1/unknownKeyword/my_identifier.json" }
]
},
"tests": [
Expand Down
Loading