Restructure what is JSON Schema for clarity #679
Conversation
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Welcome to the JSON Schema Community. Thanks a lot for creating your first pull request!! 🎉🎉 We are so excited you are here! We hope this is only the first of many! For more details check out README.md file.
There was a problem hiding this comment.
Thanks a lot Judith! This has been a great start. I added some comments:
- How it works:
- Add the missing image.
- Add section tittle and paragraph for context.
- We need to rephrase the titles of the benefits for developers and organizations to match the format "JSON Schema enable developers to ..." and "JSON Schema enable organizations to ..."
Excellent work so far. THANKS!
benjagm
added
the
Status: In Progress
There was a problem hiding this comment.
This is looking great @Nickyshe The simplification of the messaging makes it easier for readers to through all the content.
The only area I think we should continue working on "How JSON Schema works?" and for it I left some comments are suggestions.
Great job! We are very close!!
added new image(how-json-schema-works)
modified heading "How JSON Schema works"
* Restructure what is JSON Schema for clarity * Made changes to suggestion * Suggested changes corrected on what is JSON schema page added new image(how-json-schema-works) * added modified image modified heading "How JSON Schema works" * Small adjustment and image location --------- Co-authored-by: Benjamin Granados <[email protected]>
|
|
||
| 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**. | ||
| 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. |
There was a problem hiding this comment.
I suggest using "JSON instances" instead of "JSON documents" (use consistent terms; do not introduce new undefined terms).
There was a problem hiding this comment.
Thanks a lot for the suggestion David! We'll definitely change this!
|
|
||
| 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. |
There was a problem hiding this comment.
importantly: "JSON Schemas are described with JSON documents"
|
|
||
| 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. |
There was a problem hiding this comment.
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
|
|
||
| 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. |
There was a problem hiding this comment.
the flow represented by the image is (to me) misleading. It implies the JSON schema is "transformed" or flows into the JSON Instance which yields something that is then fed to the JSON Validator. I propose something more like:
.---------------------------------.
| |
o---- [ ] JSON Instance -\ |
| \ |
| / { } ------ (:green check)
o---- [ ] JSON Schema ---/ JSON |
| Validator |
`---------------------------------'
There was a problem hiding this comment.
or replace the green checkmark with validation result, as not all results are "green"/valid
|
Thank a lot for the comments @DavidBiesack ! Great feedback!! I'll work on a new version addressing all your suggestions. |
|
This is the new PR adding David's suggestions: #724 |
* Restructure what is JSON Schema for clarity * Made changes to suggestion * Suggested changes corrected on what is JSON schema page added new image(how-json-schema-works) * added modified image modified heading "How JSON Schema works" * Small adjustment and image location --------- Co-authored-by: Benjamin Granados <[email protected]>
What kind of change does this PR introduce?
This issue is for restructuring and rewriting what is Json schema page for clarity, consistent use of pronouns, revamp headings and ensure the tone is consistent throughout the documentation
Issue Number:
Screenshots/videos:
If relevant, did you update the documentation?
Yes I updated the documentation