Skip to content

Commit

Permalink
Adding feedback to improve the messaging and illustration of What is …
Browse files Browse the repository at this point in the history
…JSON Schema (#724)

* Adding feedback to improve the messaging and illustration

* Change back the new illustration to SVG format

* Added the comments provided by Ben Hutton in PR #655

* Update pages/overview/what-is-jsonschema.md

Co-authored-by: Ben Hutton <[email protected]>

* Update pages/overview/what-is-jsonschema.md

Co-authored-by: Greg Dennis <[email protected]>

* Adding last requested changes

---------

Co-authored-by: Ben Hutton <[email protected]>
Co-authored-by: Greg Dennis <[email protected]>
  • Loading branch information
3 people authored Jun 12, 2024
1 parent ee124c7 commit ca444d5
Show file tree
Hide file tree
Showing 3 changed files with 9 additions and 9 deletions.
15 changes: 7 additions & 8 deletions pages/overview/what-is-jsonschema.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,50 +2,49 @@
section: docs
title: What is JSON Schema?
---
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.
> JSON Schema is a declarative language for defining structure and constraints for JSON data.
<br/>

## How does JSON Schema work?

When it comes to data exchange, JSON Schema stands out as a powerful standard for defining the structure and rules of JSON data. It uses a set of [keywords](https://json-schema.org/learn/glossary#keyword) to define the properties of your data.

While JSON Schema provides the language, validating a JSON [instance](https://json-schema.org/learn/glossary#instance) against a [schema](https://json-schema.org/learn/glossary#schema) requires a JSON Schema [validator](https://json-schema.org/implementations#tools). The JSON validator checks if the JSON documents conform to the schema.
While JSON Schema provides the language, validating a JSON [instance](https://json-schema.org/learn/glossary#instance) against a [schema](https://json-schema.org/learn/glossary#schema) requires a JSON Schema [validator](https://json-schema.org/implementations#validators). The JSON validator checks if the JSON documents conform to the schema.

JSON validators are open-source and commercial tools that implement the JSON Schema specification. They make it very easy to integrate JSON Schema into projects of any size.
JSON validators are tools that implement the JSON Schema specification. Such tooling enables easy integration of JSON Schema into projects of any size.

![How JSON Schema works](/img/json_schema.svg)

## Benefits of JSON Schema for Developers

JSON Schema empowers developers in the following ways:

* **Structured Data Description**: JSON Schema allows developers to describe the structure, constraints, and data types of existing JSON formats.
* **Structured Data Description**: JSON Schema allows developers to describe the structure, constraints, and data types of existing JSON data.
* **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.
* **Rich Tooling Ecosystem**: The JSON Schema community offers a wealth of [tools](https://json-schema.org/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.
* **Access to a Vibrant Tooling Ecosystem**: JSON Schema is supported by a diverse array of languages, libraries, and frameworks with community-driven [tools](https://json-schema.org/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`.
The latest version of JSON Schema is [2020-12](https://json-schema.org/latest/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.

Expand Down
1 change: 1 addition & 0 deletions public/_redirects
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
/latest/json-schema-core /draft/2020-12/json-schema-core 301
/latest/json-schema-validation /draft/2020-12/json-schema-validation 301
/latest/relative-json-pointer /draft/2020-12/relative-json-pointer.html 301
/latest/release-notes /draft/2020-12/release-notes
/tools /implementations 301
/slack https://join.slack.com/t/json-schema/shared_invite/zt-2gew5jhhj-WNWmCC8QJ~oHJ4rfNEXddQ 301
/slack-redirect https://join.slack.com/t/json-schema/shared_invite/zt-2gew5jhhj-WNWmCC8QJ~oHJ4rfNEXddQ 301
2 changes: 1 addition & 1 deletion public/img/json_schema.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit ca444d5

Please sign in to comment.