Skip to content

Commit 98a867f

Browse files
Charlie OwenPhil Sturgeon
Charlie Owen
authored and
Phil Sturgeon
committed
Updating example1.md
1 parent 56b316f commit 98a867f

File tree

1 file changed

+216
-35
lines changed

1 file changed

+216
-35
lines changed

‎example1.md

Lines changed: 216 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -3,69 +3,148 @@ layout: page
33
title: Building a product schema
44
---
55

6-
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*.
6+
Let's pretend we're interacting with a JSON based product catalog. This catalog has a product which has:
77

8-
### Example JSON data for a product API
8+
* An identifier: `productId`
9+
* A product name: `name`
10+
* A selling cost for the consumer: `price`
11+
* An optional set of tags: `tags`.
912

10-
An example product in this API is:
13+
For example:
1114

1215
```json
13-
{% include example1/instance.json %}
16+
{
17+
"productId": 1,
18+
"name": "A green door",
19+
"price": 12.50,
20+
"tags": [ "home", "green" ]
21+
}
1422
```
1523

16-
While generally straightforward, that example leaves some open questions. For example, one may ask:
24+
While generally straightforward, the example leaves some open questions. For example, one may ask:
1725

18-
- What is id?
19-
- Is name required?
20-
- Can price be 0?
21-
- Are all tags strings?
26+
* What is `productId`?
27+
* Is name `required`?
28+
* Can the `price` be zero (0)?
29+
* Are all of the `tags` string values?
2230

23-
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.
31+
When you're talking about a data format, you want to have metadata about what keys mean, including the valid inputs for those keys. **JSON Schema** is a proposed IETF standard how to answer those questions for data.
2432

25-
Starting the schema
26-
-------------------
33+
## Starting the schema
2734

28-
To start a schema definition, let's begin with a basic JSON schema:
35+
To start a schema definition, let's begin with a basic JSON schema.
36+
37+
We start with four properties called **keywords** which are expressed as [JSON](https://www.json.org/) keys.
38+
39+
> Yes. the standard uses a JSON data document to describe data documents, most often that are also JSON data documents but could be in any number of other content types like `text/xml`.
40+
41+
* The [`$schema`](http://json-schema.org/latest/json-schema-core.html#rfc.section.7) keyword states that this schema is written according to the a specific draft of the standard and used for a variety of reasons, primarily version control.
42+
* The [`$id`](http://json-schema.org/latest/json-schema-core.html#rfc.section.8.2) keyword defines a URI for the schema, and the base URI that other URI references within the schema are resolved against.
43+
* The [`title`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.10.1) and [`description`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.10.1) annotation keywords are descriptive only. They do not add constraints to the data being validated. The intent of the schema is stated with these two keywords.
44+
* The [`type`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.1.1) validation keyword defines the first constraint on our JSON data and in this case it has to be a JSON Object.
2945

3046
```json
31-
{% include example1/schema1.json %}
47+
{
48+
"$schema": "http://json-schema.org/draft-07/schema#",
49+
"$id": "http://example.com/product.schema.json",
50+
"title": "Product",
51+
"description": "A product in the catalog",
52+
"type": "object"
53+
}
3254
```
3355

34-
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).
56+
## Defining the properties
3557

36-
The *type* keyword defines the first constraint on our JSON data: it has to be a JSON Object.
58+
Next let's answer our previous questions about this API, starting with `productId`.
3759

38-
Finally, the *$schema* keyword states that this schema is written according to the draft-06 specification.
60+
### What is productId?
3961

40-
Defining the properties
41-
-----------------------
62+
`productId` 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.
4263

43-
Next let's answer our previous questions about this API, starting with id.
64+
In JSON Schema terms, we update our schema to add:
4465

45-
### What is id?
66+
* The [`properties`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.5.4) keyword.
67+
* The `productId` key.
68+
* `description` and `type` keywords for `productId`.
69+
* The [`required`](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.5.3) keyword listing `productId`.
4670

47-
*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.
48-
49-
In JSON Schema terms, we can update our schema to:
5071

5172
```json
52-
{% include example1/schema2.json %}
73+
{
74+
"$schema": "http://json-schema.org/draft-07/schema#",
75+
"$id": "http://example.com/product.schema.json",
76+
"title": "Product",
77+
"description": "A product from Acme's catalog",
78+
"type": "object",
79+
"properties": {
80+
"productId": {
81+
"description": "The unique identifier for a product",
82+
"type": "integer"
83+
}
84+
},
85+
"required": [ "productId" ]
86+
}
5387
```
5488

5589
### Is name required?
5690

57-
*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:
91+
Yes.
92+
93+
* `name` is a string value that describes a product. Since there isn't much to a product without a name it also is required.
94+
* Since the `required` keyword is an array of strings we can note multiple keys as required, now including `name`.
5895

5996
```json
60-
{% include example1/schema3.json %}
97+
{
98+
"$schema": "http://json-schema.org/draft-07/schema#",
99+
"$id": "http://example.com/product.schema.json",
100+
"title": "Product",
101+
"description": "A product from Acme's catalog",
102+
"type": "object",
103+
"properties": {
104+
"productId": {
105+
"description": "The unique identifier for a product",
106+
"type": "integer"
107+
},
108+
"name": {
109+
"description": "Name of the product",
110+
"type": "string"
111+
}
112+
},
113+
"required": [ "productId", "name" ]
114+
}
61115
```
62116

63-
### Can price be 0?
117+
### Can price be zero (0)?
118+
119+
No. According to the store owner there are no free products. ;)
64120

65-
According to Acme's docs, there are no free products. So we need to specify *exclusiveMinimum*. If we wanted to include 0 as a valid price, we would have specified *minimum* instead. Therefore, we can update our schema with *price*:
121+
* We need to specify this using the [`exclusiveMinimum` validation keyword](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.2.5).
122+
* If we wanted to include zero as a valid price we would have specified the [`minimum` validation keyword](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.2.4).
66123

67124
```json
68-
{% include example1/schema4.json %}
125+
{
126+
"$schema": "http://json-schema.org/draft-07/schema#",
127+
"$id": "http://example.com/product.schema.json",
128+
"title": "Product",
129+
"description": "A product from Acme's catalog",
130+
"type": "object",
131+
"properties": {
132+
"productId": {
133+
"description": "The unique identifier for a product",
134+
"type": "integer"
135+
},
136+
"name": {
137+
"description": "Name of the product",
138+
"type": "string"
139+
},
140+
"price": {
141+
"description": "The price of the product,",
142+
"type": "number",
143+
"exclusiveMinimum": 0
144+
}
145+
},
146+
"required": ["productId", "name", "price"]
147+
}
69148
```
70149

71150
### Are all tags strings?
@@ -80,11 +159,39 @@ However, Acme's docs add two constraints:
80159
The first constraint can be added with *minItems*, and the second one by specifying *uniqueItems* as being true:
81160

82161
```json
83-
{% include example1/schema5.json %}
162+
{
163+
"$schema": "http://json-schema.org/draft-07/schema#",
164+
"$id": "http://example.com/product.schema.json",
165+
"title": "Product",
166+
"description": "A product from Acme's catalog",
167+
"type": "object",
168+
"properties": {
169+
"productId": {
170+
"description": "The unique identifier for a product",
171+
"type": "integer"
172+
},
173+
"name": {
174+
"description": "Name of the product",
175+
"type": "string"
176+
},
177+
"price": {
178+
"type": "number",
179+
"exclusiveMinimum": 0
180+
},
181+
"tags": {
182+
"type": "array",
183+
"items": {
184+
"type": "string"
185+
},
186+
"minItems": 1,
187+
"uniqueItems": true
188+
}
189+
},
190+
"required": ["productId", "name", "price"]
191+
}
84192
```
85193

86-
Summary
87-
-------
194+
## Summary
88195

89196
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).
90197

