Object-based contains

[gregsdennis]

Inspired by this SO question.

We have contains to verify that at least one item in an array matches a subschema. And through additionalProperties and patternProperties we recognize that objects can have dynamic properties.

It seems like we should have a way to specify that at least one property matches a subschema.

It could make sense to extend contains to do this when it receives an object, or we could define a new keyword. If we extend contains, then minContains and maxContains would naturally follow. format (in all its glory) already works on multiple value types, so it's not something we haven't had before.

[jdesrosiers]

I'm sure this has come up before, but I did a search in the vocabularies repo and didn't find anything.

I should point out that there is a way to express object-contains-at-least-one without a new keyword. It would be sugar for,

{
  "not": {
    "additionalProperties": {
      "not": { ... schema ... }
  }
}

Just like this is sugar for array-contains-at-least-one (aka: contains),

{
  "not": {
    "items": {
      "not": { ... schema ... }
  }
}

There is no workaround for minContains/maxContains for arrays or objects.

I wouldn't be opposed to adding a keyword or extending the scope of contains to cover objects.

This has come up twice in the last week and I vaguely remember seeing a similar issue not long ago as well. This indicates that there is need for something like this. While there is a workaround, unless they're a JSON Schema expert they're unlikely to figure it out on their own. I also feel like it fits a hole in JSON Schema, if we support a contains operation on arrays, why not objects.

Generally, I don't like the idea of having a keyword that does more than one thing, but the semantics of contains for array and object really are the same, so I wouldn't be opposed.

[gregsdennis]

{
  "not": {
    "additionalProperties": {
      "not": { ... schema ... }
  }
}

I don't follow how this (or the array one) works like contains.

[jdesrosiers]

@gregsdennis Let's look at the array one first because I think it's a little easier to follow.

{
  "items": {
    "not": { "required": ["foo"] }
  }
}

This schema asserts that none of the items in the array can have a property "foo". If an instance validates to false against this schema, then we know it must have at least one item with a "foo" property. Since that false result is the result we actually want, we negate it with not.

{
  "not": {
    "items": {
      "not": { "required": ["foo"] }
    }
  }
}

additionalProperties works just like items except on objects, so the same pattern works there too.

[gregsdennis]

Cases:

[{ "foo": "bar" }, { "baz": 1 }]:

• required returns: true for /0, false for /1
• not inverts that: false for /0, true for /1
• items combines those: false overall
• not inverts that: true overall ✔️

[{ "foo": "bar" }, { "foo": 1 }]:

• required returns: true for both
• not inverts that: false for both
• items combines those: false overall
• not inverts that: true overall ✔️

[{ "baz": "bar" }, { "baz": 1 }]:

• required returns: false for both
• not inverts that: true for both
• items combines those: true overall
• not inverts that: false overall ✔️

Okay.... sorry. Had to work through that. Thought it might be helpful for others, too.

[m-mohr]

I'm strong supporter for this. We also have numerous use cases to make good schemas for the STAC specification: https://stacspec.org/

There we often need to check whether an object contains an object with specific requirements. An example:
https://gist.github.com/m-mohr/26dfeca72f2e8402f13565d6248a3346

[jdesrosiers]

There doesn't seem to be an opposition to this idea. I'd like to write up a PR sometime soonish if there are no objections. I think the only thing left to get consensus on is whether to say contains applies to objects as well as arrays or to define new objectContains/objectContainsMin/objectContainsMax keywords that apply to objects. I think I could go either way.

[gregsdennis]

I personally like expanding contains.

[jdesrosiers]

There seems to be consensus for expanding contains. I'm going to start writing this up in a few days unless someone tells me to hold off.

[jdesrosiers]

It just occurred to me, should we do the same thing for uniqueItems? We could make it unique and have it apply to arrays and object values.

[gregsdennis]

I don't see why it can't be supported (no conflicts, etc.), but it seems edge-case-y to me.

Maybe it's no less edge-case-y than contains supporting objects.

[awwright]

Following up my comment in #1092

What happens to schemas that allow an array or an object; that specify "contains" and "properties" and didn't intend for "contains" to apply to the object form?

[gregsdennis]

@awwright that seems like an edge case to me.

Even so, I'd separate those cases and specify an array for the contains:

- allOf
  - type=array & contains
  - properties

I can't think of a single use where you'd want to describe those in the same schema object.

[m-mohr]

While this is true for new schemas, this could be a breaking change for existing schemas. If you already have such a semantic with type: object & array and using contains, you may break things with the contains keyword now applying also to objects. To be backward compatible, it may indeed be better to make it a new keyword.