v6 validation: "contains"

[handrews]

Originally written by @geraintluff at https://github.com/json-schema/json-schema/wiki/contains-(v5-proposal)

Proposed keywords

• contains

We also might want an equivalent for objects (like containsProperty).

Purpose

Specifying that an array must contain at least one matching item is awkward. It can currently be done, but only using some inside-out syntax:

{
    "type": "array",
    "not": {
        "items": {
            "not": {... whatever ...}
        }
    }
}

This would replace it with the much neater:

{
    "type": "array",
    "contains": {... whatever ...}
}

It would also enable us to specify multiple schemas that must be matched by distinct items (which is currently not supported).

Values

The value of contains would be either a schema, or an array of schemas.

Validation

If the value of contains is a schema, then validation would only succeed if at least one of the items in the array matches the provided sub-schema.

If the value of contains is an array, then validation would only succeed if it is possible to map each sub-schema in contains to a distinct array item matching that sub-schema. Two sub-schemas in contains cannot be mapped to the same array index.

Example

Plain schema

{
    "type": "array",
    "contains": {
        "type": "string"
    }
}

Valid: ["foo"], [5, null, "foo"]
Invalid: [], [5, null]

Array of schemas

{
    "type": "array",
    "items": {"type": "object"},
    "contains": [
        {"required": ["propA"]},
        {"required": ["propB"]}
    ]
}

Valid:

• [{"propA": true}, {"propB": true}]
• [{"propA": true}, {"propA": true, "propB": true}]

Invalid:

• []
• [{"propA": true}] - no match for second entry
• [{"propA": true, "propB": true}] - entries in contains must describe different items

Concerns

Implementation

The plain-schema case is simple.

The array case is equivalent to Hall's Marriage Theorem. There are relatively efficient solutions for the general problem - but, I suspect a brute-force search will be surprisingly effective and efficient (due to the relatively small number of entries in contains).

It may or may not be worth warning schema authors about stuffing hundreds of entries into contains, because a naive implementation could easily end up having O(n³m) complexity.

Complexity of understanding (for humans)

Behaviour for the array for may be slightly complicated. For example:

{
    "type": "array",
    "contains": [
        {"enum": ["A", "B"]},
        {"enum": ["A", "B", "C"]},
        {"enum": ["A", "D"]},
    ]
}

In this case, ["A", "B", "C"] is valid.

However, this is not due to the syntax - it's simply a complex constraint.

[epoberezkin]

I think array syntax should not be part of the standard. What is the real life use case for it (that cannot be replaced with two contains)? The use case where we want different items match different schemas seems theoretic and can almost always be achieved by using schemas that won't match the same data, such as {type: 'string'} and {type: 'number'} for example.

[awwright]

I think the point with the array is two items from "contains" can't match the same item in the array, whereas with "allOf", it could.

But I'm not sure who in the world even needs this feature.

[Relequestual]

I would hold off till someone can come up with a concreet useful real life example. I'd be tempted to start tagging issues with "requires real life use case"... =]

[epoberezkin]

@awwright I understand the idea, the concern is exactly as @Relequestual writes - it is theoretic. Even when in cases when you want 2 items you can achieve it by using exclusive schemas (as in my simple example) in allOf rather than allowing for generic requirement where any implementation would have a high performance cost.

[handrews]

Does anyone want to advocate for even the one-schema version of this feature? If not I will close it based on @awwright 's "if you don't want to champion it, you shouldn't have migrated it" principle.

[epoberezkin]

@handrews I think that single item version can be useful for heterogenous arrays, that are useful in some cases (e.g. UI description should be an array).

Although in many cases you can get away with positional items (where you can use items keyword with array value), there are cases where you would not be able to, especially where you would use validation not for simply valid/invalid use case but as a predicate for some other decisions (which seems to be quite common by the way).

So I'd like to see this feature in the standard. Not with multiple schema values though.

[handrews]

@epoberezkin that works for me. I can see the use for the single-item version.

The only thing that the multiple-item version does that you couldn't do with an "allOf" is ensure that each item matches a distinct element of the array, and I find that condition a little weird to begin with.

[handrews]

OK, single 'contains' is in! The consensus was arrays should not be added. If we come up with a real use case for it, we can file that again on its own.