json-schema-org
[📝 Docs]: Implement the Spec page restructuring (Docs Website)
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
- Output schemas
- Output examples
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: https://github.com/json-schema-org/website/issues/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
- [X] I agree to follow this project's Code of Conduct
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.
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "Published by a pub.dev verified publisher"){kind=small}
Thanks Blessing. Is this going to be all in one PR?
No, they'll be two separate PRs.
they'll be two separate PRs.
Thanks Blessing. Can you please add the details to the issue?
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.
Hello @benjagm this issue now has an open PR. https://github.com/json-schema-org/website/pull/819 Decided to have it all in one PR. Thank you.
I have reservations about rebuilding already-published specifications. These were published by IETF and should remain in the format they created.
cc: @jdesrosiers
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.
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.
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.
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.