"requiredProperties" keyword

[awwright]

When accepting JSON documents for submission, it is frequently the case the documents are objects that have at least one property that is required, such as an ID or name field.

As an authoring convenience, JSON Schema should have a "requiredProperties" keyword that is similar to "properties" in that it defines a sub-schema to apply to the respective properties; but in addition, each of those properties must exist, similar to the "required" keyword.

This:

{
  "requiredProperties": {
    "name": { "type": "string", "minLength":1 }
  }
}

Would be the same as this:

{
  "required": ["name"],
  "properties": {
    "name": { "type": "string", "minLength":1 }
  }
}

Alternatively, this functionality could be built into the "required" keyword (so that "required" accepts an array or an object). This may even be preferable, since older validators will (usually) bail if they see an object where an array is expected:

{
  "required": {
    "name": { "type": "string", "minLength":1 }
  }
}

Examples of confused users:

• https://stackoverflow.com/questions/61786293/json-schema-if-then-else-conditional-behaving-strangely

This issue is intended to restate and close #659 #681 #734

[gregsdennis]

Is this really the right direction?

I started working with JSON Schema at draft 4, so I don't have any details, but does anyone know why required was removed from the property schema into the required property when moving from draft 3 -> 4?

Some insight into that decision would probably be helpful here.

[awwright]

@gregsdennis Boolean "required" didn't work the same way that other keywords worked; it only had meaning in a subschema in certain keywords, mostly "properties". It was nonsensical if used inside e.g. "patternProperties" or "additionalItems", and there's even more considerations, like what if you use it inside "oneOf" or "not"?

It also made it more difficult to create composable schemas; referencing a schema that had required: true could cause a little bit of a problem depending on where the $ref was located.

I actually argued against the change at the time because it was a nice authoring convenience compared to the array form; but I think this is superior to boolean "required" by far.

(rewritten from #734 (comment) )

[handrews]

While I'd be strongly against changing required to take an object form, I'm at least tentatively open to the idea of requiredProperties as a new keyword. Not sold, but keeping an open mind.

I want to keep the keyword taxonomy clear, in terms of which keywords behave as applicators, assertions, or annotations.

@awwright Adding an object syntax to required would make it a keyword that has two completely different syntaxes, with different taxonomy for each. This is exactly why we split dependencies into dependentSchemas (an applicator, taking a map of subschemas) and dependentRequired (an assertion, taking a map of string arrays).

But requiredProperties would be a single syntax that functions both as an applicator and an assertion. My purist impulses object to that, but since it is always functioning as both I could be convinced.

My practical concern with the taxonomy has to do with how truly generic implementations could manage plugins for unknown vocabularies. It's too involved to go into at the moment, I just mention it so people know that there's a point other than "Henry likes his own theoretical ideas a lot." (although that is also true).

[handrews]

@gregsdennis I think requiredProperties is a better proposal than the boolean required, because boolean required doesn't really fit into the processing model we've developed.

Superficially similar keywords like readOnly, writeOnly, and deprecated are fine because they are annotations, and by definition get attached to the location where they are applied. The attachment information includes the instance path, and therefore the relevant property name.

But assertions are intended to assert things about the instance location to which they are applied. Boolean required actually asserts something about the parent of the instance location to which it is applied:

{
    "type": "object",
    "properties": {
        "foo": {
            "type": "integer",
            "required": true
        },
        "bar": {
            "type": "string"
        }
    }
}

with instance

{
    "foo": 1,
    "bar": "something"
}

The root schema gets applied to the whole instance. We look at properties, and notice that we have subschemas for "foo" and "bar". We apply each one of them in turn. That "required": true in the subschema applied to #/foo in the instance doesn't say anything about #/foo (which has the value 1). It says that the root instance object must contain a property named "foo".

Now, because of how required works as a concept, we know that if it's getting applied at all, the property must have been present, so we can return a result without having to go inspect the parent.

But let's say we couldn't assume that. We would have to pass the parent object to the child assertion in order to determine the result. Nothing in JSON Schema assertion processing looks up into a parent. Applying a schema to an instance location only involves that location and its children, never the parent.

That is not a behavior we should change.

[gregsdennis]

@awwright / @handrews all very good insight. Thanks. I just wanted to ensure that readers of this issue have context and history; not advocating for a reversion.

[gregsdennis]

@awwright are you proposing also that we deprecate required? I've seen schemas that only have required, but no further restrictions on those properties. It's like specifying your new keyword with "myProp": true, which is actually more verbose.

[jdesrosiers]

requiredProperties makes me uncomfortable for theoretical purity reasons, but I can also see that it could be potentially useful.

I think this could be the first of keyword in a vocabulary of helper keywords that address concerns similar to this. It could even be officially supported by the JSON Schema team, but I don't think it belongs in the official specification.

[awwright]

I imagine requiredProperties as more of a syntactic sugar than anything else; it makes sense to me that sometimes syntatic sugar will combine applicators and validators.

@gregsdennis I don't think it would make sense to deprecate required; authors may still wish to declare "required" and "properties" separately, for composibility reasons.

[handrews]

@awwright There are a number of syntactic sugar proposals, and as @jdesrosiers notes maybe making them an additional vocabulary outside of the Core and Validation specification documents would be a good approach. We would then keep the six vocabularies in those two specifications as minimal as possible.

They do have some keywords that are technically unnecessary (dependentRequired, dependentSchemas, if/then/else can all be written in other ways, and there's substantial overlap between patternProperties and propertyNames). So I don't know where to draw the line. We didn't have vocabularies when all of those went in.

[handrews]

Regarding the purity issue, what I'm thinking of (not proposing here- I'll file a separate issue if and when it seems appropriate) is the ability for a vocabulary to indicate which keywords fall into which classifications, and how they interact.

Then extensions and generic implementations could be designed around those behaviors. Run in-place applicators first, because some keywords depend on the results of adjacent in-place applicators (at the moment, they specifically name keywords and because there's no generic way to do this with extension applicators). Run assertions when validating. If you're not collecting annotations then you can just ignore those keywords entirely. etc.

This is a half-formed idea which is why I haven't filed it, but that's where I'm keeping an eye on purity. A keyword that would need both an applicator hook and an assertion hook seems reasonable when those two behaviors can be modeled separately. Which is the case with requiredProperties. I'm hoping to get some real feedback on how people build vocabularies once we're out in the OAS 3.1 ecosystem. This idea may or may not be worth pursuing, we won't know until we get feedback.

So that's why I'm tentatively open to requiredProperties despite it violating a strict keyword classification concept. You can just treat it as a keyword that's run both ways, without having to do any more complex new processing.