Modify non_json_data.md, document contentSchema keyword #1028
Conversation
valeriahhdez
added
📝 Documentation
built with Refined Cloudflare Pages Action⚡ Cloudflare Pages Deployment
|
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #1028 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 10 10
Lines 373 373
Branches 94 94
=========================================
Hits 373 373 ☔ View full report in Codecov by Sentry. |
| This process ensures that the non-JSON content is properly encoded for transmission and accurately decoded by the recipient, maintaining the integrity of the data throughout the processe. | ||
|
|
||
| <Keywords label="single: contentSchema single: media; contentSchema" /> | ||
|
|
There was a problem hiding this comment.
Based on the content of the contributing.md file and the Google style guide, I has just assumed that we are replacing the "keywords", "star" tags in the new documentation. Now, I'm not so sure about my assumption :). Please let me know. Thank you
There was a problem hiding this comment.
The goal of the review and editing work is to make sure that the documentation uses the tags according to the rules of the style guide: https://github.com/json-schema-org/website/blob/main/pages/md-style-guide.md
That could mean replacing the "Star" tag when it doesn't follow the guidelines with another tag best suited for the context.
Regarding the "Keywords" tag, we don't have it documented in the style guide, yet. But that is a topic for another conversation that I posted on the general channel.
|
I asked someone from the TSC to help us with the review. |
|
|
||
| To better understand how `contentEncoding` and `contentMediaType` are applied in practice, let's consider the process of transmitting non-JSON data: | ||
|
|
||
|  |
There was a problem hiding this comment.
|  | |
|  |
The image is now being shown. We need to add the image folder to make that work.
There was a problem hiding this comment.
Does the website support Mermaid diagrams (Example: https://github.com/json-schema-org/json-schema-spec/pull/1544/files)? If so, it might be nicer because it can be styled to match the rest of the site.
There was a problem hiding this comment.
Thanks for the recommendation. I added a version of the diagram in Mermaid to test if it works on our website. I'll remove the PNG file after we confirm it renders correctly.
There was a problem hiding this comment.
Looks like the website doesn't support mermaid 😢. That's too bad. Thanks for trying.
|
|
||
| To better understand how `contentEncoding` and `contentMediaType` are applied in practice, let's consider the process of transmitting non-JSON data: | ||
|
|
||
|  |
There was a problem hiding this comment.
Does the website support Mermaid diagrams (Example: https://github.com/json-schema-org/json-schema-spec/pull/1544/files)? If so, it might be nicer because it can be styled to match the rest of the site.
Co-authored-by: Jason Desrosiers <[email protected]>
This version includes changes suggested by Jason, Benjamin, Blessing, and Anitha
These changes introduce a better heading structure for scannability
What kind of change does this PR introduce?
Updates non_json_data.md by improving text for readability, adding a figure to illustrate the role of contentEncoding and contentMediaType in sharing non-JSON data, and documenting the contentSchema keyword.
Issue Number:
Screenshots/videos:
If relevant, did you update the documentation?
Yes, this is an update to the following document: https://json-schema.org/understanding-json-schema/reference/non_json_data
Summary
The contentSchema keyword was missing in the document Media: string-encoding non-JSON data. This pull request adds the missing keyword to the document, makes minor improvements to the text, and adds an explanatory image about the role of contentEncoding and contentMediaType in the transmission of non-JSON data.
Does this PR introduce a breaking change? No