add introductory guide to JSON Schema

[techmannih]

Issue Number:

• Closes [📝 Docs]: Create a standalone introductory guide to JSON Schema #1129

[techmannih]

@valeriahhdez please review this PR

[valeriahhdez]

@valeriahhdez please review this PR

Hi @techmannih,

Yes, I'll review it.

[DhairyaMajmudar]

@techmannih it seems like ci checks are failing pls. fix them

[github-actions]

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Name	Status	Preview	Last Commit
website	✅ Ready (View Log)	Visit Preview	94d74e5

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (72ae168) to head (94d74e5).

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #1148   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           10        10           
  Lines          373       373           
  Branches        94        94           
=========================================
  Hits           373       373           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[techmannih]

@DhairyaMajmudar done

@techmannih it seems like ci checks are failing pls. fix them

[valeriahhdez]

Hi @techmannih,

This is a good starting point!

I left some line comments but here are my high-level observations:

• It seems to me the document lacks clear goals where the reader starts at point A and finishes at point B.
• Because of this, the document jumps from very basic (empty schema) to complex (nested objects) without a clear progression.
• It needs to be improved to build knowledge incrementally.
• In some parts of the text, ideas don't flow naturally, for example when you talk about $ref keyword.
• It needs to be revised for style. I invite you to read and consult from time to time our style guide.

But overall, I think this is a good first draft. Let me know if you have any questions about these comments.

I look forward to the next iteration of improvements!

[benjagm]

How this new page differs from https://json-schema.org/overview/what-is-jsonschema

Why we need a new one?

[valeriahhdez]

How this new page differs from https://json-schema.org/overview/what-is-jsonschema

Why we need a new one?

To answer your questions @benjagm, I am pasting what I wrote in issue #1129. But let me know if anything needs further clarification.
The following documents:

• What is a schema?
• The basics

are formatted as book chapters which means that they present information in a sequential manner and each chapter builds upon the previous one. This means the reader needs to complete more than one chapter to complete a task or learning lesson. We want each one of our documentation to be self-contained so that readers can quickly find the information they are looking for.

An introductory guide to JSON Schema that is self-contained should comply with the following requirements to replace the book chapters mentioned above:

• clear learning goals for the reader
• a start and end points
• link to other learning resources
• be clear, concise, and accurate

However, I didn't mention in the issue that we can use one of the existing files for this self-contained guide; we don't need to create a new Markdown document. What we're aiming for with this PR is to replace the above-mentioned documents with this single self-contained one.

[valeriahhdez]

Hi @benjagm,

Can we continue working on this PR?

[benjagm]

Hi Team, I am not fully aligned with the goal of this issue. We already have a What is JSON Schema page in the overview section and a What is JSON Schema in Reference.

This PR is now adding a new page with the same information and also generating duplicities in the Reference section:

Honestly, I think https://json-schema.org/understanding-json-schema/about is enough.

[benjagm]

Hi @valeriahhdez and @techmannih . First of all sorry if my feedback was too direct here. It wasn't my intention so first of all let me apologize. We are so grateful for all the contributions... and sorry I'm my feedback was not transmitting that same spirit.

Looking into the root cause here I think there are 2 key elements:

• The issue [📝 Docs]: Create a standalone introductory guide to JSON Schema #1129 is stating that the expected outcome of this feature is creating a guide, however I think that is not correct. The resulting document is going to live into the Reference section, therefore we are expecting a Reference Document which goals and structure is totally different. I added this as comment to the issue but I think this is the first reason of the difference in terms of expectation.
• The second element, is creating another guide called "What is JSON Shema" we are creating a duplicity with "What is JSON schema" in the overview section, a page with almost same title than "What is a Schema". In my opinion, what we would need here is an "Introduction to the JSON Schema Reference" as a reference doc.

I hope this makes sense. And again, sorry for rushing my feedback in the previous review.

[valeriahhdez]

I agree this document shouldn't live in the reference documentation, but we could move it to the Guides content bucket that I'm proposing for the New Architecture Infrastructure PR. Regarding the title, the idea is to replace What is a schema? and The basics with a single document (this one), so there would be no repetition.

I don't think the reference documentation needs an introductory document. The overview pages I am proposing to add in the new architecture infrastructure PR already describe what the reference documentation contains, giving the readers clear expectations for this content bucket.

Whatever we end up doing, I do think something has to be done about these documents

• What is a schema?
• The basics

because they are formatted as book chapters instead of self-contained documents.