json-schema-org / json-schema-org/website

[📝 Docs]: Add sub-navigation menu in the "JSON data types" portion of the docs

Open
#1,820 11 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

📝 Documentation Status: Stale Status: Triage
Dominant language
HTML
Stars
169
Forks
484
Avg merge
2d 2h
Merged PRs (30d)
6

Description

What Docs changes are you proposing?

The "JSON data types" part of the documentation is quite difficult to use.

As an example, let's say I want to read about the "object" type.

There's no way to see what the general sub-sections of the object documentation is.
Things like Required Properties, Property Names, Size, Pattern Properties, etc.

It would be incredibly helpful to have a little contents menu (wikipedia-style) at the top of each major JSON Schema data type.

That way someone who is new to the schema can quickly explore the features, configurations, etc. of each major type.

For context: I use JSON Schema only for OpenAI tool definitions so I may not be the most "ideal" user. However, in general, writing schemas seems to be a big part of the use cases and currently the documentation isn't easy to traverse when trying to write schemas, expand schemas, or just learn and create more advanced ones.

Over the last year I've noticed the left-side navigation hasn't changed but the data type schemas seem to be growing with more and more features. In the proposed contents menu at the top you could even use badges to indicate new additions, draft specific ones, etc.

Thank you for your consideration!

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the linked JSON data types documentation, especially the object page and its sections such as Required Properties, Property Names, Size, and Pattern Properties. Define the navigation structure for each major JSON Schema data type, then verify that every type page has a visible contents menu covering its documented subsections.

Written by the indexing model from the issue text.

Assessment

Tech stack
html
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.