Proposal: Add propertyDependencies keyword (aka discriminator)

[jdesrosiers]

The pattern of using oneOf to describe a choice between two types has become ubiquitous.

{
  "oneOf": [
    { "$ref": "#/$defs/aaa" },
    { "$ref": "#/$defs/bbb" }
  ]
}

However, this pattern is also notorious for its many shortcomings. There is a better way to describe this kind of constraint that doesn't have all the problems of the oneOf pattern, but it's verbose, error prone, and not particularly intuitive.

{
  "allOf": [
    {
      "if": {
        "properties": {
          "foo": { "const": "aaa" }
        },
        "required": ["foo"]
      },
      "then": { "$ref": "#/$defs/foo-aaa" }
    },
    {
      "if": {
        "properties": {
          "foo": { "const": "bbb" }
        },
        "required": ["foo"]
      },
      "then": { "$ref": "#/$defs/foo-bbb" }
    }
  ]
}

OpenAPI addresses this problem with the discriminator keyword. However their approach is more oriented toward code generation concerns and is poorly specified when it comes to validation. I don't think we should adopt discriminator, but I do think we need something like it. I believe this is the thing that is generating the most questions in our community right now.

Right now, we have the dependentSchemas keyword that is very close to what is needed except it checks for the presence of a property rather than it's value. The propertyDependencies keyword builds on that concept to solve the problem.

{
  "propertyDependencies": {
    "foo": {
      "aaa": { "$ref": "#/$defs/foo-aaa" },
      "bbb": { "$ref": "#/$defs/foo-bbb" }
    }
  }
}

If the instance is an object, then for every property (name) and value of that property (value), if /propertyDependencies/{name}/{value} is defined, then the instance must be valid against the schema at that location. Compared to discriminator, this is more consistent with the style of JSON Schema keywords because it doesn't use sub-keywords like propertyName and mappings. It's also more powerful because it allows you to discriminate using more than one property.

Because of the parallels to dependencies, I chose to name it in similar way. However, dependencies is the least well known and understood keyword, so it might not be beneficial to build on that naming convention. Either way, I don't think we should call it discriminator to avoid confusion with what OpenAPI has specified.

[karenetheridge]

Even though this is "just" syntax sugar, the dependentSchemas and dependentRequired keywords are sugar too, that can also be achieved by combining if/then/else and allOf. However, sugar keywords are more efficient (in the allOf case we evaluate all clauses, even though only one of the if/then conditions can successfully match), and also the resulting errors will be more clear to the user. (And of course the paths in the errors or annotations will be different.)

I agree that this is one of the most frequently asked questions lately, and adding this construct should help both schema authors and various tools that parse schemas and generate code and/or UIs.

