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

[dafeder]

Thanks @handrews I meant is 06 or 07 compatible with 04 for instance. Would a strictly conforming draft-04 schema validate using draft-07 rules?

[handrews]

@dafeder Ah, my apologies. No, draft-06 is not compatible with draft-04. It's been a while since I thought about that exactly, but off the top of my head id became $id and exclusiveMaximum and exclusiveMinimum became independent numeric keywords instead of being boolean modifiers on adjacent maximum and minimum keywords. There's probably something else.. there used to be release notes on the json schema site, you might check there (I'm no longer active with the project, although happy to answer questions up through draft 2020-12).

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

[dafeder]

I think resolving the draft version should be pretty doable, but the question I have is more what do you do with it... and how strict are you. In this library, it looks like it validates 03 and 04 with the same rules, for the most part, just has logic to account for using properties as specified in either draft. Would we simply continue to use that "loose" approach?

For instance, if someone uses a const property in a schema supposedly implementing draft-04, do we just accept it? Do we accept exclusiveMaximum as either a bool or a number no matter what draft we're using?

If not, how are constraint differences between drafts managed throughout the different validations in the codebase? That's what I was looking for in OPIs but tbh I'm having trouble understanding a lot of the code.

[handrews]

@dafeder I'm surprised the same logic is used for draft-03 and draft-04 as they are very different. required and type in particular are different (although all draft-04 type values work in draft-03, but not the other way around).

The specifications state that any keyword not known to the draft SHOULD be ignored (in later drafts, SHOULD be collected as an annotation, but that's not relevant for draft-07 or earlier).

To be compliant and interoperable, these are the recommendations you'd need to follow. You can offer options to support other keywords from future drafts as extensions, but that shouldn't be the default behavior. For one thing, someone might have used that keyword name as an extension in a way that is incompatible with how the later draft defined it.

[DannyvdSluijs]

I've been given this some thoughts over time trying to see how we could fit in the different drafts that are out there. As well as be more strict on current drafts. This has led me to the path of different constraints.

Currently we use the UndefinedConstraint as our primary way for validation. This constraints goes through the supplied data and schema and adheres to both draft 3 and 4. I would like to explore if we could create constraints for each draft which should be able to handle the high level stuff (which can be specific to the draft, such as supported keywords and how to deal with unknown keywords) and the lower logic (type checking, enum const etc could be dispatched to the already existing constraints.
If needed the could be draft aware to handle small differences between drafts or could even be draft specific constraint implementations if the logic becomes so different.

This would allow the library to behave as is with the UndefinedConstraint and for people who prefer a more strict validation an opt-in to use draft specific constraints would be the preferred way.

Love to hear thoughts, critiques or agreements before going down a rabbit hole and only after emerging seeing the solution would not be the right one.