Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Restructure what is JSON Schema for clarity #679

Merged
merged 9 commits into from
May 21, 2024
Merged

Restructure what is JSON Schema for clarity #679

Changes from 5 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
89062fa
Restructure what is JSON Schema for clarity
Nickyshe Apr 26, 2024
9e0f69a
Merge branch 'json-schema-org:main' into main
Nickyshe May 2, 2024
799a508
Made changes to suggestion
Nickyshe May 4, 2024
9bec2e4
Merge branch 'json-schema-org:main' into main
Nickyshe May 4, 2024
89a100e
Merge branch 'main' of https://github.com/Nickyshe/website
Nickyshe May 4, 2024
a50dc16
Merge branch 'json-schema-org:main' into main
Nickyshe May 14, 2024
f14859b
Suggested changes corrected on what is JSON schema page
Nickyshe May 14, 2024
4b7e156
added modified image
Nickyshe May 15, 2024
dcebf7d
Small adjustment and image location
benjagm May 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
243 changes: 40 additions & 203 deletions pages/overview/what-is-jsonschema.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,219 +2,56 @@
section: docs
title: What is JSON Schema?
---
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.
JSON Schema is a declarative language for annotating and validating JSON documents' structure, constraints, and data types. It provides a way to standardize and define expectations for JSON data.
<br/><br/>
![How JSON Schema works](/img/what-is-json-schema.png)
Nickyshe marked this conversation as resolved.
Show resolved Hide resolved

## How it works

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.

Before we get into JSON Schema and how it can help us, let's first understand what exactly is a JSON document.

* 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.
* JSON documents are used to store and transfer data between systems and applications.

Taking an example of a JSON document representing a customer order:

```json
{
"order_id": "123456",
"customer_name": "John Doe",
"items": [
{
"product_id": "P001",
"name": "T-shirt",
"quantity": 2,
"price": 19.99
},
{
"product_id": "P002",
"name": "Jeans",
"quantity": 1,
"price": 49.99
}
],
"total_amount": 89.97,
"status": "pending"
}
```

* 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.

* 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.


### The challenge

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.

For example, if we wanted to validate JSON data using Python:

```python
# Without JSON Schema
data = {
"product": {
"name": "Widget",
"price": 10.99,
"quantity": 5
}
}

# Performing basic validation
if "product" in data and isinstance(data["product"], dict) and "name" in data["product"] and "price" in data["product"]:
print("Valid JSON object.")
else:
print("Invalid JSON object.")
```

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.

To show the challenges of performing data validation without using JSON Schema, we can take this example in Python:

```python
# Without JSON Schema
data = {
"order": {
"order_id": "123456",
"customer_name": "John Doe",
"items": [
{
"product_id": "P001",
"name": "T-shirt",
"quantity": 2,
"price": 19.99
},
{
"product_id": "P002",
"name": "Jeans",
"quantity": 1,
"price": 49.99
}
],
"shipping_address": {
"street": "123 Main St",
"city": "New York",
"state": "NY",
"postal_code": "10001"
},
"total_amount": 89.97,
"status": "pending"
}
}

# Performing basic validation
if (
"order" in data
and isinstance(data["order"], dict)
and "order_id" in data["order"]
and "customer_name" in data["order"]
and "items" in data["order"] and isinstance(data["order"]["items"], list)
and "shipping_address" in data["order"] and isinstance(data["order"]["shipping_address"], dict)
and "total_amount" in data["order"]
and "status" in data["order"]
):
print("Valid JSON object.")
else:
print("Invalid JSON object.")
```

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.


### JSON Schema to the rescue

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.

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.