(Note: I originally misread the placement of required in the examples above. required is needed in the conditional, so the check doesn't pass if the property doesn't exist at all. but it should not be implied at the top level, as none of the other object keywords (properties, patternProperties, propertyNames, dependent*) imply required either. If the property doesn't exist, then the subschemas are not applied and the keyword as a whole still evaluates successfully.)

[gregsdennis]

{
  "propertyDependencies": {
    "foo": {
      "aaa": { "$ref": "#/$defs/foo-aaa" },
      "bbb": { "$ref": "#/$defs/foo-bbb" }
    }
  }
}

If the instance is an object, then for every property (name) and value of that property (value), if /propertyDependencies/{name}/{value} is defined, then the instance must be valid against the schema at that location.

I'm confused. Are aaa and bbb possible values for foo? What if my possible value for foo is a non-string? I won't be able to use that as a key in an object as shown here.

[karenetheridge]

discriminator only works for objects whose values are strings. Is there a need to support anything else? What might the syntax look like for that?

[gregsdennis]

There could be. If this is intended to replace the allOf-if verboseness above, then I would expect that any value should be supported.

[jdesrosiers]

@gregsdennis It's important to keep in mind that propertyDependencies is not designed to solve every possible conditional selection use case. dependentSchemas and propertyDependencies are just sugar for the most common patterns. Neither are intended to replace or to be as powerful as if/then.

That said, you have a good point that this would only work for properties with string values and it would be nice if it could support numbers and booleans without compromising the simplicity propertyDependencies achieves. We could define some type coercion behavior for numbers and booleans if we think it's valuable enough to justify the extra complexity. I'm not sure it's worth it.

Another limitation that came up in Slack discussion is that there's no way to set a default schema to use if there are no matches. This could be supported by adding a sibling keyword called defaultPropertyDependency. Again, I don't think it's a common need and therefore, not worth including at this point.

[gregsdennis]

Maybe with these things in mind, this would be better suited to an independent vocabulary and not in the out-of-the-box (avoiding the word "core" here) set of keywords.

(🤔 Actually, also moving other "sugar" keywords into a separate vocabulary might not be a bad idea...)

[jdesrosiers]

I disagree. We want JSON Schema to be reasonably easy use for the most common use cases without having to be extended. That means that having a few sugar keywords around to make very common patterns not such a horrible experience. The use case propertyDependencies covers is extremely common and is responsible for a significant chunk of the support questions we see on SO and Slack. That's why I was motivated to make this proposal. I'm tired of answering the same questions over and over again.

Moving sugar keywords out to an independent vocabulary is probably a more slippery slope than you expect. Here are some examples that could be considered sugar keywords.

• dependentRequired
• dependentSchemas
• if/then/else
• contains
• enum
• The array form of type
• properties

[gregsdennis]

I'm not suggesting the existing sugar keywords are moved to an independent vocab, just a spec-defined sugar vocab, akin to the annotations or metadata vocabs. If they just make authoring easier, then they're not really basic functionality. It was just a thought.

But I do think this specific proposal belongs in an independent vocab unless we can make it work for all value types.

[karenetheridge]

Whether this goes into a new vocab or not is more an implementation question, as long as it's included in the main meta-schema (that is, it is enabled for schemas that declare "$schema": "https://json-schema/draft/2021-XX/schema"). It's not a difficult keyword to implement (certainly easier than unimplemented*), and omitting it from the default set would defeat the point of making it available to to make schema authoring more intuitive.

[jdesrosiers]

@gregsdennis

I'm not suggesting the existing sugar keywords are moved to an independent vocab, just a spec-defined sugar vocab

I see. I'm not sure that's necessary, but it's a little off topic, so let's discuss that later.

I do think this specific proposal belongs in an independent vocab unless we can make it work for all value types.

It seems a bit extreme to exclude a keyword that solves a real and common problem because it doesn't support a use case that no one is asking for. I think it would help if you could share why you think it's important for this keyword to support all value types.

I'll write up some examples of alternatives so we can more easily see what the trade-offs are. I think that might help with decision making process.

[gregsdennis]

$data solved a "real and common problem" but I put my proposal in a vocab so that it could gain adoption and support independently.

I think this should be the approach for new keywords going forward. If we see that it has a fair amount of implementation support and end-user use, then it can be pulled into the main vocabs with relative ease.

I also think that keywords that are in the main vocabs should be as generic as possible, supporting all possible values. Examples of this are enum and format, which allow all types, even objects and arrays.

You might argue that keywords like required and properties only support strings, but these target object keys specifically which are only ever strings. However this keyword (as proposed) targets values, which can be of any type.

[jdesrosiers]

Here are what some alternatives might look like that support all value types. All examples are functionality equivalent to the examples in the original post.

This version uses an array of objects. Each object is a collection of the variables needed to express a property dependency. This doesn't fit the style of JSON Schema. There aren't any keywords remotely like this. It's also still too verbose. It's a little more intuitive than if/then and definitely less error prone. This is also less efficient to process. Implementations will need to check every alternative for a match as opposed to the original proposal that can do this in O(1).

{
  "propertyDependencies": [
    {
      "propertyName": "foo",
      "propertySchema": { "const": "aaa" },
      "apply": { "$ref": "#/$defs/foo-aaa" }
    },
    {
      "propertyName": "foo",
      "propertySchema": { "const": "bbb" },
      "apply": { "$ref": "#/$defs/foo-bbb" }
    }
  ]
}

A slight variation on that example is to make it a map of keyword to dependency object. But, I don't think that makes a significant difference. It's still too verbose and has the same efficiency problems in most cases.

{
  "propertyDependencies": {
    "foo": [
      {
        "propertySchema": { "const": "aaa" },
        "apply": { "$ref": "#/$defs/foo-aaa" }
      },
      {
        "propertySchema": { "const": "bbb" },
        "apply": { "$ref": "#/$defs/foo-bbb" }
      }
    ]
  }
}

This one is a little more consistent with the JSON Schema style (poor keyword naming aside), but otherwise has all the same problems as the other examples.

{
  "allOf": [
    {
      "propertyDependencyName": "foo",
      "propertyDependencySchema": { "const": "aaa" },
      "propertyDependencyApply": { "$ref": "#/$defs/foo-aaa" }
    },
    {
      "propertyDependencyName": "foo",
      "propertyDependencySchema": { "const": "bbb" },
      "propertyDependencyApply": { "$ref": "#/$defs/foo-bbb" }
    }
  ]
}

This one is a variation of if that combines if, properties, and required to reduce boilerplate. It's also essentially a variation of the previous example with better names. While I think this is the best alternative, I still think people will avoid this because it's too verbose.

{
  "allOf": [
    {
      "ifProperties": {
        "foo": { "const": "aaa" }
      },
      "then": { "$ref": "#/$defs/foo-aaa" }
    },
    {
      "ifProperties": {
        "foo": { "const": "bbb" }
      },
      "then": { "$ref": "#/$defs/foo-aaa" }
    }
]

I read all the discriminator discussions I could find in the OpenAPI repo before making this proposal and I will tell you that one of the main things people want from this keyword that you don't get from any of these alternatives is O(1) alternative selection. Only the original proposal can do that.

[jdesrosiers]

$data solved a "real and common problem"

It most certainly does, but $data is a very different case. There are arguments about scope (which I don't completely agree with), but more importantly, it introduces a completely new core behavior to JSON Schema which can cause problems. For example, the way your vocabulary defines $data is not compatible with validators that have a separate compile and interpret step like mine and many others. propertyDependencies is effectively just sugar for something JSON Schema already supports. There is plenty of precedent for adding this kind of thing when we see overwhelming need for them including contains and if/then/else.

I put my proposal in a vocab so that it could gain adoption and support independently. I think this should be the approach for new keywords going forward.

I don't think our vocabulary system is equipped to support that goal right now. It's something I want to bring up in more detail at some point, but I'll try to explain briefly for now. Vocabularies are well equipped for creating dialects. It's good for when someone wants to include a version of JSON Schema in their own specification and provide their own tooling for that specialized use of JSON Schema. OpenAPI is a great example of who it would work well for. However, vocabularies are not good for individual schema authors who want to add a new capability to their schemas. Schema authors would need to create their own custom dialect every time they want to use a non-standard keyword in one of their schemas. I don't see people doing that until we can make changes to the vocabulary system to better support schema authors as opposed to specification authors.

I also think that keywords that are in the main vocabs should be as generic as possible

I agree that they should be as generic as is reasonable. When making it more generic means that it no longer solves the problem it's intended to solve, then you've gone too far. Hopefully the alternative examples I posted help illustrate that supporting any value type is a step too far.

[handrews]

I'd advise separating the question of extension vs in-spec vocabulary from the discussion of the keyword itself. These are largely orthogonal problems and can clutter the issue for readers not as deeply versed in the project. Also, keywords can always be pulled into the spec- initially releasing it as an extension vocabulary for use with 2020-12 does not preclude pulling it into the next draft (or a later one).

While I have a knee-jerk "what about other types" reaction, I agree that a keyword that is fundamentally about making a common use case easier should focus on that use case. It's already possible to handle arbitrarily complex conditions, so we don't really need another system for arbitrary complexity.

I think boolean and numeric coercion is a reasonable approach for those simple cases, but don't have strong feelings on it. You would technically lose the ability to distinguish between true and "true", or null and "null", or 1 and "1", but arguably if you're trying to do that you should be questioning your life choices 😜 You could also do that distinction with oneOf or if and type if you really need it- a good example of making the simple case (switch on true / false / null) easy with type coercion, and leaving the complex-to-pathological case (type mixing) as requiring more complexity.

Since I haven't been commenting for a while, let me just note that I'll probably start dropping the occasional comment on issues, but do not intend to dive back in at anything resembling my previous levels of involvement anytime soon. Please just treat my comments as offered opinions, and don't wait on me if I don't reply to something promptly. I'm thrilled to see all of the work that is going on and do not want to disrupt the flow you all have going!