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.
The latest Internet-Drafts at the IETF are the draft-wright-json-schema\*-01 documents, which correspond to the draft-06 meta-schemas. These were published on 2017-04-15. (Due to a change in authorship the I-D numbering was reset with the previous draft). The specification is split into three parts, Core, Validation, and Hyper-Schema:
|[JSON Schema Core](latest/json-schema-core.html)| defines the basic foundation of JSON Schema |
12
+
|[JSON Schema Validation](latest/json-schema-validation.html)| defines the validation keywords of JSON Schema |
13
+
|[JSON Hyper-Schema](latest/json-schema-hypermedia.html)| defines the hyper-media keywords of JSON Schema |
14
+
15
+
They are also available on the IETF main site: [core (draft-wright-json-schema-01)](http://tools.ietf.org/html/draft-wright-json-schema-01), [validation (draft-wright-json-schema-validation-01)](http://tools.ietf.org/html/draft-wright-json-schema-validation-01) and [hyper-schema (draft-wright-json-schema-hyperschema-01)](http://tools.ietf.org/html/draft-wright-json-schema-hyperschema-01).
16
+
17
+
For previous versions of the specification, please see the [Specification Links](https://github.com/json-schema-org/json-schema-spec/wiki/Specification-Links) page on our github wiki.
18
+
19
+
Meta-schemas
20
+
------------
21
+
22
+
The meta-schemas are the schemas which define the JSON Schema and Hyper-Schema formats.
Copy file name to clipboardExpand all lines: example1.md
+69-74Lines changed: 69 additions & 74 deletions
Original file line number
Diff line number
Diff line change
@@ -2,69 +2,65 @@
2
2
layout: page
3
3
---
4
4
5
-
<h2>Example data</h2>
6
-
<divclass="block">
7
-
<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>
5
+
Example data
6
+
------------
8
7
9
-
<h3>Example JSON data for a product API</h3>
10
-
<p>An example product in this API is:</p>
8
+
Let's pretend we're interacting with a JSON based product catalog. This catalog has a product which has an *id*, a *name*, a *price*, and an optional set of *tags*.
11
9
12
-
<pre><codeclass="language-json">
10
+
### Example JSON data for a product API
11
+
12
+
An example product in this API is:
13
+
14
+
```json
13
15
{
14
16
"id": 1,
15
17
"name": "A green door",
16
18
"price": 12.50,
17
19
"tags": ["home", "green"]
18
20
}
19
-
</code></pre>
21
+
```
20
22
21
-
<p>While generally straightforward, that example leaves some open questions. For example, one may ask:</p>
23
+
While generally straightforward, that example leaves some open questions. For example, one may ask:
22
24
23
-
<ul>
24
-
<li>What is id?</li>
25
-
<li>Is name required?</li>
26
-
<li>Can price be 0?</li>
27
-
<li>Are all tags strings?</li>
28
-
</ul>
25
+
- What is id?
26
+
- Is name required?
27
+
- Can price be 0?
28
+
- Are all tags strings?
29
29
30
-
<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>
31
-
</div>
30
+
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.
32
31
33
-
<h2>Starting the schema</h2>
34
-
<divclass="block">
35
-
<p>To start a schema definition, let's begin with a basic JSON schema:</p>
32
+
Starting the schema
33
+
-------------------
36
34
37
-
<pre><codeclass="language-json">
35
+
To start a schema definition, let's begin with a basic JSON schema:
The above schema has four properties called *keywords*. The *title* and *description* keywords are descriptive only, in that they do not add constraints to the data being validated. The intent of the schema is stated with these two keywords (that is, this schema describes a product).
45
47
46
-
<p>The above schema has four properties called <em>keywords</em>.
48
+
The *type* keyword defines the first constraint on our JSON data: it has to be a JSON Object.
47
49
48
-
The <em>title</em> and <em>description</em> keywords are descriptive only, in that they do not add
49
-
constraints to the data being validated. The intent of the schema is stated with these two keywords
50
-
(that is, this schema describes a product).</p>
50
+
Finally, the *$schema* keyword states that this schema is written according to the draft v4 specification.
51
51
52
-
<p>The <em>type</em> keyword defines the first constraint on our JSON data: it has to be a JSON
53
-
Object.</p>
52
+
Defining the properties
53
+
-----------------------
54
54
55
-
<p>Finally, the <em>$schema</em> keyword states that this schema is written according to the draft
56
-
v4 specification.</p>
57
-
</div>
55
+
Next let's answer our previous questions about this API, starting with id.
58
56
59
-
<h2>Defining the properties</h2>
60
-
<divclass="block">
61
-
<p>Next let's answer our previous questions about this API, starting with id.</p>
57
+
### What is id?
62
58
63
-
<h3>What is id?</h3>
64
-
<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
+
*id* 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.
65
60
66
-
<p>In JSON Schema terms, we can update our schema to:</p>
67
-
<pre><codeclass="language-json">
61
+
In JSON Schema terms, we can update our schema to:
<p><em>name</em> is a string value that describes a product. Since there isn't
85
-
much to a product without a name, it also is required. Adding this gives us the schema:</p>
81
+
*name* is a string value that describes a product. Since there isn't much to a product without a name, it also is required. Adding this gives us the schema:
<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>
105
+
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 *exclusiveMinimum*. Therefore we can update our schema with *price*:
<p>Finally, we come to the <em>tags</em> property. Unlike the previous
137
-
properties, tags have many values, and is represented as a JSON array. According
138
-
to Acme's docs, all tags must be strings, but you aren't required to specify
139
-
tags. We simply leave <em>tags</em> out of the list of required properties.</p>
132
+
### Are all tags strings?
140
133
141
-
<p>However, Acme's docs add two constraints:</p>
134
+
Finally, we come to the *tags* property. Unlike the previous properties, tags have many values, and is represented as a JSON array. According to Acme's docs, all tags must be strings, but you aren't required to specify tags. We simply leave *tags* out of the list of required properties.
142
135
143
-
<ul>
144
-
<li>there must be at least one tag,</li>
145
-
<li>all tags must be unique.</li>
146
-
</ul>
136
+
However, Acme's docs add two constraints:
147
137
148
-
<p>The first constraint can be added with <em>minItems</em>, and the second one by
149
-
specifying <em>uniqueItems</em> as being true:</p>
138
+
-there must be at least one tag,
139
+
-all tags must be unique.
150
140
151
-
<pre><codeclass="language-json">
141
+
The first constraint can be added with *minItems*, and the second one by specifying *uniqueItems* as being true:
@@ -179,17 +171,20 @@ <h3>Are all tags strings?</h3>
179
171
},
180
172
"required": ["id", "name", "price"]
181
173
}
182
-
</code></pre>
183
-
</div>
174
+
```
175
+
176
+
Summary
177
+
-------
178
+
179
+
The above example is by no means definitive of all the types of data JSON schema can define. For more definitive information see the [full standard draft](#definitions).
184
180
185
-
<h2>Summary</h2>
186
-
<divclass="block">
187
-
<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>
188
-
<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>
189
-
<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
+
As a final example, here's a spec for an array of products, with the products having 2 new properties. The first is a *dimensions* property for the size of the product, and the second is a *warehouseLocation* field for where the warehouse that stores them is geographically located.
190
182
191
-
<h3>Set of products:</h3>
192
-
<pre><codeclass="language-json">
183
+
And also, since JSON Schema defines a reference schema for a geographic location, instead of coming up with our own, we'll reference the [canonical one](http://json-schema.org/geo).
0 commit comments