Skip to content

Commit 3c4c288

Browse files
jviottijviotti
committed
More
Signed-off-by: Juan Cruz Viotti <jv@jviotti.com>
1 parent a0510f0 commit 3c4c288

57 files changed

Lines changed: 472 additions & 349 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

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

Lines changed: 29 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -38,22 +38,24 @@ related:
3838
keyword: unevaluatedItems
3939
---
4040

41-
The `additionalItems` keyword restricts array instance items not described by
42-
the _sibling_ [`items`]({{< ref "2019-09/applicator/items" >}}) keyword (when
43-
[`items`]({{< ref "2019-09/applicator/items" >}}) is in array form), to
44-
validate against the given subschema. Whether this keyword was evaluated
45-
against any item of the array instance is reported using annotations.
41+
The [`additionalItems`]({{< ref "2019-09/applicator/additionalitems" >}})
42+
keyword restricts array instance items not described by the _sibling_
43+
[`items`]({{< ref "2019-09/applicator/items" >}}) keyword (when [`items`]({{<
44+
ref "2019-09/applicator/items" >}}) is in array form), to validate against the
45+
given subschema. Whether this keyword was evaluated against any item of the
46+
array instance is reported using annotations.
4647

4748
{{<common-pitfall>}}This keyword **only** has an effect when the sibling
4849
[`items`]({{< ref "2019-09/applicator/items" >}}) keyword is set to an array of
49-
schemas. If [`items`]({{< ref "2019-09/applicator/items" >}}) is not present or is set to a schema (not an array),
50-
[`additionalItems`]({{< ref "2019-09/applicator/additionalitems" >}}) has no effect and is ignored. This is a common source of
51-
confusion.{{</common-pitfall>}}
50+
schemas. If [`items`]({{< ref "2019-09/applicator/items" >}}) is not present or
51+
is set to a schema (not an array of schemas), [`additionalItems`]({{< ref
52+
"2019-09/applicator/additionalitems" >}}) has no effect and is ignored.{{</common-pitfall>}}
5253

5354
{{<common-pitfall>}}This keyword does not prevent an array instance from being
54-
empty or having fewer items than the [`items`]({{< ref "2019-09/applicator/items" >}}) array. If needed, use the
55-
[`minItems`]({{< ref "2019-09/validation/minitems" >}}) to assert on the minimum
56-
bounds of the array.{{</common-pitfall>}}
55+
empty or having fewer items than the [`items`]({{< ref
56+
"2019-09/applicator/items" >}}) array. If needed, use the [`minItems`]({{< ref
57+
"2019-09/validation/minitems" >}}) keyword to assert on the minimum bounds of
58+
the array.{{</common-pitfall>}}
5759

5860
{{<constraint-warning `array`>}}
5961

@@ -116,7 +118,7 @@ bounds of the array.{{</common-pitfall>}}
116118
[ false, 35, "foo" ]
117119
{{</instance-fail>}}
118120

