[Docs] Updated 'What is JSON Schema?' page #47
Conversation
Signed-off-by: Akanksha Kushwaha <cmakanksha@gmail.com>
Signed-off-by: Akanksha Kushwaha <cmakanksha@gmail.com>
Signed-off-by: Akanksha Kushwaha <cmakanksha@gmail.com>
Signed-off-by: Akanksha Kushwaha <cmakanksha@gmail.com>
Signed-off-by: Akanksha Kushwaha <cmakanksha@gmail.com>
|
I had an idea regarding the illustrations. Instead of one diagram showing each step inside it under the How it works section, we can also have a diagram after every step (or wherever possible). For example, For step 4: Validating the documents Please let me know your thoughts on this. |
pages/overview/what-is-jsonschema.md
Outdated
|
|
||
| JSON Schema can: | ||
| 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. | ||
| * The *pre-historic* era, from 2009 to 2012, marked the early stages of development when JSON Schema was still evolving without standardized versions. |
There was a problem hiding this comment.
Pre-historic / Classic and modern json schema are concepts used by Henry Andrews but know used generally by the JSON Schema Community so I will suggest avoid to use them and simplify in this section.
- There are five versions in active use: draft-04, draft-06, draft-07, 2019-09 and 2020-12.
- 2020-12 is the current version and have expended capabilities compared with the previous version draft-04, draft-06, draft-07.
- We encourage everyone to adopt the last version when possible to take advantage of all the advancements.
- For more information about JSON Schema history we can refer to Henry Andrews article.
pages/overview/what-is-jsonschema.md
Outdated
| * Validate your data, which helps you: | ||
| * Automate testing | ||
| * Ensure the quality of client-submitted data | ||
| * However, the *modern era*, starting in 2019 and continuing to the present, has brought significant advancements to JSON Schema. They have expanded its capabilities and introduced standardized features. |
There was a problem hiding this comment.
They have expanded
Avoid to use Third person ... use first person. Instead "They have expended" use "We have expanded"
|
|
||
|
|
||
| ## 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. |
There was a problem hiding this comment.
I'll suggest to keep this initial paragraph
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.
Here we need to explain what problem is JSON Schema solving before explaining how it actually works.
I like this article:https://nordicapis.com/a-guide-to-json-schema/
I think we need this structure:
- Example of a JSON document.
- Explain the problem without JSON Schema. (the article explains it very well)
- JSON Schema to the rescue to solve the problem.
And after this we go with the step by step stuff
pages/overview/what-is-jsonschema.md
Outdated
|
|
||
|
|
||
| ## 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. | ||
| 1. **Define the rules**: 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). |
There was a problem hiding this comment.
using various [keywords]
I'll suggest saying: using [keywords]
pages/overview/what-is-jsonschema.md
Outdated
|
|
||
| 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. | ||
| 2. **Create the schema**: Use the defined rules to create a JSON Schema that represents the expected structure and format of your JSON data. |
There was a problem hiding this comment.
IMHO step 1 is in reality part of the step 2.... Can why try to keep both as one single step?
pages/overview/what-is-jsonschema.md
Outdated
|
|
||
| 3. **Choose a validator**: 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. | ||
|
|
||
| 4. **Validate the documents**: Use the selected validator to validate your JSON documents against the created JSON Schema. |
There was a problem hiding this comment.
I think we should keep consistency with the glossary of terms and for this section I suggest we focus in 3 elements: schema, keywords and instance.
- Keywords and Schema are used in step 1.
- Here I suggest to use instance instead of document.
pages/overview/what-is-jsonschema.md
Outdated
| * We have created an `instance` of the `schema` we defined as an example in step 2. | ||
| * Since the data is valid, we will not get any output. In case of invalid data, we will get a `jsonschema.exceptions.ValidationError` exception. | ||
|
|
||
| 5. **Utilize the validated data**: 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. |
There was a problem hiding this comment.
Instead of "Utilize the validated data" I'll suggest something more inspiring like "Apply to your use case"
| * **Simplify testing and validation**: JSON Schema helps to reduce the code's complexity and the development time by simplifying your validation logic. | ||
| * **Easy and reliable data exchange**: JSON Schema enables reliable, eventually consistent data exchange at scale. | ||
| * **Interoperability and Extensibility**: JSON Schema provides an extensible interoperability layer to your solution in multiple languages and platforms. | ||
| * **Huge tooling ecosystem**: JSON Schema is a vibrant and growing ecosystem of production ready Open Source tools implemented by the Community | ||
|
|
||
|
|
||
| ## Next steps |
There was a problem hiding this comment.
The next steps section should contain:
Next steps
To start using JSON Schema, see Creating your first schema.
Learn more
Learn more about the specification:
Join the community
To get involved with our community, please make sure you are familiar with the project's Code of Conduct.
- Join JSON Schema Slack. This is the best place to ask questions, learn, get help, or discuss all things JSON Schema.
- Attend our public JSON Schema meetings. We hold Office Hours every first Tuesday at 15:00 BST (and by appointment) and Open Community Working Meetings every Monday at 14:00 PT.
- Follow our YouTube channel. Find recordings of our public community meetings and JSON Schema learning resources.
- Read our blog. Find the latest and greatest stories from our community.
There was a problem hiding this comment.
Yes, this content is there already. I didn't make any changes to this 😅
Signed-off-by: Akanksha Kushwaha <cmakanksha@gmail.com>
Signed-off-by: Akanksha Kushwaha <cmakanksha@gmail.com>
pages/overview/what-is-jsonschema.md
Outdated
|
|
||
| ## 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. | ||
|
|
||
| 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. | ||
| ### What is a JSON Document |
There was a problem hiding this comment.
I'll suggest to remove this heading and let the previous paragraph flow to the next one. The story works well and I think we don't need the an extra heading here.
pages/overview/what-is-jsonschema.md
Outdated
| * 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. | ||
|
|
||
|
|
||
| ### Without JSON Schema |
There was a problem hiding this comment.
Instead of the current sentence "Without JSON Schema" I'll suggest something like "The challenge"
pages/overview/what-is-jsonschema.md
Outdated
| 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. | ||
|
|
||
|
|
||
| ### Harness the power of JSON Schema |
There was a problem hiding this comment.
Instead of the current sentence "Harness the power of JSON Schema" I'll suggest something like "JSON Schema to the rescue"
pages/overview/what-is-jsonschema.md
Outdated
| * 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, |
There was a problem hiding this comment.
Replace , by : at the end of this sentence "Taking an example of a JSON document representing a customer order"
pages/overview/what-is-jsonschema.md
Outdated
|
|
||
| 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. | ||
| * **Simplify testing and validation**: JSON Schema helps to reduce the code's complexity and the development time by simplifying your validation logic. |
There was a problem hiding this comment.
We made some changes in the messaging of the Why orgs adopt JSON Schema and this is the last version:
- 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.
Signed-off-by: Akanksha Kushwaha <cmakanksha@gmail.com>
Thank you so much! I've updated the PR with the suggested changes. |
pages/overview/what-is-jsonschema.md
Outdated
| * 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 of validating JSON data |
There was a problem hiding this comment.
| ### The challenge of validating JSON data | |
| ### The challenge |
I think is better to leave it as "The challenge" and leave the people read it instead of fully describing it in the title.
There was a problem hiding this comment.
Okay, will just change it.
Signed-off-by: Akanksha Kushwaha <cmakanksha@gmail.com>
Thank you! I'll make the suggested changes and update the PR. |
Signed-off-by: Akanksha Kushwaha <cmakanksha@gmail.com>
|
@aku1310 Thanks for mentioning me to get my attention. Very much the best way =D |
Signed-off-by: Akanksha Kushwaha <cmakanksha@gmail.com>
Signed-off-by: Akanksha Kushwaha <cmakanksha@gmail.com>
Signed-off-by: Akanksha Kushwaha <cmakanksha@gmail.com>
Thank you! I've updated the PR with the suggested changes. |
Signed-off-by: Akanksha Kushwaha <cmakanksha@gmail.com>
|
Hi @Relequestual! |
There was a problem hiding this comment.
Thanks for your continued work on this!
I see @benjagm previously made a review, so let's also wait for him to re-review.
|
Thank you so much! I just have one small thing to fix, I'll update it in a minute. Sorry for the inconvenience. 😅 |
Signed-off-by: Akanksha Kushwaha <cmakanksha@gmail.com>
How it workssection by adding steps with explanation and code snippet where necessary. (Currently working on adding an illustration to this section as well to make it more visually appealing)Why JSON Schemainto 2 different sections for developers and organizations to show the benefits in a better way.