search

SchemaStore / schemastore

A collection of JSON schema files including full API
http://schemastore.org
Apache License 2.0
3.02k stars 1.65k forks source link

draft-04 is no longer the most broadly implemented draft #2427

Open handrews opened 2 years ago

handrews commented 2 years ago

Description of the feature / enhancement.

The contributing guidelines say:

Use the lowest possible schema draft needed, preferably Draft v4, to ensure interoperability with as many supported editors, IDEs and parsers as possible.

However, among actively maintained implementations (which is what the "modern" part of the filename below means), draft-04 comes in 3rd place (grepping the source for json-schema.org's implementations page):

bash % grep 'draft.*3' _data/validator-libraries-modern.yml | wc -l     7 
bash % grep 'draft.*4' _data/validator-libraries-modern.yml | wc -l    35
bash % grep 'draft.*6' _data/validator-libraries-modern.yml | wc -l    38
bash % grep 'draft.*7' _data/validator-libraries-modern.yml | wc -l    48
bash % grep 'draft.*19' _data/validator-libraries-modern.yml | wc -l   21
bash % grep 'draft.*20' _data/validator-libraries-modern.yml | wc -l   21

As for IDEs, that part of the implementations page is done in markdown so not as easy to grep, but after checking the various relevant projects to make sure things are up-to-date, we have:

Altova XMLSpy 2019r3 - 6, 7 appears to now support 2019-09 and 2020-12 Dashjoin JSON Schema editor - (not fully compliant with any draft, partial draft-06) Hackolade Studio - 4, 6, 7, 2019-09, 2020-12 JSONBuddy - 4, 6, 7, 2019-09 JSONEditor Online - 4, 6, 7 Liquid JSON Schema Editor - 4, 6, 7, 2019-09 Oxygen JSON Editor - 4, 6, 7 Stoplight Studio - 4, 6, 7 now supports OAS 3.1 so presumably JSON Schema 2020-12 Visual Studio Code - 4, 6, 7, 2019-09, 2020-12 WebStorm, IntelliJ IDEA, and other JetBrains IDEs - 4, 6, 7, 2020-12 support is being tracked Eclipse IDE - (seems to support JSON Schema through various plugins, and I can't figure out what is th emost common setup)

Discarding the editor that doesn't completely support anything, every implementation supports draft-07. Most but not all support draft-04. A few support 2020-12 or are working on it, but not as many as support draft-04.

So, across both categories, the most broadly implemented draft is now draft-07. A draft-07 schema will be usable with 37% more validators than draft-04, and with all of the listed editors that have clear support statements.

At what point can the contribution guidelines be updates to reflect this?

[NOTE: I couldn't figure out what to say about the PR question. I would be happy to make a PR for the README, as that would be trivial, but this is really a policy question for folks to decide, so of course I'm not going to submit a PR for an undecided point that might be rejected.]

Are you making a PR for this?

Yes, I will create a PR.

GerryFerdinandus commented 2 years ago

As of this year, Visual Studio 2022 (17.2) support draft-07.

So the description can be updated. in the (CONTRIBUTING.md and PULL_REQUEST_TEMPLATE.md) @madskristensen what do you think?

madskristensen commented 2 years ago

The majority of schemas use very basic features of JSON Schema and can therefore easily be expressed in Draft v4 which is the most widely supported version. However, all new editors/IDEs are catching up and Draft v7 is soon becoming a reasonable lowest common denominator. Perhaps we shouls update the guidance to say [...] preferably Draft v4 or v7.

jdesrosiers commented 2 years ago

I suspect that the recommendation to use draft-04 might be based on a misunderstanding that subsequent release are compatible with draft-04. This is not correct. An implementation that supports draft-07 can't be relied on to validate draft-04 schemas. I just wanted to mention that in case that is indeed taken into account as part of the recommendation to use draft-04.

jdesrosiers commented 2 years ago

Draft v4 which is the most widely supported version

Was the data analysis that @handrews presented unconvincing? It seems the data shows that draft-07 is the most widely supported. We are seeing a trend of validators dropping support for draft-04 (including AJV) and newer implementations never supporting it in the first place. Recently, I saw a request for a schema to be provided in a newer JSON Schema version because they couldn't find a quality implementation in their language that supported draft-04.

jdesrosiers commented 2 years ago

Perhaps the solution is for SchemaStore to allow content negotiation for the JSON Schema versions the requestor can handle and allow people to include more than one version of the schema. That way all bases are covered. You can even use AlterSchema to automatically convert between JSON Schema versions.

madskristensen commented 2 years ago

Visual Studio prior to a recent update only supported draft v4. Millions of users are still using earlier versions, though that is going to change over time. From the list above, it looks like only Altova XMLSpy doesn't support v4 and I doubt they have more users than Visual Studio.

handrews commented 2 years ago

@madskristensen "draft-04 or draft-07" would be an improvement in my book, and encourage folks to at least think about which is the broader support base for their intended audience.

Perhaps a more suitable approach (although a larger change) would be host schemas by draft/release (at some point the "draft" label will go away). @jdesrosiers mentioned AlterSchema, which could automate this. It would work something like the following:

Why do this?

The JSON Schema ecosystem is suffering from a circular problem. There are two parts of modernizing the ecosystem: ensuring support for more recent versions, and ensuring the availability of schemas that are written for those newer versions.

The implementation side has moved pretty solidly to draft-07, but anyone looking to take advantage of that who also depends on a site like schemastore that mostly only offers draft-04 is disincentivized to move forwards. Which leads to even more draft-04 lock-in, which is increasingly unsustainable as major implementations have started to move on and drop support. Many older draft-04 implementations are no longer maintained, and are being replaced by implementations in the same language that do not support draft-04 at all. This will only accelerate with OpenAPI 3.1 and 2020-12, although we're still a good ways off from that being a practical concern.

The JSON Schema ecosystem as a whole needs to find ways to move on to more recent versions that offer a lot more functionality and integration with newer technologies. We don't need or want to break things for people who are on older drafts for whatever reason, but there's enough support for later drafts that we really need content available that encourages using them.

madskristensen commented 2 years ago

We could offer a new subdomain for later versions. So instead of https://json.schemastore.org/schemafile it would be https://draft-07.schemastore.org/schemafile and https://2020-12.schemastore.org/schemafile etc. We can then use AlterSchema to generate the folders for each and potentially even use it to downgrade. What if we kept the current schema folder, but we generated version specific folders in a build step? That way IDEs can keep using the original URL, or choose a specific version.

@GerryFerdinandus what do you think?

GerryFerdinandus commented 2 years ago

So keep the same folder as present where all the different schema are placed in src/schemas/json/ Subdomain json link to this directory

Example: A new folder has been generated by AlterSchema from the directory src/schemas/json/ src/ReadOnlyAutoGenerated/07/ (subdomain draft-07) src/ReadOnlyAutoGenerated/2019/ (subdomain 2019-09) src/ReadOnlyAutoGenerated/2020/(subdomain 2020-12)

There is an issue that schemas already in draft 2020 cannot be downgraded to a lower version and thus are missing from the 07 and 2019 folder. (as going backwards is lossy) The catalog.json item needs to be extended with whatever version is available for this schema

"schema": {
        "draft-04": "https://draft-04.schemastore.org/schema.json",
        "draft-07": "https://draft-07.schemastore.org/schema.json",
        "2019-09": "https://2019-09.schemastore.org/schema.json"
        "2020-12": "https://2020-12.schemastore.org/schema.json"
 }

Optional draft-04 folder. Is just a copy of all draft-04 schemas from src/schemas/json/ src/ReadOnlyAutoGenerated/04/ (subdomain draft-04) But this one is needed to complete the catalog list

There is also a problem with $ref schemaA to schemaB. $id or $ref have a fixed URL to json.schemastore.org This should be updated if it's in the 2020 folder from json.schemastore.org to 2020-12.schemastore.org With search and replace function?

jdesrosiers commented 2 years ago

In case you aren't aware, It's possible to do content negotiation for a specific version or a range of versions using the application/schema+json media type. This would be more flexible for users and wouldn't require any change to the URLs you're already using to access schemas.

Examples:

User doesn't ask for anything specific. They will get back a schema in whatever version SchemaStore chooses.

GET https://schemastore.org/schema.json

Users asks for a JSON Schema, but no particular version. They will get back a schema in whatever version SchemaStore chooses.

GET https://schemastore.org/schema.json
Accept: application/schema+json

User specifically asks for a draft-07 schema. They will get a draft-07 schema or a 406 Not Acceptable response.

GET https://schemastore.org/schema.json
Accept: application/schema+json; schema="http://json-schema.org/draft-07/schema#"

User specifically asks for a draft-07 or 2020-12 schema with preference for 2020-12. They will get back a draft-07 or 2020-12 schema or a 406 Not Acceptable response.

GET https://schemastore.org/schema.json
Accept: application/schema+json; schema="http://json-schema.org/draft-07/schema#"; q=0.8, 
        application/schema+json; schema="https://json-schema.org/draft/2020-12/schema"; q=0.9
handrews commented 2 years ago

Optional draft-04 folder. Is just a copy of all draft-04 schemas from src/schemas/json/ src/ReadOnlyAutoGenerated/04/ (subdomain draft-04) But this one is needed to complete the catalog list

I think it would be good to have the draft-04 folder/subdomain (or content negotiation option) for consistency. It's less confusing to work with than the current mixed form (although of course holding on to that for compatibility makes sense).

There is an issue that schemas already in draft 2020 cannot be downgraded to a lower version and thus are missing from the 07 and 2019 folder. (as going backwards is lossy)

I think there aren't that many 2020 or 2019 schemas in the repo, so they could be manually backported, or perhaps some (as is currently the case) just aren't available on older drafts.

For example, creating an OAS 3.1 schema for draft-04 or draft-07 would be a huge amount of work because it relies heavily on unevaluatedProperties. And it would be likely to introduce errors given how much repetition-with-minor-variations would be involved. Since OAS 3.1 works with 2020-12, so there's an assumption that your tooling environment includes 2020-12 support.

But for a lot of other schemas, a good-enough manual backport should work if it's really needed.

There is also a problem with $ref schemaA to schemaB. $id or $ref have a fixed URL to json.schemastore.org This should be updated if it's in the 2020 folder from json.schemastore.org to 2020-12.schemastore.org With search and replace function?

That seems viable. AlterSchema has walkers that are used to implement the transforms. It might be easy to add an $id adjustment transform of some sort (paging @jviotti )