Skip to content

Commit 8c2a6ee

Browse files
PropDeps: Fix typos and other cleanup
Co-authored-by: Greg Dennis <[email protected]>
1 parent b6f9430 commit 8c2a6ee

File tree

1 file changed

+13
-13
lines changed

1 file changed

+13
-13
lines changed

proposals/propertyDependencies.md

+13-13
Original file line numberDiff line numberDiff line change
@@ -36,14 +36,15 @@ specification](../jsonschema-core.html) also apply to this document.
3636
## Overview
3737

3838
### Problem Statement
39-
A common need in JSON Schema is to select between one schema or another to
39+
40+
A common need in JSON Schema is to select between one or more schemas to use to
4041
validate an instance based on the value of some property in the JSON instance.
4142
There are a several patterns people use to accomplish this, but they all have
4243
significant [problems](#problems).
4344

4445
OpenAPI solves this problem with the `discriminator` keyword. However, their
4546
approach is more oriented toward code generation concerns, is poorly specified
46-
when it comes to validation, and is couple to OpenAPI concepts that don't exist
47+
when it comes to validation, and is coupled to OpenAPI concepts that don't exist
4748
is JSON Schema. Therefore, it's necessary to define something new rather than
4849
adopt `discriminator`.
4950

@@ -79,9 +80,9 @@ The validation result is equivalent to the following schema.
7980

8081
### Limitations
8182

82-
The problem of choosing an alternative based on a property value could apply for
83-
a value of any JSON type, but `propertyDependencies` only solves this problem
84-
when the value is a string. One of the main goals of this keyword is to define
83+
The problem of choosing a subschema based on a property value could apply for a
84+
value of any JSON type, but `propertyDependencies` only solves this problem when
85+
the value is a string. One of the main goals of this keyword is to define
8586
something that's intuitive enough and easy enough to use that people will
8687
actually use it rather than fallback to `oneOf` because it's simple. Achieving
8788
those goals means that some trade-offs need to be made. {{alternatives}} lists
@@ -131,21 +132,20 @@ not wide-spread or consistent behavior, nor is it expected or required from
131132
implementations.
132133

133134
This pattern is also inefficient. Generally, there is a single value in the
134-
object that determines which alternative to chose, but the `oneOf` pattern has
135-
no way to specify what that value is and therefore needs to evaluate the entire
136-
schema. This is made worse in that every alternative needs to be fully validated
137-
to ensure that only one of the alternative passes and all the others fail. This
135+
object that determines which subschema to chose, but the `oneOf` pattern has no
136+
way to specify what that value is and therefore needs to evaluate the entire
137+
schema. This is made worse in that every subschema needs to be fully validated
138+
to ensure that only one of the subschemas passes and all the others fail. This
138139
last problem can be avoided by using `anyOf` instead, but that pattern is much
139140
less used.
140141

141142
### `if`/`then`
142143

143144
We can describe this kind of constraint more efficiently and with with better
144145
error messaging by using `if`/`then`. This allows the user to explicitly specify
145-
the constraint to be used to select which alternative the schema should be used
146-
to validate the schema. However, this pattern has problems of it's own. It's
147-
verbose, error prone, and not particularly intuitive, which leads most people to
148-
avoid it.
146+
the constraint to be used to select which subschema should be used. However,
147+
this pattern has problems of it's own. It's verbose, error prone, and not
148+
particularly intuitive, which leads most people to avoid it.
149149

150150
```jsonschema
151151
{

0 commit comments

Comments
 (0)