Skip to content

Commit 637a898

Browse files
jviottijviotti
authored
Document allOf for previous dialects (#297)
Signed-off-by: Juan Cruz Viotti <jv@jviotti.com>
1 parent b739315 commit 637a898

4 files changed

Lines changed: 477 additions & 0 deletions

File tree

‎content/2019-09/applicator/allOf.markdown‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,3 +27,126 @@ related:
2727
- vocabulary: applicator
2828
keyword: not
2929
---
30+
31+
The {{<link keyword="allOf" vocabulary="applicator">}} keyword restricts
32+
instances to validate against _every_ given subschema. This keyword can be
33+
thought of as a [logical
34+
conjunction](https://en.wikipedia.org/wiki/Logical_conjunction) (AND)
35+
operation, as instances are valid if they satisfy every constraint of every
36+
subschema (the intersection of the constraints).
37+
38+
{{<common-pitfall>}} Wrapping a single instance of the [`$ref`](../../core/ref)
39+
or [`$recursiveRef`](../../core/recursiveref) keyword in an `allOf` operator is
40+
an anti-pattern.
41+
42+
This practice has historical roots. In JSON Schema [Draft 7](/draft7) and
43+
earlier versions, any subschema declaring the `$ref` keyword was considered to
44+
be a _reference object_ and any other sibling keyword was silently ignored. As
45+
a consequence, subschemas with references that made use of other keywords had
46+
to artificially wrap the reference into its own subschema.
47+
{{</common-pitfall>}}
48+
49+
{{<best-practice>}}This keyword typically has a single use case: combining
50+
_multiple_ schemas through the use of (internal or external) references. If
51+
this is not the case, prefer elevating the keywords of every subschema to the
52+
outer schema and avoid using this keyword. {{</best-practice>}}
53+
54+
This keyword is equivalent to the `&&` operator found in most programming
55+
languages. For example:
56+
57+
```c
58+
bool valid = A && B && C;
59+
```
60+
61+
As a reference, the following boolean [truth
62+
table](https://en.wikipedia.org/wiki/Truth_table) considers the evaluation
63+
result of this keyword given 3 subschemas: A, B, and C.
64+
65+
<table class="table table-borderless border">
66+
<thead>
67+
<tr class="table-light">
68+
<th><code>allOf</code></th>
69+
<th>Subschema A</th>
70+
<th>Subschema B</th>
71+
<th>Subschema C</th>
72+
</tr>
73+
</thead>
74+
<tbody>
75+
<tr class="table-danger">
76+
<td class="fw-bold"><i class="bi bi-x-circle-fill me-1"></i> Invalid</td>
77+
<td><i class="bi bi-x-circle"></i> Invalid</td>
78+
<td><i class="bi bi-x-circle"></i> Invalid</td>
79+
<td><i class="bi bi-x-circle"></i> Invalid</td>
80+
</tr>
81+
<tr class="table-danger">
82+
<td class="fw-bold"><i class="bi bi-x-circle-fill me-1"></i> Invalid</td>
83+
<td><i class="bi bi-x-circle"></i> Invalid</td>
84+
<td><i class="bi bi-x-circle"></i> Invalid</td>
85+
<td><i class="bi bi-check-circle"></i> Valid</td>
86+
</tr>
87+
<tr class="table-danger">
88+
<td class="fw-bold"><i class="bi bi-x-circle-fill me-1"></i> Invalid</td>
89+
<td><i class="bi bi-x-circle"></i> Invalid</td>
90+
<td><i class="bi bi-check-circle"></i> Valid</td>
91+
<td><i class="bi bi-x-circle"></i> Invalid</td>
92+
</tr>
93+
<tr class="table-danger">
94+
<td class="fw-bold"><i class="bi bi-x-circle-fill me-1"></i> Invalid</td>
95+
<td><i class="bi bi-x-circle"></i> Invalid</td>
96+
<td><i class="bi bi-check-circle"></i> Valid</td>
97+
<td><i class="bi bi-check-circle"></i> Valid</td>
98+
</tr>
99+
<tr class="table-danger">
100+
<td class="fw-bold"><i class="bi bi-x-circle-fill me-1"></i> Invalid</td>
101+
<td><i class="bi bi-check-circle"></i> Valid</td>
102+
<td><i class="bi bi-x-circle"></i> Invalid</td>
103+
<td><i class="bi bi-x-circle"></i> Invalid</td>
104+
</tr>
105+
<tr class="table-danger">
106+
<td class="fw-bold"><i class="bi bi-x-circle-fill me-1"></i> Invalid</td>
107+
<td><i class="bi bi-check-circle"></i> Valid</td>
108+
<td><i class="bi bi-x-circle"></i> Invalid</td>
109+
<td><i class="bi bi-check-circle"></i> Valid</td>
110+
</tr>
111+
<tr class="table-danger">
112+
<td class="fw-bold"><i class="bi bi-x-circle-fill me-1"></i> Invalid</td>
113+
<td><i class="bi bi-check-circle"></i> Valid</td>
114+
<td><i class="bi bi-check-circle"></i> Valid</td>
115+
<td><i class="bi bi-x-circle"></i> Invalid</td>
116+
</tr>
117+
<tr class="table-success">
118+
<td class="fw-bold"><i class="bi bi-check-circle-fill me-1"></i> Valid</td>
119+
<td><i class="bi bi-check-circle"></i> Valid</td>
120+
<td><i class="bi bi-check-circle"></i> Valid</td>
121+
<td><i class="bi bi-check-circle"></i> Valid</td>
122+
</tr>
123+
</tbody>
124+
</table>
125+
126+
## Examples
127+
128+
{{<schema `A schema that constrains instances with two internally referenced schemas`>}}
129+
{
130+
"$schema": "https://json-schema.org/draft/2019-09/schema",
131+
"allOf": [
132+
{ "$ref": "#/$defs/foo" },
133+
{ "$ref": "#/$defs/bar" }
134+
],
135+
"$defs": {
136+
"foo": { "type": "number" },
137+
"bar": { "type": "integer" }
138+
}
139+
}
140+
{{</schema>}}
141+
142+
{{<instance-pass `A value that matches both subschemas is valid`>}}
143+
12345
144+
{{</instance-pass>}}
145+
146+
{{<instance-fail `A value that only matches one of the subschemas is invalid`>}}
147+
3.14
148+
{{</instance-fail>}}
149+
150+
{{<instance-fail `A value that does not match any of the subschemas is invalid`>}}
151+
"Hello World"
152+
{{</instance-fail>}}

‎content/draft4/validation/allOf.markdown‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,121 @@ related:
2121
- vocabulary: validation
2222
keyword: not
2323
---
24+
25+
The {{<link keyword="allOf" vocabulary="validation">}} keyword restricts
26+
instances to validate against _every_ given subschema. This keyword can be
27+
thought of as a [logical
28+
conjunction](https://en.wikipedia.org/wiki/Logical_conjunction) (AND)
29+
operation, as instances are valid if they satisfy every constraint of every
30+
subschema (the intersection of the constraints).
31+
32+
{{<common-pitfall>}} Note that in JSON Schema [Draft 7](/draft7) and earlier
33+
versions, any subschema declaring the `$ref` keyword is considered to be a
34+
_reference object_ and any other sibling keyword will be silently ignored. To
35+
avoid this, wrap subschemas with references that make use of other keywords
36+
using the [`allOf`](../../validation/allOf) keyword. {{</common-pitfall>}}
37+
38+
{{<best-practice>}}This keyword typically has a single use case: combining one
39+
or more schemas through the use of (internal or external) references. If this
40+
is not the case, prefer elevating the keywords of every subschema to the outer
41+
schema and avoid using this keyword. {{</best-practice>}}
42+
43+
This keyword is equivalent to the `&&` operator found in most programming
44+
languages. For example:
45+
46+
```c
47+
bool valid = A && B && C;
48+
```
49+
50+
As a reference, the following boolean [truth
51+
table](https://en.wikipedia.org/wiki/Truth_table) considers the evaluation
52+
result of this keyword given 3 subschemas: A, B, and C.
53+
54+
<table class="table table-borderless border">
55+
<thead>
56+
<tr class="table-light">
57+
<th><code>allOf</code></th>
58+
<th>Subschema A</th>
59+
<th>Subschema B</th>
60+
<th>Subschema C</th>
61+
</tr>
62+
</thead>
63+
<tbody>
64+
<tr class="table-danger">
65+
<td class="fw-bold"><i class="bi bi-x-circle-fill me-1"></i> Invalid</td>
66+
<td><i class="bi bi-x-circle"></i> Invalid</td>
67+
<td><i class="bi bi-x-circle"></i> Invalid</td>
68+
<td><i class="bi bi-x-circle"></i> Invalid</td>
69+
</tr>
70+
<tr class="table-danger">
71+
<td class="fw-bold"><i class="bi bi-x-circle-fill me-1"></i> Invalid</td>
72+
<td><i class="bi bi-x-circle"></i> Invalid</td>
73+
<td><i class="bi bi-x-circle"></i> Invalid</td>
74+
<td><i class="bi bi-check-circle"></i> Valid</td>
75+
</tr>
76+
<tr class="table-danger">
77+
<td class="fw-bold"><i class="bi bi-x-circle-fill me-1"></i> Invalid</td>
78+
<td><i class="bi bi-x-circle"></i> Invalid</td>
79+
<td><i class="bi bi-check-circle"></i> Valid</td>
80+
<td><i class="bi bi-x-circle"></i> Invalid</td>
81+
</tr>
82+
<tr class="table-danger">
83+
<td class="fw-bold"><i class="bi bi-x-circle-fill me-1"></i> Invalid</td>
84+
<td><i class="bi bi-x-circle"></i> Invalid</td>
85+
<td><i class="bi bi-check-circle"></i> Valid</td>
86+
<td><i class="bi bi-check-circle"></i> Valid</td>
87+
</tr>
88+
<tr class="table-danger">
89+
<td class="fw-bold"><i class="bi bi-x-circle-fill me-1"></i> Invalid</td>
90+
<td><i class="bi bi-check-circle"></i> Valid</td>
91+
<td><i class="bi bi-x-circle"></i> Invalid</td>
92+
<td><i class="bi bi-x-circle"></i> Invalid</td>
93+
</tr>
94+
<tr class="table-danger">
95+
<td class="fw-bold"><i class="bi bi-x-circle-fill me-1"></i> Invalid</td>
96+
<td><i class="bi bi-check-circle"></i> Valid</td>
97+
<td><i class="bi bi-x-circle"></i> Invalid</td>
98+
<td><i class="bi bi-check-circle"></i> Valid</td>
99+
</tr>
100+
<tr class="table-danger">
101+
<td class="fw-bold"><i class="bi bi-x-circle-fill me-1"></i> Invalid</td>
102+
<td><i class="bi bi-check-circle"></i> Valid</td>
103+
<td><i class="bi bi-check-circle"></i> Valid</td>
104+
<td><i class="bi bi-x-circle"></i> Invalid</td>
105+
</tr>
106+
<tr class="table-success">
107+
<td class="fw-bold"><i class="bi bi-check-circle-fill me-1"></i> Valid</td>
108+
<td><i class="bi bi-check-circle"></i> Valid</td>
109+
<td><i class="bi bi-check-circle"></i> Valid</td>
110+
<td><i class="bi bi-check-circle"></i> Valid</td>
111+
</tr>
112+
</tbody>
113+
</table>
114+
115+
## Examples
116+
117+
{{<schema `A schema that constrains instances with two internally referenced schemas`>}}
118+
{
119+
"$schema": "http://json-schema.org/draft-04/schema#",
120+
"allOf": [
121+
{ "$ref": "#/$defs/foo" },
122+
{ "$ref": "#/$defs/bar" }
123+
],
124+
"$defs": {
125+
"foo": { "type": "number" },
126+
"bar": { "type": "integer" }
127+
}
128+
}
129+
{{</schema>}}
130+
131+
{{<instance-pass `A value that matches both subschemas is valid`>}}
132+
12345
133+
{{</instance-pass>}}
134+
135+
{{<instance-fail `A value that only matches one of the subschemas is invalid`>}}
136+
3.14
137+
{{</instance-fail>}}
138+
139+
{{<instance-fail `A value that does not match any of the subschemas is invalid`>}}
140+
"Hello World"
141+
{{</instance-fail>}}

‎content/draft6/validation/allOf.markdown‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,121 @@ related:
2121
- vocabulary: validation
2222
keyword: not
2323
---
24+
25+
The {{<link keyword="allOf" vocabulary="validation">}} keyword restricts
26+
instances to validate against _every_ given subschema. This keyword can be
27+
thought of as a [logical
28+
conjunction](https://en.wikipedia.org/wiki/Logical_conjunction) (AND)
29+
operation, as instances are valid if they satisfy every constraint of every
30+
subschema (the intersection of the constraints).
31+
32+
{{<common-pitfall>}} Note that in JSON Schema [Draft 7](/draft7) and earlier
33+
versions, any subschema declaring the `$ref` keyword is considered to be a
34+
_reference object_ and any other sibling keyword will be silently ignored. To
35+
avoid this, wrap subschemas with references that make use of other keywords
36+
using the [`allOf`](../../validation/allOf) keyword. {{</common-pitfall>}}
37+
38+
{{<best-practice>}}This keyword typically has a single use case: combining one
39+
or more schemas through the use of (internal or external) references. If this
40+
is not the case, prefer elevating the keywords of every subschema to the outer
41+
schema and avoid using this keyword. {{</best-practice>}}
42+
43+
This keyword is equivalent to the `&&` operator found in most programming
44+
languages. For example:
45+
46+
```c
47+
bool valid = A && B && C;
48+
```
49+
50+
As a reference, the following boolean [truth
51+
table](https://en.wikipedia.org/wiki/Truth_table) considers the evaluation
52+
result of this keyword given 3 subschemas: A, B, and C.
53+
54+
<table class="table table-borderless border">
55+
<thead>
56+
<tr class="table-light">
57+
<th><code>allOf</code></th>
58+
<th>Subschema A</th>
59+
<th>Subschema B</th>
60+
<th>Subschema C</th>
61+
</tr>
62+
</thead>
63+
<tbody>
64+
<tr class="table-danger">
65+
<td class="fw-bold"><i class="bi bi-x-circle-fill me-1"></i> Invalid</td>
66+
<td><i class="bi bi-x-circle"></i> Invalid</td>
67+
<td><i class="bi bi-x-circle"></i> Invalid</td>
68+
<td><i class="bi bi-x-circle"></i> Invalid</td>
69+
</tr>
70+
<tr class="table-danger">
71+
<td class="fw-bold"><i class="bi bi-x-circle-fill me-1"></i> Invalid</td>
72+
<td><i class="bi bi-x-circle"></i> Invalid</td>
73+
<td><i class="bi bi-x-circle"></i> Invalid</td>
74+
<td><i class="bi bi-check-circle"></i> Valid</td>
75+
</tr>
76+
<tr class="table-danger">
77+
<td class="fw-bold"><i class="bi bi-x-circle-fill me-1"></i> Invalid</td>
78+
<td><i class="bi bi-x-circle"></i> Invalid</td>
79+
<td><i class="bi bi-check-circle"></i> Valid</td>
80+
<td><i class="bi bi-x-circle"></i> Invalid</td>
81+
</tr>
82+
<tr class="table-danger">
83+
<td class="fw-bold"><i class="bi bi-x-circle-fill me-1"></i> Invalid</td>
84+
<td><i class="bi bi-x-circle"></i> Invalid</td>
85+
<td><i class="bi bi-check-circle"></i> Valid</td>
86+
<td><i class="bi bi-check-circle"></i> Valid</td>
87+
</tr>
88+
<tr class="table-danger">
89+
<td class="fw-bold"><i class="bi bi-x-circle-fill me-1"></i> Invalid</td>
90+
<td><i class="bi bi-check-circle"></i> Valid</td>
91+
<td><i class="bi bi-x-circle"></i> Invalid</td>
92+
<td><i class="bi bi-x-circle"></i> Invalid</td>
93+
</tr>
94+
<tr class="table-danger">
95+
<td class="fw-bold"><i class="bi bi-x-circle-fill me-1"></i> Invalid</td>
96+
<td><i class="bi bi-check-circle"></i> Valid</td>
97+
<td><i class="bi bi-x-circle"></i> Invalid</td>
98+
<td><i class="bi bi-check-circle"></i> Valid</td>
99+
</tr>
100+
<tr class="table-danger">
101+
<td class="fw-bold"><i class="bi bi-x-circle-fill me-1"></i> Invalid</td>
102+
<td><i class="bi bi-check-circle"></i> Valid</td>
103+
<td><i class="bi bi-check-circle"></i> Valid</td>
104+
<td><i class="bi bi-x-circle"></i> Invalid</td>
105+
</tr>
106+
<tr class="table-success">
107+
<td class="fw-bold"><i class="bi bi-check-circle-fill me-1"></i> Valid</td>
108+
<td><i class="bi bi-check-circle"></i> Valid</td>
109+
<td><i class="bi bi-check-circle"></i> Valid</td>
110+
<td><i class="bi bi-check-circle"></i> Valid</td>
111+
</tr>
112+
</tbody>
113+
</table>
114+
115+
## Examples
116+
117+
{{<schema `A schema that constrains instances with two internally referenced schemas`>}}
118+
{
119+
"$schema": "http://json-schema.org/draft-06/schema#",
120+
"allOf": [
121+
{ "$ref": "#/$defs/foo" },
122+
{ "$ref": "#/$defs/bar" }
123+
],
124+
"$defs": {
125+
"foo": { "type": "number" },
126+
"bar": { "type": "integer" }
127+
}
128+
}
129+
{{</schema>}}
130+
131+
{{<instance-pass `A value that matches both subschemas is valid`>}}
132+
12345
133+
{{</instance-pass>}}
134+
135+
{{<instance-fail `A value that only matches one of the subschemas is invalid`>}}
136+
3.14
137+
{{</instance-fail>}}
138+
139+
{{<instance-fail `A value that does not match any of the subschemas is invalid`>}}
140+
"Hello World"
141+
{{</instance-fail>}}

0 commit comments

Comments
 (0)