@@ -95,11 +202,85 @@ And also, since JSON Schema defines a reference schema for a geographic ___location
95202
### Set of products:
96203

97204
```json
98-
{% include example1/set_instance.json %}
205+
[
206+
{
207+
"productId": 2,
208+
"name": "An ice sculpture",
209+
"price": 12.50,
210+
"tags": ["cold", "ice"],
211+
"dimensions": {
212+
"length": 7.0,
213+
"width": 12.0,
214+
"height": 9.5
215+
},
216+
"warehouseLocation": {
217+
"latitude": -78.75,
218+
"longitude": 20.4
219+
}
220+
},
221+
{
222+
"productId": 3,
223+
"name": "A blue mouse",
224+
"price": 25.50,
225+
"dimensions": {
226+
"length": 3.1,
227+
"width": 1.0,
228+
"height": 1.0
229+
},
230+
"warehouseLocation": {
231+
"latitude": 54.4,
232+
"longitude": -32.7
233+
}
234+
}
235+
]
99236
```
100237

101238
### Set of products schema:
102239

103240
```json
104-
{% include example1/set_schema.json %}
241+
{
242+
"$schema": "http://json-schema.org/draft-07/schema#",
243+
"$id": "http://example.com/product.schema.json",
244+
"title": "Product set",
245+
"type": "array",
246+
"items": {
247+
"title": "Product",
248+
"type": "object",
249+
"properties": {
250+
"productId": {
251+
"description": "The unique identifier for a product",
252+
"type": "number"
253+
},
254+
"name": {
255+
"type": "string"
256+
},
257+
"price": {
258+
"type": "number",
259+
"exclusiveMinimum": 0
260+
},
261+
"tags": {
262+
"type": "array",
263+
"items": {
264+
"type": "string"
265+
},
266+
"minItems": 1,
267+
"uniqueItems": true
268+
},
269+
"dimensions": {
270+
"type": "object",
271+
"properties": {
272+
"length": {"type": "number"},
273+
"width": {"type": "number"},
274+
"height": {"type": "number"}
275+
},
276+
"required": ["length", "width", "height"]
277+
},
278+
"warehouseLocation": {
279+
"description": "Coordinates of the warehouse with the product",
280+
"$ref": "http://json-schema.org/geo"
281+
}
282+
},
283+
"required": ["productId", "name", "price"]
284+
}
285+
}
105286
```

0 commit comments

Comments
 (0)