119-
{{<schema `A schema that demonstrates when this keyword has no effect`>}}
121+
{{<schema `A schema that describes open items and additional items leads to the additional items schema being ignored`>}}
120122
{
121123
"$schema": "https://json-schema.org/draft/2019-09/schema",
122124
"items": { "type": "number" },
@@ -139,3 +141,18 @@ bounds of the array.{{</common-pitfall>}}
139141
{{<instance-annotation>}}
140142
{ "keyword": "/items", "instance": "", "value": true }
141143
{{</instance-annotation>}}
144+
145+
{{<schema `A schema with only additional items definitions leads to the additional items schema being ignored`>}}
146+
{
147+
"$schema": "https://json-schema.org/draft/2019-09/schema",
148+
"additionalItems": { "type": "string" }
149+
}
150+
{{</schema>}}
151+
152+
{{<instance-pass `Any array is valid`>}}
153+
[ 1, 2, 3 ]
154+
{{</instance-pass>}}
155+
156+
{{<instance-pass `A non-array value is valid`>}}
157+
"Hello World"
158+
{{</instance-pass>}}

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

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,9 @@ related:
4141
keyword: unevaluatedProperties
4242
---
4343

44-
The `additionalProperties` keyword restricts object instance properties not
45-
described by the _sibling_ [`properties`]({{< ref
44+
The [`additionalProperties`]({{< ref
45+
"2019-09/applicator/additionalproperties" >}}) keyword restricts object instance
46+
properties not described by the _sibling_ [`properties`]({{< ref
4647
"2019-09/applicator/properties" >}}) and [`patternProperties`]({{< ref
4748
"2019-09/applicator/patternproperties" >}}) keywords (if any), to validate
4849
against the given subschema. Information about the properties that this keyword

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

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -41,11 +41,11 @@ subschema (the intersection of the constraints).
4141
anti-pattern.
4242

4343
This practice has historical roots. In JSON Schema [Draft 7](/draft7) and
44-
earlier versions, any subschema declaring the `$ref` keyword was considered
45-
to be a _reference object_ and any other sibling keyword was silently ignored.
46-
As a consequence, subschemas with references that made use of other keywords
47-
had to artificially wrap the reference into its own subschema.
48-
{{</common-pitfall>}}
44+
earlier versions, any subschema declaring the [`$ref`]({{< ref
45+
"2019-09/core/ref" >}}) keyword was considered to be a _reference object_ and
46+
any other sibling keyword was silently ignored. As a consequence, subschemas
47+
with references that made use of other keywords had to artificially wrap the
48+
reference into its own subschema. {{</common-pitfall>}}
4949

5050
{{<best-practice>}}This keyword typically has a single use case: combining
5151
_multiple_ schemas through the use of (internal or external) references. If

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -32,12 +32,12 @@ related:
3232
keyword: unevaluatedItems
3333
---
3434

35-
The `contains` keyword restricts array instances to include one or more items
36-
(at any location of the array) that validate against the given subschema. The
37-
lower and upper bounds that are allowed to validate against the given subschema
38-
can be controlled using the [`minContains`]({{< ref
39-
"2019-09/validation/mincontains" >}}) and [`maxContains`]({{< ref
40-
"2019-09/validation/maxcontains" >}}) keywords.
35+
The [`contains`]({{< ref "2019-09/applicator/contains" >}}) keyword restricts
36+
array instances to include one or more items (at any location of the array) that
37+
validate against the given subschema. The lower and upper bounds that are
38+
allowed to validate against the given subschema can be controlled using the
39+
[`minContains`]({{< ref "2019-09/validation/mincontains" >}}) and
40+
[`maxContains`]({{< ref "2019-09/validation/maxcontains" >}}) keywords.
4141

4242
{{<constraint-warning `array`>}}
4343

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

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,11 @@ related:
2020
keyword: dependentRequired
2121
---
2222

23-
The `dependentSchemas` keyword restricts object instances to validate against
24-
one or more of the given subschemas if the corresponding properties are
25-
defined. Note that the given subschemas are evaluated against the object
26-
that defines the property dependency.
23+
The [`dependentSchemas`]({{< ref "2019-09/applicator/dependentschemas" >}})
24+
keyword restricts object instances to validate against one or more of the given
25+
subschemas if the corresponding properties are defined. Note that the given
26+
subschemas are evaluated against the object that defines the property
27+
dependency.
2728

2829
{{<learning-more>}}The [`dependentRequired`]({{< ref
2930
"2019-09/validation/dependentrequired" >}}) keyword is a specialisation of

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

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -39,11 +39,12 @@ instance.
3939
subschema. {{</common-pitfall>}}
4040

4141
{{<best-practice>}} The [`if`]({{< ref "2019-09/applicator/if" >}}),
42-
[`then`]({{< ref "2019-09/applicator/then" >}}), and `else` keywords can be
43-
thought of as imperative variants of the [`anyOf`]({{< ref
44-
"2019-09/applicator/anyof" >}}) keyword, and both approaches are equally
45-
capable of describing arbitrary conditions. Choose the one that more elegantly
46-
describes your desired constraints.{{</best-practice>}}
42+
[`then`]({{< ref "2019-09/applicator/then" >}}), and [`else`]({{< ref
43+
"2019-09/applicator/else" >}}) keywords can be thought of as imperative
44+
variants of the [`anyOf`]({{< ref "2019-09/applicator/anyof" >}}) keyword,
45+
and both approaches are equally capable of describing arbitrary conditions.
46+
Choose the one that more elegantly describes your desired
47+
constraints.{{</best-practice>}}
4748

4849
## Examples
4950

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

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -34,19 +34,20 @@ vocabulary="applicator">}} sibling subschemas (if present). Note that the
3434
evaluation outcome of this subschema controls which other subschema to apply
3535
(if any) but has no direct effect on the overall validation result.
3636

37-
{{<best-practice>}} The `if`, [`then`]({{< ref "2019-09/applicator/then"
38-
>}}), and [`else`]({{< ref "2019-09/applicator/else" >}}) keywords can be
39-
thought of as imperative variants of the [`anyOf`]({{< ref
40-
"2019-09/applicator/anyof" >}}) keyword, and both approaches are equally
41-
capable of describing arbitrary conditions. Choose the one that more elegantly
42-
describes your desired constraints.{{</best-practice>}}
37+
{{<best-practice>}} The [`if`]({{< ref "2019-09/applicator/if" >}}),
38+
[`then`]({{< ref "2019-09/applicator/then" >}}), and [`else`]({{< ref
39+
"2019-09/applicator/else" >}}) keywords can be thought of as imperative variants
40+
of the [`anyOf`]({{< ref "2019-09/applicator/anyof" >}}) keyword, and both
41+
approaches are equally capable of describing arbitrary conditions. Choose the
42+
one that more elegantly describes your desired
43+
constraints.{{</best-practice>}}
4344

4445
{{<learning-more>}} This keyword has no effect if neither the [`then`]({{< ref
4546
"2019-09/applicator/then" >}}) nor [`else`]({{< ref
4647
"2019-09/applicator/else" >}}) keywords are declared within the same subschema.
4748
However, when collecting annotations, the JSON Schema implementation will still
48-
need to evaluate the `if` keyword in case its subschema emits annotations.
49-
{{</learning-more>}}
49+
need to evaluate the [`if`]({{< ref "2019-09/applicator/if" >}}) keyword in
50+
case its subschema emits annotations. {{</learning-more>}}
5051

5152
The {{<link keyword="if" vocabulary="applicator">}}, {{<link keyword="then"
5253
vocabulary="applicator">}}, and {{<link keyword="else"

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

Lines changed: 18 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -42,21 +42,24 @@ related:
4242
keyword: unevaluatedItems
4343
---
4444

45-
The `items` keyword is used to validate array items and has two different modes
46-
of operation depending on its value:
47-
48-
**Schema Form**: When set to a schema, `items` validates that all items in
49-
the array instance validate against the given subschema. Whether this keyword
50-
was evaluated against any item of the array instance is reported using
51-
annotations.
52-
53-
**Array Form**: When set to an array of schemas, `items` validates each item
54-
in the array instance against the subschema at the corresponding position
55-
(tuple validation). Items beyond the length of the `items` array can be
56-
validated using the [`additionalItems`]({{< ref
57-
"2019-09/applicator/additionalitems" >}}) keyword. The annotation reports the
58-
largest index to which a subschema was applied, or true if it was applied to
59-
every item.
45+
The [`items`]({{< ref "2019-09/applicator/items" >}}) keyword is used to
46+
validate array items and has two different modes of operation depending on the
47+
type of its value:
48+
49+
- **Schema**: When set to a schema, [`items`]({{< ref
50+
"2019-09/applicator/items" >}}) validates that all items in the array
51+
instance validate against the given subschema. Whether this keyword was
52+
evaluated against any item of the array instance is reported using
53+
annotations.
54+
55+
- **Array**: When set to an array of schemas, [`items`]({{< ref
56+
"2019-09/applicator/items" >}}) validates each item in the array instance
57+
against the subschema at the corresponding position. Items beyond the length
58+
of the [`items`]({{< ref "2019-09/applicator/items" >}}) array can be
59+
validated using the [`additionalItems`]({{< ref
60+
"2019-09/applicator/additionalitems" >}}) keyword. The annotation reports the
61+
largest index to which a subschema was applied, or `true` if it was applied
62+
to every item.
6063

6164
{{<common-pitfall>}}This keyword does not prevent an array instance from being
6265
empty. If needed, use the [`minItems`]({{< ref "2019-09/validation/minitems"
@@ -66,8 +69,6 @@ empty. If needed, use the [`minItems`]({{< ref "2019-09/validation/minitems"
6669

6770
## Examples
6871

69-
### Schema Form
70-
7172
{{<schema `A schema that constrains array instances to consist of number items`>}}
7273
{
7374
"$schema": "https://json-schema.org/draft/2019-09/schema",
@@ -95,8 +96,6 @@ empty. If needed, use the [`minItems`]({{< ref "2019-09/validation/minitems"
9596
"Hello World"
9697
{{</instance-pass>}}
9798

98-
### Array Form (Tuple Validation)
99-
10099
{{<schema `A schema that constrains array instances to start with a boolean item followed by a number item`>}}
101100
{
102101
"$schema": "https://json-schema.org/draft/2019-09/schema",
@@ -136,8 +135,6 @@ empty. If needed, use the [`minItems`]({{< ref "2019-09/validation/minitems"
136135
"Hello World"
137136
{{</instance-pass>}}
138137

139-
### Array Form with additionalItems
140-
141138
{{<schema `A schema that constrains array instances to start with a boolean item followed by a number item, with only string items allowed beyond that`>}}
142139
{
143140
"$schema": "https://json-schema.org/draft/2019-09/schema",

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

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,8 +48,9 @@ might seem counter-intuitive, consider the following cases:
4848
{{<best-practice>}} Avoid the use of this keyword (usually negating the
4949
[`required`]({{< ref "2019-09/validation/required" >}}) keyword) to prohibit
5050
specific object properties from being defined. Instead, use the
51-
[`properties`]({{< ref "properties" >}}) keyword and set the disallowed object
52-
properties to the `false` boolean schema.{{</best-practice>}}
51+
[`properties`]({{< ref "2019-09/applicator/properties" >}}) keyword and set
52+
the disallowed object properties to the `false` boolean
53+
schema.{{</best-practice>}}
5354

5455
This keyword is equivalent to the `!` operator found in most programming
5556
languages. For example:

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

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -42,10 +42,11 @@ related:
4242
keyword: unevaluatedProperties
4343
---
4444

45-
The `patternProperties` keyword restricts properties of an object instance that
46-
match certain regular expressions to match their corresponding subschemas
47-
definitions. Information about the properties that this keyword was evaluated
48-
for is reported using annotations.
45+
The [`patternProperties`]({{< ref "2019-09/applicator/patternproperties" >}})
46+
keyword restricts properties of an object instance that match certain regular
47+
expressions to match their corresponding subschemas definitions. Information
48+
about the properties that this keyword was evaluated for is reported using
49+
annotations.
4950

5051
{{<common-pitfall>}} This keyword is evaluated independently of the
5152
[`properties`]({{< ref "2019-09/applicator/properties" >}}) keyword. If an

0 commit comments

Comments
 (0)