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?