Skip to content

Commit e7ecb1b

Browse files
benjagmbenjagm
authored
Merge pull request #47 from aku1310/overview-page
[Docs] Updated 'What is JSON Schema?' page
2 parents 0b8c0df + 7e750d4 commit e7ecb1b

File tree

2 files changed

+264
-13
lines changed

2 files changed

+264
-13
lines changed

‎pages/overview/what-is-jsonschema.md

Lines changed: 264 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -6,36 +6,287 @@ title: What is JSON Schema?
66
JSON Schema is a declarative language that you can use to annotate and validate the structure, constraints, and data types of your JSON documents. It provides a way to standardize and define expectations for your JSON data.
77

88

9-
## Overview
9+
## Overview
1010

1111
This documentation describes JSON Schema and the many ways you can use it to ensure the consistency of your JSON data. Here’s what you’ll find in the documentation:
1212

1313
* **Getting Started**: If you’re new to JSON Schema, [start here](/learn/getting-started-step-by-step). You’ll find a step-by-step guide that walks you through creating your first JSON Schema, along with some real-world examples.
14-
* **Reference**: This section provides a [glossary]((/learn/glossary), [specification release notes](/specification), and [in-depth reference](/understanding-json-schema) to JSON Schema that you can use to write and understand more complex schemas.
14+
* **Reference**: This section provides a [glossary](/learn/glossary), [specification release notes](/specification), and [in-depth reference](/understanding-json-schema) to JSON Schema that you can use to write and understand more complex schemas.
1515

1616

17-
## Why JSON Schema?
17+
## JSON Schema History
1818

19-
JSON Schema can:
19+
JSON Schema has a rich history that dates back to the [first JSON Schema proposal](https://web.archive.org/web/20071026185150/http://json.com/json-schema-proposal/) submitted by **Kris Zyp** to json.com on October 2nd, 2007.
2020

21-
* Describe your existing data formats
22-
* Provide clear documentation that’s both human and machine readable
23-
* Validate your data, which helps you:
24-
* Automate testing
25-
* Ensure the quality of client-submitted data
21+
The current version of JSON Schema is [2020-12](/draft/2020-12/release-notes), which represents the latest advancements and have expended capabilities as compared with the previous version `draft-04`, `draft-06`, `draft-07`. We encourage everyone to adopt the latest version whenever possible to take advantage of all the advancements and benefits of JSON Schema.
2622

27-
JSON Schema is highly extensible and can be tailored to fit your needs. You can create custom keywords, formats, and validation rules to suit your own requirements. The JSON Schema community has a wealth of tools and resources available across many programming languages to help you create, validate, and integrate your schemas.
23+
For more information regarding JSON Schema history, you can refer to [this article](https://modern-json-schema.com/what-is-modern-json-schema) by **Henry Andrews**.
2824

25+
![How JSON Schema works](/img/what-is-json-schema.png)
2926

3027
## How it works
3128

3229
Using JSON Schema, you can define rules and constraints that JSON data should adhere to. When your JSON documents adhere to these constraints, it becomes easier to exchange structured data between applications because the data follows a consistent pattern.
3330

34-
You begin by defining the rules in a JSON Schema document using various [keywords](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-validation-keywords-for-any). For example, you can use `type` to specify what types of data are valid for a given key. You can specify either a single type, like `string`, or an array of possible types, like `string`, `number`, or `integer`. You can also enforce formats using regular expressions with the `pattern` keyword. There are countless ways to describe specific data types and formats that your data must follow.
31+
Before we get into JSON Schema and how it can help us, let's first understand what exactly is a JSON document.
3532

36-
After you define your schema, you validate your JSON documents against the schema. To do this, you can use any supported [validator](https://json-schema.org/implementations.html#validators) in whatever language or context fits your project. There are JSON Schema validation tools for nearly every modern programming language, as well as language-agnostic command-line and browser tools.
33+
* A JSON document represents a piece of data that follows the syntax and structure defined by the JSON format. It is a collection of key-value pairs, arrays, and nested objects.
34+
* JSON documents are used to store and transfer data between systems and applications.
3735

38-
When you have a defined schema and valid JSON data, the possibilities are endless. You can do additional data processing, set up error handling, and integrate your validated data with APIs, other applications, and business logic.
36+
Taking an example of a JSON document representing a customer order:
37+
```json
38+
{
39+
"order_id": "123456",
40+
"customer_name": "John Doe",
41+
"items": [
42+
{
43+
"product_id": "P001",
44+
"name": "T-shirt",
45+
"quantity": 2,
46+
"price": 19.99
47+
},
48+
{
49+
"product_id": "P002",
50+
"name": "Jeans",
51+
"quantity": 1,
52+
"price": 49.99
53+
}
54+
],
55+
"total_amount": 89.97,
56+
"status": "pending"
57+
}
58+
```
59+
60+
* The above code snippet includes attributes such as the *order ID*, *customer name*, *items ordered* (an array of objects with product details), *shipping address*, *total amount*, and *status* of the order.
61+
62+
* This JSON document provides a structured representation of an order, making it easy to exchange, store, or process the order information in various applications or systems.
63+
64+
65+
### The challenge
66+
67+
When working with JSON data, it can quickly become complex and difficult to manage, especially when dealing with nested structures. Without a standardized schema, it becomes challenging to validate and enforce constraints on the data.
68+
69+
For example, if we wanted to validate JSON data using Python:
70+
71+
```python
72+
# Without JSON Schema
73+
data = {
74+
"product": {
75+
"name": "Widget",
76+
"price": 10.99,
77+
"quantity": 5
78+
}
79+
}
80+
81+
# Performing basic validation
82+
if "product" in data and isinstance(data["product"], dict) and "name" in data["product"] and "price" in data["product"]:
83+
print("Valid JSON object.")
84+
else:
85+
print("Invalid JSON object.")
86+
```
87+
88+
In the above code snippet, we are performing basic validation to check if the JSON object has the required fields. Since this is a relatively simpler data, this way of checking works for now.
89+
90+
To show the challenges of performing data validation without using JSON Schema, we can take this exmaple in Python:
91+
```python
92+
# Without JSON Schema
93+
data = {
94+
"order": {
95+
"order_id": "123456",
96+
"customer_name": "John Doe",
97+
"items": [
98+
{
99+
"product_id": "P001",
100+
"name": "T-shirt",
101+
"quantity": 2,
102+
"price": 19.99
103+
},
104+
{
105+
"product_id": "P002",
106+
"name": "Jeans",
107+
"quantity": 1,
108+
"price": 49.99
109+
}
110+
],
111+
"shipping_address": {
112+
"street": "123 Main St",
113+
"city": "New York",
114+
"state": "NY",
115+
"postal_code": "10001"
116+
},
117+
"total_amount": 89.97,
118+
"status": "pending"
119+
}
120+
}
121+
122+
# Performing basic validation
123+
if (
124+
"order" in data
125+
and isinstance(data["order"], dict)
126+
and "order_id" in data["order"]
127+
and "customer_name" in data["order"]
128+
and "items" in data["order"] and isinstance(data["order"]["items"], list)
129+
and "shipping_address" in data["order"] and isinstance(data["order"]["shipping_address"], dict)
130+
and "total_amount" in data["order"]
131+
and "status" in data["order"]
132+
):
133+
print("Valid JSON object.")
134+
else:
135+
print("Invalid JSON object.")
136+
137+
```
138+
Now we are dealing with a complex JSON structure that represents an order. The basic validation logic checks whether the required fields exist in the JSON object. However, as the structure becomes more complex, the validation code becomes more complicated and prone to errors. Moreover, this approach lacks support for checking data types, handling nested structures, and enforcing specific constraints.
139+
140+
141+
### JSON Schema to the rescue
142+
143+
JSON Schema provides a solution to this problem. It is a specification language for JSON that allows you to describe the structure, content, and semantics of a JSON instance. With JSON Schema, you can define metadata about an object's properties, specify whether fields are optional or required, and define expected data formats.
144+
145+
By using JSON Schema, people can better understand the structure and constraints of the JSON data they are using. It enables applications to validate data, ensuring it meets the defined criteria. With JSON Schema, you can make your JSON more readable, enforce data validation, and improve interoperability across different programming languages.
146+
147+
Using the same example, we can validate the data by making use of the [jsonschema](https://github.com/python-jsonschema/jsonschema) Python library:
148+
```python
149+
from jsonschema import validate
150+
151+
# Using JSON Schema
152+
data = {
153+
"product": {
154+
"name": "Widget",
155+
"price": 10.99,
156+
"quantity": 5
157+
}
158+
}
159+
160+
schema = {
161+
"$schema": "https://json-schema.org/draft/2020-12/schema",
162+
"title": "Product",
163+
"type": "object",
164+
"properties": {
165+
"product": {
166+
"type": "object",
167+
"properties": {
168+
"name": {
169+
"type": "string"
170+
},
171+
"price": {
172+
"type": "number",
173+
"minimum": 0
174+
},
175+
"quantity": {
176+
"type": "integer",
177+
"minimum": 1
178+
}
179+
},
180+
"required": ["name", "price", "quantity"]
181+
}
182+
},
183+
"required": ["product"]
184+
}
185+
186+
try:
187+
validate(data, schema)
188+
print("Valid JSON object.")
189+
except Exception as e:
190+
print("Invalid JSON object:", e)
191+
192+
```
193+
194+
In the above code snippet, we defined a JSON Schema that describes the expected structure and constraints of the JSON data. We use the `jsonschema` library to validate the `data` against the `schema`. If the data doesn't conform to the schema, an exception is raised, providing detailed information about the failure.
195+
196+
By using JSON Schema, we can easily define and enforce constraints, making the validation process more robust and manageable. It improves the readability of the code and reduces the chances of data-related issues.
197+
198+
199+
### Steps to Validate JSON Data Using JSON Schema
200+
201+
1. **Create the schema**
202+
203+
You begin by defining the rules in a JSON Schema document using [keywords](/learn/glossary/#keyword).
204+
205+
* You can use `type` to specify what types of data are valid for a given key. You can specify either a single type, like `string`, or an array of possible types, like `string`, `number`, or `integer`.
206+
* You can also enforce formats using regular expressions with the `pattern` keyword.
207+
* There are countless ways to describe specific data types and formats that your data must follow.
208+
209+
Now that the rules have been created, you can use these rules to create a JSON Schema that represents the expected structure and format of your JSON data.
210+
211+
For example, let the following file be `schema.json`:
212+
213+
```json
214+
schema = {
215+
"type": "object",
216+
"properties": {
217+
"name": {
218+
"type": ["string", "null"],
219+
"pattern": "^[A-Za-z]+$"
220+
},
221+
"age": {
222+
"type": "integer"
223+
},
224+
"email": {
225+
"type": "string"
226+
}
227+
},
228+
"required": ["name", "age", "email"]
229+
}
230+
```
231+
232+
* In the above schema, `name` can either be a `string` or `null`, `age` can only be an `integer`, `email` can only be a `string`, and the entire schema is an `object`.
233+
* Here, `name` can only contain alphabetical characters.
234+
* You can make some properties mandatory to enter by using the `required` keyword. Here, `name`, `age`, and `email`, all are required to create an instance of the schema.
235+
236+
2. **Choose a validator**
237+
238+
Select a JSON Schema [validator](https://json-schema.org/implementations.html#validators) that is supported in your chosen programming language or context. There are JSON Schema validation tools for nearly every modern programming language, as well as language-agnostic command-line and browser tools.
239+
240+
3. **Validate the instance**
241+
242+
Use the selected validator to validate your instance against the created JSON Schema.
243+
244+
Here's an example using the [jsonschema](https://github.com/python-jsonschema/jsonschema) Python library:
245+
```python
246+
from jsonschema import validate
247+
248+
# Load the JSON data to be validated
249+
data = {
250+
"name": "John Doe",
251+
"age": 25,
252+
"email": "[email protected]"
253+
}
254+
255+
# Load and validate the JSON Schema from step 2
256+
with open("schema.json") as schema_file:
257+
schema = json.load(schema_file)
258+
validate(data, schema)
259+
```
260+
261+
* We have created an `instance` of the `schema` we defined as an example in step 2.
262+
* Since the data is valid, we will not get any output. In case of invalid data, we will get a `jsonschema.exceptions.ValidationError` exception.
263+
264+
4. **Apply to your use case**
265+
266+
When you have a defined schema and valid JSON data, the possibilities are vast. You can do additional data processing, set up error handling, and integrate your validated data with APIs, other applications, and business logic.
267+
268+
269+
## Why developers use JSON Schema
270+
271+
With JSON Schema you can:
272+
273+
* **Describe existing data formats**: JSON Schema allows you to describe the structure, constraints, and data types of your existing JSON data formats.
274+
* **Define rules and constraints**: When your JSON documents adhere to these constraints, it becomes easier to exchange structured data between applications because the data follows a consistent pattern.
275+
* **Clear and readable documentation**: JSON Schema supports the creation of documentation that is easily understandable by both humans and machines.
276+
* **Highly extensible** and can be tailored to fit your needs.
277+
* You can create *custom keywords*, *formats*, and *validation rules* to suit your own requirements.
278+
* **Validate your data**, which helps you:
279+
* **Automate testing**: JSON Schema validation enables automated testing, ensuring that data consistently adheres to the specified rules and constraints.
280+
* **Enhance data quality**: By enforcing validation rules, JSON Schema helps ensure the quality of client-submitted data, preventing inconsistencies, errors, and malicious inputs.
281+
* **Wide range of tools availability**: The JSON Schema community has a wealth of tools and resources available across many programming languages to help you create, validate, and integrate your schemas.
282+
283+
284+
## Why organizations adopt JSON Schema
285+
286+
* **Streamline testing and validation**: Simplify your validation logic to reduce your code’s complexity and save time on development. Define constraints for your data structures to catch and prevent errors, inconsistencies, and invalid data.
287+
* **Exchange data seamlessly**: Establish a common language for data exchange, no matter the scale or complexity of your project. Define precise validation rules for your data structures to create shared understanding and increase interoperability across different systems and platforms.
288+
* **Document your data**: Create a clear, standardized representation of your data to improve understanding and collaboration among developers, stakeholders, and collaborators.
289+
* **Vibrant tooling ecosystem**: Adopt JSON Schema with an expansive range of community-driven tools, libraries, and frameworks across many programming languages.
39290

40291

41292
## Next steps

‎public/img/what-is-json-schema.png

110 KB
Loading

0 commit comments

Comments
 (0)