From ca444d5da4b9e9a3c0936d4759829c31fc447188 Mon Sep 17 00:00:00 2001 From: Benjamin Granados <40007659+benjagm@users.noreply.github.com> Date: Wed, 12 Jun 2024 15:14:42 +0200 Subject: [PATCH] Adding feedback to improve the messaging and illustration of What is 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 * Update pages/overview/what-is-jsonschema.md Co-authored-by: Greg Dennis * Adding last requested changes --------- Co-authored-by: Ben Hutton Co-authored-by: Greg Dennis --- pages/overview/what-is-jsonschema.md | 15 +++++++-------- public/_redirects | 1 + public/img/json_schema.svg | 2 +- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/pages/overview/what-is-jsonschema.md b/pages/overview/what-is-jsonschema.md index 56fc83a9f..6f7da535c 100644 --- a/pages/overview/what-is-jsonschema.md +++ b/pages/overview/what-is-jsonschema.md @@ -2,7 +2,7 @@ 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.
@@ -10,9 +10,9 @@ JSON Schema is a declarative language for annotating and validating JSON documen 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) @@ -20,24 +20,23 @@ JSON validators are open-source and commercial tools that implement the JSON Sch 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 @@ -45,7 +44,7 @@ JSON Schema empowers organizations by: 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. diff --git a/public/_redirects b/public/_redirects index b0e9d2f77..c0054904a 100644 --- a/public/_redirects +++ b/public/_redirects @@ -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 diff --git a/public/img/json_schema.svg b/public/img/json_schema.svg index 0c51b6bb4..5906ec4e5 100644 --- a/public/img/json_schema.svg +++ b/public/img/json_schema.svg @@ -1 +1 @@ - \ No newline at end of file + \ No newline at end of file