Using the same example, we can validate the data by making use of the [jsonschema](https://github.com/python-jsonschema/jsonschema) Python library:

```python
from jsonschema import validate

# Using JSON Schema
data = {
"product": {
"name": "Widget",
"price": 10.99,
"quantity": 5
}
}

schema = {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Product",
"type": "object",
"properties": {
"product": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"price": {
"type": "number",
"minimum": 0
},
"quantity": {
"type": "integer",
"minimum": 1
}
},
"required": ["name", "price", "quantity"]
}
},
"required": ["product"]
}

try:
validate(data, schema)
print("Valid JSON object.")
except Exception as e:
print("Invalid JSON object:", e)

```

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.

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.


## Why developers use JSON Schema

With JSON Schema you can:

* **Describe existing data formats**: JSON Schema allows you to describe the structure, constraints, and data types of your existing JSON data formats.
* **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.
* **Clear and readable documentation**: JSON Schema supports the creation of documentation that is easily understandable by both humans and machines.
* **Highly extensible** and can be tailored to fit your needs.
* You can create *custom keywords*, *formats*, and *validation rules* to suit your own requirements.
* **Validate your data**, which helps you:
* **Automate testing**: JSON Schema validation enables automated testing, ensuring that data consistently adheres to the specified rules and constraints.
* **Enhance data quality**: By enforcing validation rules, JSON Schema helps ensure the quality of client-submitted data, preventing inconsistencies, errors, and malicious inputs.
* **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.


## Why organizations adopt JSON Schema

* **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.
* **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.
* **Document your data**: Create a clear, standardized representation of your data to improve understanding and collaboration among developers, stakeholders, and collaborators.
* **Vibrant tooling ecosystem**: Adopt JSON Schema with an expansive range of community-driven tools, libraries, and frameworks across many programming languages.

## JSON Schema History
## How does JSON Schema work?

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.
In the world of data exchange, JSON Schema emerges as a powerful tool for defining the structure and rules of your JSON data. It uses keywords to define the properties of your data. These keywords allow you to specify details, including datatypes, required properties that must be present for a valid JSON document, and optional properties that can be included.
Nickyshe marked this conversation as resolved.
Show resolved Hide resolved

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.
Furthermore, you can restrict the length of your data and ensure it adheres to specific formats. JSON Schema empowers you to define minimum and maximum values for numerical data, keeping your numbers within a valid range.
Nickyshe marked this conversation as resolved.
Show resolved Hide resolved

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**.
## Benefits of JSON Schema for Developers

## Next steps
JSON Schema empowers developers in the following ways:

To start using JSON Schema, see [Creating your first schema](../learn/getting-started-step-by-step).
* **Structured Data Description**: JSON Schema allows developers to describe the structure, constraints, and data types of existing JSON formats.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

importantly: "JSON Schemas are described with JSON documents"

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

perhaps use "JSON data" instead of "existing JSON formats", unless you have a better defined term for "formats" without using "schema" :-(.
("formats" is not well defined, and may be confused with the format keyword). Also, for conciseness, omit "existing" - I don't think it is necessary here

* **Rule Definition and Enforcement**: By adhering to JSON schema constraints, it becomes easier to exchange structured data between applications as it maintains a consistent pattern.
* **Produce clear documentation**: JSON Schema supports the creation of machine and human readable documentation.
* **Extensibility:** JSON Schema offers high adaptability to developers' needs. Custom keywords, formats, and validation rules can be created to tailor schemas according to specific requirements..
* **Data Validation:** JSON Schema ensures data validity through:
* Automated Testing: Validation enables automated testing, ensuring data consistently complies with specified rules and constraints.
* Improved Data Quality: By enforcing validation rules, JSON Schema aids in maintaining the quality of client-submitted data, reducing inconsistencies, errors, and potential security vulnerabilities.
* **Rich Tooling Ecosystem**: The JSON Schema community offers a wealth of tools and resources across various programming languages to help developers create, validate, and integrate schemas.

### Benefits of JSON Schema for Organizations

JSON Schema empowers organizations by:

* **Simplifying Testing and Validation:**: JSON Schema reduces code complexity and development time by simplifying validation logic. It defines constraints for data structures, enabling the detection and prevention of errors, inconsistencies, and invalid data.

* **Facilitating Seamless Data Exchange:**: JSON Schema establishes a common language for data exchange, no matter the complexity of your project. It defines precise validation rules for your data structures to create a shared understanding and increase interoperability across different systems and platforms.
* **Enhancing Data Documentation**: JSON Schema enables the creation of clear and standardized representations of data. This improves understanding and collaboration among developers, stakeholders, and collaborators, enhancing organizational efficiency.
* **Access to a Vibrant Tooling Ecosystem**: JSON Schema is supported by a diverse array of languages, libraries, and frameworks with community-driven tools. This vibrant ecosystem enhances development productivity and provides resources for effective schema implementation and utilization.


## History of JSON Schema


JSON Schema 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](http://json.com) on October 2nd, 2007.

The current version of JSON Schema is [2020-12](https://json-schema.org/draft/2020-12/release-notes), which represents the latest advancements and has expanded capabilities compared with the previous versions, `draft-04`, `draft-06`, and `draft-07`.

We recommend using the newest version of JSON Schema and taking advantage of its benefits.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

newest -> current


For more information regarding JSON Schema history, refer to [this article](https://modern-json-schema.com/what-is-modern-json-schema) by Henry Andrews.


## What Next?

Intrigued by JSON Schema's potential? Dive right in! Learning is by doing, and creating your first schema is the perfect starting point. Check out the guide on [Creating your first schema](https://json-schema.org/learn/getting-started-step-by-step) to begin crafting your data validation tool.

### Learn more

Expand Down