Supporting newer drafts

[DannyvdSluijs]

I guess we are running behind on supporting the newest/newer drafts. And now seems to be the time. As I've replied in #395 what could help at this point in time is:

• Proof of Concept PR: Draft a PR that adds context of which draft version is being validated
• Research: How would validating work if we reference an schema that uses a different version draft, should we switch the draft version (and switch back when leaving the schema) or keep the current schema. I'm clueless on this.
• Prepare newer constraints: New draft versions have new constraints some of which dont have a constraint class in code yet. Providing implementation for those could help. Perhaps peeking at other implementation on how this has been done could be a good start?
• Discuss: Participate in the discussion and provide insights, knowledge and/or learnings

[dafeder]

The other major PHP implementation, Opis, only supports down to draft-06. But it does support a few different drafts that are more recent, @handrews do you know are 06 and later backwards compatible or do they have breaking changes too?

This python implementation does support from 03 up to 2020-12, will try to take a closer look at the logic soon.

[handrews]

@dafeder draft-07 is strictly backwards compatible with draft-06, and is far more widely used. It is probably the most common draft at this point. Draft-07 is used in AsyncAPI and the W3C's Web of Things work, among other places.

Drafts 2019-09 and 2020-12 are not backwards compatible. Of the two, 2020-12 is far more broadly used, as (despite the 2 year gap) it came out before 2019-09 was widely adopted. 2020-12 is also part OpenAPI 3.1 (and higher, once we get 3.2 out the door later this year- I mostly work on OpenAPI rather than JSON Schema these days).

[DannyvdSluijs]

Did some research on the topic and made some notes along the way. Writing them down here for future references.

Checking Opis Json Schema I can see they:

• Use the $schema property if available and matching the supported schema, see here
• Use a fallback to default a default draft, see here
• The default can be configured using the setDefaultDraftVersion() method, see here
• When no default has been configured an ultimate fallback is made to the SchemaParser::DEFAULT_DRAFT (2020-12) which is the latest supported schema
• All of the above happens in de the scope of a method called parseRootSchema()

Noticeable is that Opis Json Schema uses logic to parse schema into objects. This is something we don't have.
The default version could be something we can take from the factory

With regards to the $schema in references, in the JSON Schema documentation it if mentioned:

$schema applies to the entire document and must be at the root level. It does not apply to externally referenced ($ref, $dynamicRef) documents. Those schemas need to declare their own $schema.

Checking with ChatGPT (4o mini) it made some recommendations:

• Standardize on one draft for all your schemas (main and references).
• If you must mix, use a validator with true multi‐dialect support and ensure each file declares its own $schema.
• Test your tooling: try validation with schemas in isolation and together to catch silent keyword‐ignoring.

It also mentioned AJV:

Validators that support multiple drafts (for example Ajv’s 2019/2020‐12 build or by loading additional meta‐schemas via ajv.addMetaSchema(...)) can isolate each document’s dialect correctly. If you only load one meta‐schema, every referenced document is validated as if it were written against that single draft.