You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Nov 2, 2023. It is now read-only.
<p>The latest IETF published draft is <ahref="http://tools.ietf.org/html/draft-zyp-json-schema-03">v3</a>. However, a newer version of the specification is being prepared for submission in early 2013.
<p>Let's pretend we're interacting with a JSON based product catalog. This catalog has a product which has an <em>id</em>, a <em>name</em>, a <em>price</em>, and an optional set of <em>tags</em>.
22
-
</p>
1
+
<h2>Example data</h2>
2
+
<divclass="block">
3
+
<p>Let's pretend we're interacting with a JSON based product catalog. This catalog has a product which has an <em>id</em>, a <em>name</em>, a <em>price</em>, and an optional set of <em>tags</em>.</p>
23
4
24
-
<h3>Example JSON data for a product API</h3>
25
-
<p>An example product in this API is:</p>
5
+
<h3>Example JSON data for a product API</h3>
6
+
<p>An example product in this API is:</p>
26
7
27
8
<preclass="json">
28
9
{
@@ -33,18 +14,21 @@ <h3>Example JSON data for a product API</h3>
33
14
}
34
15
</pre>
35
16
36
-
<p>While generally straightforward, that example leaves some open questions. For example, one may ask:</p>
17
+
<p>While generally straightforward, that example leaves some open questions. For example, one may ask:</p>
18
+
19
+
<ul>
20
+
<li>What is id?</li>
21
+
<li>Is name required?</li>
22
+
<li>Can price be 0?</li>
23
+
<li>Are all tags strings?</li>
24
+
</ul>
37
25
38
-
<ul>
39
-
<li>What is id?</li>
40
-
<li>Is name required?</li>
41
-
<li>Can price be 0?</li>
42
-
<li>Are all tags strings?</li>
43
-
</ul>
26
+
<p>When you're talking about a data format, you want to have metadata about what fields mean, and what valid inputs for those fields are. JSON schema is a specification for standardizing how to answer those questions for JSON data.</p>
27
+
</div>
44
28
45
-
<p>When you're talking about a data format, you want to have metadata about what fields mean, and what valid inputs for those fields are. JSON schema is a specification for standardizing how to answer those questions for JSON data.</p>
46
-
<h3>Example schema for the product API</h3>
47
-
<p>To start a schema definition, let's begin with a basic JSON schema:</p>
29
+
<h2>Starting the schema</h2>
30
+
<divclass="block">
31
+
<p>To start a schema definition, let's begin with a basic JSON schema:</p>
48
32
49
33
<preclass="json-schema">
50
34
{
@@ -55,24 +39,27 @@ <h3>Example schema for the product API</h3>
55
39
}
56
40
</pre>
57
41
58
-
<p>The above schema has four properties called <em>keywords</em>.
42
+
<p>The above schema has four properties called <em>keywords</em>.
59
43
60
-
The <em>title</em> and <em>description</em> keywords are descriptive only, in that they do not add
61
-
constraints to the data being validated. The intent of the schema is stated with these two keywords
62
-
(that is, this schema describes a product).</p>
44
+
The <em>title</em> and <em>description</em> keywords are descriptive only, in that they do not add
45
+
constraints to the data being validated. The intent of the schema is stated with these two keywords
46
+
(that is, this schema describes a product).</p>
63
47
64
-
<p>The <em>type</em> keyword defines the first constraint on our JSON data: it has to be a JSON
65
-
Object.</p>
48
+
<p>The <em>type</em> keyword defines the first constraint on our JSON data: it has to be a JSON
49
+
Object.</p>
66
50
67
-
<p>Finally, the <em>$schema</em> keyword states that this schema is written according to the draft
68
-
v4 specification.</p>
51
+
<p>Finally, the <em>$schema</em> keyword states that this schema is written according to the draft
52
+
v4 specification.</p>
53
+
</div>
69
54
70
-
<p>Next let's answer our previous questions about this API, starting with id.</p>
55
+
<h2>Defining the properties</h2>
56
+
<divclass="block">
57
+
<p>Next let's answer our previous questions about this API, starting with id.</p>
71
58
72
-
<h4>What is id?</h4>
73
-
<p><em>id</em> is a numeric value that uniquely identifies a product. Since this is the canonical identifier for a product, it doesn't make sense to have a product without one, so it is required.</p>
59
+
<h3>What is id?</h3>
60
+
<p><em>id</em> is a numeric value that uniquely identifies a product. Since this is the canonical identifier for a product, it doesn't make sense to have a product without one, so it is required.</p>
74
61
75
-
<p>In JSON Schema terms, we can update our schema to:</p>
62
+
<p>In JSON Schema terms, we can update our schema to:</p>
<p><em>name</em> is a string value that describes a product. Since there isn't
94
-
much to a product without a name, it also is required. Adding this gives us the schema:</p>
79
+
<h3>Is name required?</h3>
80
+
<p><em>name</em> is a string value that describes a product. Since there isn't
81
+
much to a product without a name, it also is required. Adding this gives us the schema:</p>
95
82
96
83
<preclass="json-schema">
97
84
{
@@ -113,8 +100,8 @@ <h4>Is name required?</h4>
113
100
}
114
101
</pre>
115
102
116
-
<h4>Can price be 0?</h4>
117
-
<p>According to Acme's docs, there are no free products. In JSON schema a number can have a minimum. By default this minimum is inclusive, so we need to specify <em>exclusiveMinimum</em>. Therefore we can update our schema with <em>price</em>:</p>
103
+
<h3>Can price be 0?</h3>
104
+
<p>According to Acme's docs, there are no free products. In JSON schema a number can have a minimum. By default this minimum is inclusive, so we need to specify <em>exclusiveMinimum</em>. Therefore we can update our schema with <em>price</em>:</p>
118
105
119
106
<preclass="json-schema">
120
107
{
@@ -141,21 +128,21 @@ <h4>Can price be 0?</h4>
141
128
}
142
129
</pre>
143
130
144
-
<h4>Are all tags strings?</h4>
145
-
<p>Finally, we come to the <em>tags</em> property. Unlike the previous
146
-
properties, tags have many values, and is represented as a JSON array. According
147
-
to Acme's docs, all tags must be strings, but you aren't required to specify
148
-
tags. We simply leave <em>tags</em> out of the list of required properties.</p>
131
+
<h3>Are all tags strings?</h3>
132
+
<p>Finally, we come to the <em>tags</em> property. Unlike the previous
133
+
properties, tags have many values, and is represented as a JSON array. According
134
+
to Acme's docs, all tags must be strings, but you aren't required to specify
135
+
tags. We simply leave <em>tags</em> out of the list of required properties.</p>
149
136
150
-
<p>However, Acme's docs add two constraints:</p>
137
+
<p>However, Acme's docs add two constraints:</p>
151
138
152
-
<ul>
153
-
<li>there must be at least one tag,</li>
154
-
<li>all tags must be unique.</li>
155
-
</ul>
139
+
<ul>
140
+
<li>there must be at least one tag,</li>
141
+
<li>all tags must be unique.</li>
142
+
</ul>
156
143
157
-
<p>The first constraint can be added with <em>minItems</em>, and the second one by
158
-
specifying <em>uniqueItems</em> as being true:</p>
144
+
<p>The first constraint can be added with <em>minItems</em>, and the second one by
145
+
specifying <em>uniqueItems</em> as being true:</p>
159
146
160
147
<preclass="json-schema">
161
148
{
@@ -189,15 +176,15 @@ <h4>Are all tags strings?</h4>
189
176
"required": ["id", "name", "price"]
190
177
}
191
178
</pre>
179
+
</div>
192
180
193
-
<h3>Example summary</h3>
194
-
<p>The above example is by no means definitive of all the types of data JSON schema can define. For more definitive information see the <ahref="#definitions">full standard draft</a>.</p>
195
-
196
-
<p>As a final example, here's a spec for an array of products, with the products having 2 new properties. The first is a <em>dimensions</em> property for the size of the product, and the second is a <em>warehouseLocation</em> field for where the warehouse that stores them is geographically located.</p>
197
-
198
-
<p>And also, since JSON Schema defines a reference schema for a geographic location, instead of coming up with our own, we'll reference the <ahref="http://json-schema.org/geo">canonical one</a>.</p>
181
+
<h2>Summary</h2>
182
+
<divclass="block">
183
+
<p>The above example is by no means definitive of all the types of data JSON schema can define. For more definitive information see the <ahref="#definitions">full standard draft</a>.</p>
184
+
<p>As a final example, here's a spec for an array of products, with the products having 2 new properties. The first is a <em>dimensions</em> property for the size of the product, and the second is a <em>warehouseLocation</em> field for where the warehouse that stores them is geographically located.</p>
185
+
<p>And also, since JSON Schema defines a reference schema for a geographic location, instead of coming up with our own, we'll reference the <ahref="http://json-schema.org/geo">canonical one</a>.</p>
0 commit comments