Skip to content

Commit b739315

Browse files
jviottijviotti
authored
Expand additionalProperties docs to every dialect (#296)
Signed-off-by: Juan Cruz Viotti <[email protected]>
1 parent c46b35f commit b739315

File tree

5 files changed

+618
-1
lines changed

5 files changed

+618
-1
lines changed

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

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,3 +40,140 @@ related:
4040
- vocabulary: applicator
4141
keyword: unevaluatedProperties
4242
---
43+
44+
The `additionalProperties` keyword restricts object instance properties not
45+
described by the _sibling_ [`properties`]({{< ref
46+
"2019-09/applicator/properties"
47+
>}}) and [`patternProperties`]({{< ref "2019-09/applicator/patternproperties"
48+
>}}) keywords (if any), to validate against the given subschema. Information
49+
about the properties that this keyword was evaluated for is reported using
50+
annotations.
51+
52+
{{<common-pitfall>}}The use of the [`properties`]({{< ref
53+
"2019-09/applicator/properties" >}}) keyword **does not prevent the presence of
54+
other properties** in the object instance and **does not enforce the presence
55+
of the declared properties**. In other words, additional data that is not
56+
explicitly prohibited is permitted by default. This is intended behaviour to
57+
ease schema evolution (open schemas are backwards compatible by default) and to
58+
enable highly-expressive constraint-driven schemas.
59+
60+
If you want to restrict instances to only contain the properties you declared,
61+
you must set this keyword to the boolean schema `false`, and if you want to
62+
enforce the presence of certain properties, you must use the [`required`]({{<
63+
ref "2019-09/validation/required" >}}) keyword accordingly.
64+
{{</common-pitfall>}}
65+
66+
{{<learning-more>}}While the most common use of this keyword is setting it to
67+
the boolean schema `false` to prevent additional properties, it is possible to
68+
set it to a satisfiable schema. Doing this, while omitting the
69+
[`properties`]({{< ref "2019-09/applicator/properties" >}}) and
70+
[`patternProperties`]({{< ref "2019-09/applicator/patternproperties" >}})
71+
keywords, is an elegant way of describing how the value of every property in
72+
the object instance must look like independently of its
73+
name.{{</learning-more>}}
74+
75+
{{<constraint-warning `object`>}}
76+
77+
## Examples
78+
79+
{{<schema `A schema that constrains object instances to not define additional properties`>}}
80+
{
81+
"$schema": "https://json-schema.org/draft/2019-09/schema",
82+
"properties": {
83+
"foo": { "type": "string" }
84+
},
85+
"patternProperties": {
86+
"^x-": { "type": "integer" }
87+
},
88+
"additionalProperties": false
89+
}
90+
{{</schema>}}
91+
92+
{{<instance-pass `An object value that defines properties that only match static and regular expression definitions is valid`>}}
93+
{ "foo": "bar", "x-test": 2 }
94+
{{</instance-pass>}}
95+
96+
{{<instance-annotation>}}
97+
{ "keyword": "/properties", "instance": "", "value": [ "foo" ] }
98+
{ "keyword": "/patternProperties", "instance": "", "value": [ "x-test" ] }
99+
{{</instance-annotation>}}
100+
101+
{{<instance-fail `An object value that defines valid properties and also defines additional properties is invalid`>}}
102+
{ "foo": "bar", "x-test": 2, "extra": true }
103+
{{</instance-fail>}}
104+
105+
{{<instance-fail `An object value that only defines additional properties is invalid`>}}
106+
{ "extra": true, "random": 1234 }
107+
{{</instance-fail>}}
108+
109+
{{<instance-pass `An empty object value is valid`>}}
110+
{}
111+
{{</instance-pass>}}
112+
113+
{{<instance-pass `A non-object value is valid`>}}
114+
"Hello World"
115+
{{</instance-pass>}}
116+
117+
{{<schema `A schema that constrains object instances to only define integer properties`>}}
118+
{
119+
"$schema": "https://json-schema.org/draft/2019-09/schema",
120+
"additionalProperties": { "type": "integer" }
121+
}
122+
{{</schema>}}
123+
124+
{{<instance-pass `An object value that only defines integer properties is valid`>}}
125+
{ "foo": 1, "bar": 2, "baz": 3 }
126+
{{</instance-pass>}}
127+
128+
{{<instance-annotation>}}
129+
{ "keyword": "/additionalProperties", "instance": "", "value": [ "foo", "bar", "baz" ] }
130+
{{</instance-annotation>}}
131+
132+
{{<instance-fail `An object value that defines at least one non-integer property is invalid`>}}
133+
{ "foo": 1, "name": "John Doe" }
134+
{{</instance-fail>}}
135+
136+
{{<instance-pass `An empty object value is valid`>}}
137+
{}
138+
{{</instance-pass>}}
139+
140+
{{<instance-pass `A non-object value is valid`>}}
141+
"Hello World"
142+
{{</instance-pass>}}
143+
144+
{{<schema `A schema that constrains object instances to define boolean additional properties`>}}
145+
{
146+
"$schema": "https://json-schema.org/draft/2019-09/schema",
147+
"properties": {
148+
"foo": { "type": "string" }
149+
},
150+
"patternProperties": {
151+
"^x-": { "type": "integer" }
152+
},
153+
"additionalProperties": {
154+
"type": "boolean"
155+
}
156+
}
157+
{{</schema>}}
158+
159+
{{<instance-pass `An object value that defines valid properties and boolean additional properties is valid`>}}
160+
{ "foo": "bar", "x-test": 2, "extra": true }
161+
{{</instance-pass>}}
162+
163+
{{<instance-annotation>}}
164+
{ "keyword": "/properties", "instance": "", "value": [ "foo" ] }
165+
{ "keyword": "/patternProperties", "instance": "", "value": [ "x-test" ] }
166+
{ "keyword": "/additionalProperties", "instance": "", "value": [ "extra" ] }
167+
{{</instance-annotation>}}
168+
169+
{{<instance-fail `An object value that defines valid properties and also defines non-boolean additional properties is invalid`>}}
170+
{ "foo": "bar", "x-test": 2, "extra": "should be a boolean" }
171+
{{</instance-fail>}}
172+
173+
{{<instance-pass `An empty object value is valid`>}}
174+
{}
175+
{{</instance-pass>}}
176+
177+
{{<instance-pass `A non-object value is valid`>}}
178+
"Hello World"
179+
{{</instance-pass>}}

‎content/draft3/core/additionalProperties.markdown‎

Lines changed: 121 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
keyword: "additionalProperties"
33
signature: "Schema | Boolean"
44
value: This keyword must be set to a valid JSON Schema
5-
summary: "Validation succeeds if the schema validates against each value not matched by other object applicators in this vocabulary. If set to a boolean, no additional properties are allowed in the instance."
5+
summary: "Validation succeeds if the schema validates against each value not matched by other object applicators in this vocabulary. If set to `false`, no additional properties are allowed in the instance."
66
kind: [ "applicator" ]
77
instance: [ "object" ]
88
specification: "https://json-schema.org/draft-03/draft-zyp-json-schema-03.pdf#5.4"
@@ -24,3 +24,123 @@ related:
2424
- vocabulary: core
2525
keyword: required
2626
---
27+
28+
The `additionalProperties` keyword restricts object instance properties not
29+
described by the _sibling_ [`properties`]({{< ref
30+
"draft3/core/properties"
31+
>}}) and [`patternProperties`]({{< ref "draft3/core/patternproperties"
32+
>}}) keywords (if any), to validate against the given subschema.
33+
34+
{{<common-pitfall>}}The use of the [`properties`]({{< ref
35+
"draft3/core/properties" >}}) keyword **does not prevent the presence of
36+
other properties** in the object instance and **does not enforce the presence
37+
of the declared properties**. In other words, additional data that is not
38+
explicitly prohibited is permitted by default. This is intended behaviour to
39+
ease schema evolution (open schemas are backwards compatible by default) and to
40+
enable highly-expressive constraint-driven schemas.
41+
42+
If you want to restrict instances to only contain the properties you declared,
43+
you must set this keyword to the boolean schema `false`, and if you want to
44+
enforce the presence of certain properties, you must use the [`required`]({{<
45+
ref "draft3/core/required" >}}) keyword accordingly.
46+
{{</common-pitfall>}}
47+
48+
{{<learning-more>}}While the most common use of this keyword is setting it to
49+
the boolean schema `false` to prevent additional properties, it is possible to
50+
set it to a satisfiable schema. Doing this, while omitting the
51+
[`properties`]({{< ref "draft3/core/properties" >}}) and
52+
[`patternProperties`]({{< ref "draft3/core/patternproperties" >}})
53+
keywords, is an elegant way of describing how the value of every property in
54+
the object instance must look like independently of its
55+
name.{{</learning-more>}}
56+
57+
{{<constraint-warning `object`>}}
58+
59+
## Examples
60+
61+
{{<schema `A schema that constrains object instances to not define additional properties`>}}
62+
{
63+
"$schema": "http://json-schema.org/draft-03/schema#",
64+
"properties": {
65+
"foo": { "type": "string" }
66+
},
67+
"patternProperties": {
68+
"^x-": { "type": "integer" }
69+
},
70+
"additionalProperties": false
71+
}
72+
{{</schema>}}
73+
74+
{{<instance-pass `An object value that defines properties that only match static and regular expression definitions is valid`>}}
75+
{ "foo": "bar", "x-test": 2 }
76+
{{</instance-pass>}}
77+
78+
{{<instance-fail `An object value that defines valid properties and also defines additional properties is invalid`>}}
79+
{ "foo": "bar", "x-test": 2, "extra": true }
80+
{{</instance-fail>}}
81+
82+
{{<instance-fail `An object value that only defines additional properties is invalid`>}}
83+
{ "extra": true, "random": 1234 }
84+
{{</instance-fail>}}
85+
86+
{{<instance-pass `An empty object value is valid`>}}
87+
{}
88+
{{</instance-pass>}}
89+
90+
{{<instance-pass `A non-object value is valid`>}}
91+
"Hello World"
92+
{{</instance-pass>}}
93+
94+
{{<schema `A schema that constrains object instances to only define integer properties`>}}
95+
{
96+
"$schema": "http://json-schema.org/draft-03/schema#",
97+
"additionalProperties": { "type": "integer" }
98+
}
99+
{{</schema>}}
100+
101+
{{<instance-pass `An object value that only defines integer properties is valid`>}}
102+
{ "foo": 1, "bar": 2, "baz": 3 }
103+
{{</instance-pass>}}
104+
105+
{{<instance-fail `An object value that defines at least one non-integer property is invalid`>}}
106+
{ "foo": 1, "name": "John Doe" }
107+
{{</instance-fail>}}
108+
109+
{{<instance-pass `An empty object value is valid`>}}
110+
{}
111+
{{</instance-pass>}}
112+
113+
{{<instance-pass `A non-object value is valid`>}}
114+
"Hello World"
115+
{{</instance-pass>}}
116+
117+
{{<schema `A schema that constrains object instances to define boolean additional properties`>}}
118+
{
119+
"$schema": "http://json-schema.org/draft-03/schema#",
120+
"properties": {
121+
"foo": { "type": "string" }
122+
},
123+
"patternProperties": {
124+
"^x-": { "type": "integer" }
125+
},
126+
"additionalProperties": {
127+
"type": "boolean"
128+
}
129+
}
130+
{{</schema>}}
131+
132+
{{<instance-pass `An object value that defines valid properties and boolean additional properties is valid`>}}
133+
{ "foo": "bar", "x-test": 2, "extra": true }
134+
{{</instance-pass>}}
135+
136+
{{<instance-fail `An object value that defines valid properties and also defines non-boolean additional properties is invalid`>}}
137+
{ "foo": "bar", "x-test": 2, "extra": "should be a boolean" }
138+
{{</instance-fail>}}
139+
140+
{{<instance-pass `An empty object value is valid`>}}
141+
{}
142+
{{</instance-pass>}}
143+
144+
{{<instance-pass `A non-object value is valid`>}}
145+
"Hello World"
146+
{{</instance-pass>}}

‎content/draft4/validation/additionalProperties.markdown‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,3 +28,123 @@ related:
2828
- vocabulary: validation
2929
keyword: maxProperties
3030
---
31+
32+
The `additionalProperties` keyword restricts object instance properties not
33+
described by the _sibling_ [`properties`]({{< ref
34+
"draft4/validation/properties"
35+
>}}) and [`patternProperties`]({{< ref "draft4/validation/patternproperties"
36+
>}}) keywords (if any), to validate against the given subschema.
37+
38+
{{<common-pitfall>}}The use of the [`properties`]({{< ref
39+
"draft4/validation/properties" >}}) keyword **does not prevent the presence of
40+
other properties** in the object instance and **does not enforce the presence
41+
of the declared properties**. In other words, additional data that is not
42+
explicitly prohibited is permitted by default. This is intended behaviour to
43+
ease schema evolution (open schemas are backwards compatible by default) and to
44+
enable highly-expressive constraint-driven schemas.
45+
46+
If you want to restrict instances to only contain the properties you declared,
47+
you must set this keyword to the boolean schema `false`, and if you want to
48+
enforce the presence of certain properties, you must use the [`required`]({{<
49+
ref "draft4/validation/required" >}}) keyword accordingly.
50+
{{</common-pitfall>}}
51+
52+
{{<learning-more>}}While the most common use of this keyword is setting it to
53+
the boolean schema `false` to prevent additional properties, it is possible to
54+
set it to a satisfiable schema. Doing this, while omitting the
55+
[`properties`]({{< ref "draft4/validation/properties" >}}) and
56+
[`patternProperties`]({{< ref "draft4/validation/patternproperties" >}})
57+
keywords, is an elegant way of describing how the value of every property in
58+
the object instance must look like independently of its
59+
name.{{</learning-more>}}
60+
61+
{{<constraint-warning `object`>}}
62+
63+
## Examples
64+
65+
{{<schema `A schema that constrains object instances to not define additional properties`>}}
66+
{
67+
"$schema": "http://json-schema.org/draft-04/schema#",
68+
"properties": {
69+
"foo": { "type": "string" }
70+
},
71+
"patternProperties": {
72+
"^x-": { "type": "integer" }
73+
},
74+
"additionalProperties": false
75+
}
76+
{{</schema>}}
77+
78+
{{<instance-pass `An object value that defines properties that only match static and regular expression definitions is valid`>}}
79+
{ "foo": "bar", "x-test": 2 }
80+
{{</instance-pass>}}
81+
82+
{{<instance-fail `An object value that defines valid properties and also defines additional properties is invalid`>}}
83+
{ "foo": "bar", "x-test": 2, "extra": true }
84+
{{</instance-fail>}}
85+
86+
{{<instance-fail `An object value that only defines additional properties is invalid`>}}
87+
{ "extra": true, "random": 1234 }
88+
{{</instance-fail>}}
89+
90+
{{<instance-pass `An empty object value is valid`>}}
91+
{}
92+
{{</instance-pass>}}
93+
94+
{{<instance-pass `A non-object value is valid`>}}
95+
"Hello World"
96+
{{</instance-pass>}}
97+
98+
{{<schema `A schema that constrains object instances to only define integer properties`>}}
99+
{
100+
"$schema": "http://json-schema.org/draft-04/schema#",
101+
"additionalProperties": { "type": "integer" }
102+
}
103+
{{</schema>}}
104+
105+
{{<instance-pass `An object value that only defines integer properties is valid`>}}
106+
{ "foo": 1, "bar": 2, "baz": 3 }
107+
{{</instance-pass>}}
108+
109+
{{<instance-fail `An object value that defines at least one non-integer property is invalid`>}}
110+
{ "foo": 1, "name": "John Doe" }
111+
{{</instance-fail>}}
112+
113+
{{<instance-pass `An empty object value is valid`>}}
114+
{}
115+
{{</instance-pass>}}
116+
117+
{{<instance-pass `A non-object value is valid`>}}
118+
"Hello World"
119+
{{</instance-pass>}}
120+
121+
{{<schema `A schema that constrains object instances to define boolean additional properties`>}}
122+
{
123+
"$schema": "http://json-schema.org/draft-04/schema#",
124+
"properties": {
125+
"foo": { "type": "string" }
126+
},
127+
"patternProperties": {
128+
"^x-": { "type": "integer" }
129+
},
130+
"additionalProperties": {
131+
"type": "boolean"
132+
}
133+
}
134+
{{</schema>}}
135+
136+
{{<instance-pass `An object value that defines valid properties and boolean additional properties is valid`>}}
137+
{ "foo": "bar", "x-test": 2, "extra": true }
138+
{{</instance-pass>}}
139+
140+
{{<instance-fail `An object value that defines valid properties and also defines non-boolean additional properties is invalid`>}}
141+
{ "foo": "bar", "x-test": 2, "extra": "should be a boolean" }
142+
{{</instance-fail>}}
143+
144+
{{<instance-pass `An empty object value is valid`>}}
145+
{}
146+
{{</instance-pass>}}
147+
148+
{{<instance-pass `A non-object value is valid`>}}
149+
"Hello World"
150+
{{</instance-pass>}}

0 commit comments

Comments
 (0)