|
63 | 63 |
|
64 | 64 | <abstract> |
65 | 65 | <t> |
66 | | - JSON Schema (application/schema+json) has several purposes, one of which is instance |
67 | | - validation. The validation process may be interactive or non-interactive. For |
68 | | - instance, applications may use JSON Schema to build a user interface enabling |
69 | | - interactive content generation in addition to user input checking, or validate data |
70 | | - retrieved from various sources. This specification describes schema keywords |
71 | | - dedicated to validation purposes. |
| 66 | + JSON Schema (application/schema+json) has several purposes, one of which is JSON instance |
| 67 | + validation. This document specifies a vocabulary for JSON Schema to makes assertions about |
| 68 | + valid instances. |
72 | 69 | </t> |
73 | 70 | </abstract> |
74 | 71 | </front> |
|
77 | 74 | <section title="Introduction"> |
78 | 75 | <t> |
79 | 76 | JSON Schema can be used to require that a given JSON document (an instance) |
80 | | - satisfies a certain number of criteria. These criteria are materialized by a set of |
81 | | - keywords which are described in this specification. In addition, a set of keywords |
82 | | - is defined to assist in interactive instance generation. Those are also described in |
83 | | - this specification. |
| 77 | + satisfies a certain number of criteria. These criteria are asserted by using |
| 78 | + keywords described in this specification. In addition, a set of keywords |
| 79 | + is also defined to assist in interactive, user interface instance generation. |
84 | 80 | </t> |
85 | | - |
86 | 81 | <t> |
87 | | - This specification will use the terminology defined by the JSON Schema core |
88 | | - specification. It is advised that readers have a copy of this specification. |
| 82 | + This specification will use the terminology defined by the |
| 83 | + <xreftarget="json-schema-core">JSON Schema core</xref> specification. |
89 | 84 | </t> |
90 | | - |
91 | 85 | </section> |
92 | 86 |
|
93 | 87 | <section title="Conventions and Terminology"> |
|
99 | 93 | "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be |
100 | 94 | interpreted as described in <xref target="RFC2119">RFC 2119</xref>. |
101 | 95 | </t> |
102 | | - |
103 | 96 | <t> |
104 | 97 | This specification uses the term "container instance" to refer to both array and |
105 | 98 | object instances. It uses the term "children instances" to refer to array elements |
106 | 99 | or object member values. |
107 | 100 | </t> |
108 | | - |
109 | 101 | <t> |
110 | 102 | This specification uses the term "property set" to refer to the set of an object's |
111 | 103 | member names; for instance, the property set of JSON Object { "a": 1, "b": 2 } is [ |
112 | 104 | "a", "b" ]. |
113 | 105 | </t> |
114 | | - |
115 | 106 | <t> |
116 | 107 | Elements in an array value are said to be unique if no two elements of this array |
117 | 108 | are equal, as defined by the core specification. |
|
121 | 112 | <section title="Interoperability considerations"> |
122 | 113 |
|
123 | 114 | <section title="Validation of string instances"> |
124 | | - |
125 | 115 | <t> |
126 | | - It should be noted that the nul character (\x00) is valid in a JSON string. An |
| 116 | + It should be noted that the nul character (\u0000) is valid in a JSON string. An |
127 | 117 | instance to validate may contain a string value with this character, regardless |
128 | 118 | of the ability of the underlying programming language to deal with such data. |
129 | 119 | </t> |
130 | | - |
131 | 120 | </section> |
132 | 121 |
|
133 | 122 | <section title="Validation of numeric instances"> |
134 | | - |
135 | 123 | <t> |
136 | | - The JSON specification does not define any bounds to the scale or precision of |
137 | | - numeric values. JSON Schema does not define any such bounds either. This means |
138 | | - that numeric instances processed by JSON Schema can be arbitrarily large and/or |
| 124 | + The JSON specification allows numbers with arbritrary prevision, and JSON Schema does not add any such bounds. |
| 125 | + This means that numeric instances processed by JSON Schema can be arbitrarily large and/or |
139 | 126 | have an arbitrarily large decimal part, regardless of the ability of the |
140 | 127 | underlying programming language to deal with such data. |
141 | 128 | </t> |
142 | | - |
143 | 129 | </section> |
144 | 130 |
|
145 | 131 | <section title="Regular expressions"> |
146 | | - |
147 | 132 | <t> |
148 | 133 | Two validation keywords, "pattern" and "patternProperties", use regular |
149 | 134 | expressions to express constraints. These regular expressions SHOULD |
150 | 135 | be valid according to the <xref target="ecma262">ECMA 262</xref> regular |
151 | 136 | expression dialect. |
152 | 137 | </t> |
153 | | - |
154 | 138 | <t> |
155 | 139 | Furthermore, given the high disparity in regular expression constructs support, |
156 | 140 | schema authors SHOULD limit themselves to the following regular expression |
|
170 | 154 | <t>simple grouping ("(...)") and alternation ("|").</t> |
171 | 155 | </list> |
172 | 156 | </t> |
173 | | - |
174 | 157 | <t> |
175 | 158 | Finally, implementations MUST NOT consider that regular expressions are |
176 | 159 | anchored, neither at the beginning nor at the end. This means, for instance, |
177 | 160 | that "es" matches "expression". |
178 | 161 | </t> |
179 | | - |
180 | 162 | </section> |
181 | 163 |
|
182 | 164 | </section> |
|
185 | 167 |
|
186 | 168 | <section title="Keywords and instance primitive types"> |
187 | 169 | <t> |
188 | | - Some validation keywords only apply to one or more primitive types. When the |
189 | | - primitive type of the instance cannot be validated by a given keyword, |
190 | | - validation for this keyword and instance SHOULD succeed. |
| 170 | + Most validation keywords only limit the range of values within a certain primitive type. |
| 171 | + When the primitive type of the instance is not of the type targeted by the keyword, the |
| 172 | + validation succeeds. |
191 | 173 | </t> |
192 | 174 | <t> |
193 | | - This specification groups keywords in different sections, according to the |
194 | | - primitive type, or types, these keywords validate. Note that some keywords |
195 | | - validate all instance types. |
| 175 | + For example, the "maxLength" keyword will only restrict certain strings that are too long from being valid. |
| 176 | + If the instance is a number, boolean, null, array, or object, the keyword passes validation. |
196 | 177 | </t> |
197 | 178 | </section> |
198 | 179 |
|
199 | 180 | <section title="Default values for missing keywords"> |
200 | 181 | <t> |
201 | | - Some keywords, if absent, MAY be regarded by implementations as having |
202 | | - a default value. In this case, the default value will be mentioned. |
203 | | - </t> |
204 | | - </section> |
205 | | - |
206 | | - <section title="Validation of container instances"> |
207 | | - <t> |
208 | | - Keywords with the possibility to validate container instances (arrays or |
209 | | - objects) only validate the instances themselves and not their children (array |
210 | | - items or object properties). Some of these keywords do, however, contain |
211 | | - information which is necessary for calculating which schema(s) a child must be |
212 | | - valid against. The algorithms to calculate a child instance's relevant schema(s) |
213 | | - are explained in a separate section. |
214 | | - </t> |
215 | | - <t> |
216 | | - It should be noted that while an array element will only have to validate |
217 | | - against one schema, object member values may have to validate against more than |
218 | | - one schema. |
| 182 | + Validation keywords that are missing never restrict validation. |
| 183 | + In some cases, this behavior is identical to certain values that also are no-op. |
| 184 | + Since these values can be safely ignored or removed, they are noted where known. |
219 | 185 | </t> |
220 | 186 | </section> |
221 | 187 |
|
|
790 | 756 | <!-- References Section --> |
791 | 757 | <references title="Normative References"> |
792 | 758 | &RFC2119; |
| 759 | + <reference anchor="json-schema-core"> |
| 760 | + <front> |
| 761 | + <title>JSON Schema: core definitions and terminology</title> |
| 762 | + <author/> |
| 763 | + <date year="2016" month="September"/> |
| 764 | + </front> |
| 765 | + </reference> |
793 | 766 | </references> |
794 | 767 |
|
795 | 768 | <references title="Informative References"> |
|
0 commit comments