search

json-schema-org / website

JSON Schema website
https://json-schema.org
Other
39 stars 122 forks source link

[📝 Docs]: Implement the Spec restructuring (Docs Website) #791

Open kwennB opened 1 week ago

kwennB commented 1 week ago

What Docs changes are you proposing?

Description

This issue relates to restructuring the Specification docs on the JSON Schema Website. It resolves the b part of checklist 1 for Release 4 of the Execute the documentation strategy #158 .

Specification navigation menu

Intro or Overview
Versions
Specification Links
Migration
Release Notes
JSON Hyperschema

Draft Template

Sample

Specification: https://json-schema.org/draft/2020-12/json-schema-core.html

Authors:

Published: 16 June 2022

Metaschema: https://json-schema.org/draft/2020-12/schema

Implementations: https://bowtie.report/#/dialects/draft2020-12

Status: Stable

Introduction

[Add texts here]

Access all data connected to draft 2020-12

Obsolete Draft 2020-12 Documents

These were updated without changing functionality or meta-schemas due to a few errors and unclear sections.

Release Notes

2020-12 Release Notes

The previous draft (2019-09) introduced a lot of new concepts including $recursiveRef/$recursiveAnchor, unevaluatedProperties/unevaluatedItems, vocabularies, and more. Since then, these new features have seen multiple implementations and usage in real schemas. This draft is mostly dedicated to changes related to applying the lessons we've learned about implementing and using these new features in the wild.

This document attempts to put information most useful to schema authors toward the top and information for implementation authors toward the bottom.

Changes to items and additionalItems

The keywords used for defining arrays and tuples have been redesigned to help lower the learning curve for JSON Schema. Since the items keyword was used for both types, we would often see people mistakenly defining a tuple when they meant to define an array and not understand why only the first item in the array was validating.

The items and additionalItems keywords have been replaced with prefixItems and items where prefixItems has the same functionality as the array-of-schemas for of the old items and the new items keyword has the same functionality as the old additionalItems keyword.

Although the meaning of items has changed, the syntax for defining arrays remains the same. Only the syntax for defining tuples has changed. The idea is that an array has items (items) and optionally has some positionally defined items that come before the normal items (prefixItems).

The above sample illustrates the changes for the draft template.

Resolves: https://github.com/json-schema-org/website/issues/801 This PR fix will be sent in two separate PRs.

Are you working on this?

Yes

Code of Conduct

github-actions[bot] commented 1 week ago

Welcome to the JSON Schema Community. We are so excited you are here! Thanks a lot for reporting your first issue!! 🎉🎉 Please make sure to take a look to our contributors guide if you plan on opening a pull request. For more details check out README.md file.

benjagm commented 1 day ago

Thanks Blessing. Is this going to be all in one PR?

kwennB commented 1 day ago

Thanks Blessing. Is this going to be all in one PR?

No, they'll be two separate PRs.

benjagm commented 1 day ago

they'll be two separate PRs.

Thanks Blessing. Can you please add the details to the issue?

kwennB commented 1 day ago

they'll be two separate PRs.

Thanks Blessing. Can you please add the details to the issue?

Thank you Ben, I've updated the issue.