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

[kwennB]

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

• 2020-12
• 2019-09
• Draft 07
• Draft 06
• Draft 05

Specification Links

Migration

Release Notes

JSON Hyperschema

---

Draft Template

• Header
• Introduction
• Links
• Release notes

Sample

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

Authors:

• Austin Wright
• Henry Andrews
• Ben Hutton
• Greg Dennis

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

• Specifications
  • Core: draft-bhutton-json-schema-01 (changes)
  • Validation: draft-bhutton-json-schema-validation-01 (changes)
  • Relative JSON Pointer: draft-bhutton-relative-json-pointer-00 (changes)
  • Published: 16-June-2022
• General use meta-schemas
  • JSON Schema meta-schema
  • JSON Hyper-Schema meta-schema (2019-09 Hyper-Schema with 2020-12 Validation)
  • JSON Hyper-Schema Link Description Object meta-schema
• Individual vocabulary meta-schemas
  • Core Vocabulary meta-schema
  • Applicator Vocabulary meta-schema
  • Validation Vocabulary meta-schema
  • Unevaluated Vocabulary meta-schema
  • Format Annotation Vocabulary meta-schema
  • Format Assertion Vocabulary meta-schema
  • Content Vocabulary meta-schema
  • Meta-Data Vocabulary meta-schema
• Output schemas
  • JSON Schema recommended output schema
• Output examples
  • JSON Schema verbose output example

Obsolete Draft 2020-12 Documents

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

• Core: draft-bhutton-json-schema-00 (changes)
• Validation: draft-bhutton-json-schema-validation-00 (changes)

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: #801
This PR fix will be sent in two separate PRs.

• PR 1 - Specification navigation menu
• PR 2 - Draft template

Are you working on this?

Yes

Code of Conduct

• I agree to follow this project's Code of Conduct

[github-actions]

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]

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

[kwennB]

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

No, they'll be two separate PRs.

[benjagm]

they'll be two separate PRs.

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

[kwennB]

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.

[kwennB]

Hello @benjagm this issue now has an open PR. #819
Decided to have it all in one PR. Thank you.

[gregsdennis]

I have reservations about rebuilding already-published specifications. These were published by IETF and should remain in the format they created.

cc: @jdesrosiers

[benjagm]

This is not republishing, it is just organizing the information we already have. As of now we only have the release notes and the links of each draft and this template intends to just put all the information together to makes the users life easier. We'll add a link to the IETF version.

[kwennB]

Hello @gregsdennis, this issue does not re-published nor re-edit the specification. Like @benjagm said "it is only organization".
The fix is to organize the look for the already presented information. The specification details including, the release notes, hyper-schema notes, core spec, and validation spec are still unchanged.
We are prioritizing having a more "modern" look for the current overall documentation.

[gregsdennis]

Okay, sounds good. It appears I may have misunderstood this issue full stop as long as the specification documents themselves are not changing I'm okay with this.

[kwennB]

Yes, the specification documents are not changing. Thank you @gregsdennis. We will be sharing details about our open docs meeting soon. It'll be nice to join in and get more ideas about the docs improvements we are working on.

If it's okay with you, I'll ping you here once it's shared. Cheers.