[JSON Validator] Tuple validation, multi-type enum checks

[ashfame]

This PR addresses two related bugs in the schema validator that caused it to throw fatal errors (UnsupportedSchemaException or a TypeError) when it should have gracefully returned a ValidationError.

The Problem

The validator would crash when attempting to validate data against a schema that used either of the following valid JSON Schema constructs:

1. Tuple Validation: When an array's items keyword was an array of schemas (e.g., {"type": "array", "items": [{"type": "string"}, {"type": "object"}]}), the validator would throw an UnsupportedSchemaException instead of validating the data.
2. Multi-type Enums: When a schema used an array for the type keyword along with an enum (e.g., {"type": ["string", "number"]}), the validator's internal integrity check would cause a fatal TypeError.

This meant that schemas that are perfectly valid according to the JSON Schema spec were not supported and would break the validation process entirely.

Root Cause Analysis

1. The validate_array() method was only implemented to handle "list validation" (where items is a single schema object). It lacked the logic to handle "tuple validation," causing it to misinterpret the array of schemas and throw an exception.
2. The schema integrity check inside validate_type() was incorrectly calling type_matches()—which only accepts a string for the type—instead of the type_matches_any() method, which is designed to handle an array of types.

The Solution

This PR implements two fixes to make the validator more compliant with the JSON Schema spec:

1. Added Tuple Validation Logic: The validate_array() method now detects when the items keyword is an array (a tuple) and applies the correct validation logic, iterating through the data and schema arrays in lockstep.
2. Corrected the Enum Integrity Check: The check in validate_type() has been updated to use the type_matches_any() method, allowing it to correctly validate schemas that use multiple types.

How to Verify

I have added a new unit test, testItReturnsValidationErrorForInvalidTupleData(), which uses a schema with tuple validation.

• Before this fix: Running this test causes the validator to throw a fatal UnsupportedSchemaException.
• After this fix: The test now passes, as the validator correctly identifies the invalid data and returns a ValidationError object as expected.

[ashfame]

@adamziel I purposefully pushed the failing test first so that you can see the exact test I added failing in CI. Second commit adds the fix, which makes all tests pass again (except 1 that's stuck in setting up PHP in CI).

[adamziel]

looks like a good candidate for array_is_list polyfill (not a blocker here)

[adamziel]

I'm still a bit confused about this logic. It's, effectively:

$is_tuple_validation =   array_is_list( $schema['items'] );
$is_list_validation  = ! array_is_list( $schema['items'] );

Which reads like a contradiction. Also, a "list of schemas (tuple validation)" vs "single schema object (list validation)" confuses me, too. Can we find clearer terms to describe it?

I've looked it up in the JSON schema spec and perhaps this quote would help:

* List validation: a sequence of arbitrary length where each item matches the same schema
* Tuple validation: a sequence of fixed length where each item may have a different schema. In this usage, the index (or location) of each item is meaningful as to how the value is interpreted. (This usage is often given a whole separate type in some programming languages, such as Python's tuple).

Although it tells me that array_is_list() is not the right check here, since we need to confirm we have a specific number of items, each defining a separate schema. It seems like this check needs to be more involved than it is now.

[ashfame]

@adamziel Thanks for the sharp & helpful feedback! I pushed another commit in hopes of making it more readable. Since "list" and "tuple" is how JSON schema spec defined it, I renamed the flag vars to is_tuple_schema after added a detailed explanation in the comments.

I have added a second check inside the tuple validation loop to make it a two-layered approach (first checking the schema's intent, then its integrity) which should fully address the concerns you raised. If I misunderstood, please let me know.

I have added some tuple related to test cases to the data provider of testArrayValidation.

[ashfame]

And better polyfills available on array_is_list() page. Top voted note has the best one.

Do you want that one added to components/Polyfill/php-functions.php and used here instead?

[adamziel]

@ashfame up to you, it doesn't seem like a big deal and maybe it's for the best that the validator doesn't have an implicit dependency on polyfills 🤔

[adamziel]

LLMs telltale sign: marking a code branch as "existing logic". Once we merge this PR, both branches become existing logic and that comment no longer makes sense. How about:

Suggested change

	// === LIST VALIDATION (existing logic) ===
	// List validation

[ashfame]

Very true!

[adamziel]

Suggested change

	// === TUPLE VALIDATION ===
	// Tuple validation

[adamziel]

It would be cool to support it eventually. Not a blocker here

[adamziel]

Thank you @ashfame!