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

Please clarify the examples of "Extending Closed Schemas" with Schema references

Open
#196 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

As discussed in json-schema-org/understanding-json-schema#197, the examples for "Extending Closed Schemas" at https://json-schema.org/understanding-json-schema/reference/object.html?highlight=extending%20closed%20schemas#extending-closed-schemas are confusing, because of using an allOf construct with a single constraint as replacement for a schema defined elsewhere that is subject to extension.

The key point of the section is the extension of a schema defined independently. Therefore, the examples should use the schema referencing syntax with $ref and $defs. Otherwise, the reader could be distracted from the schema extension aspect. Since the referencing constructs are not yet introduced at this point when reading the documents linearly, a forwards pointer to the definition of the schema reference constructs should be introduced.

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 at the “Extending Closed Schemas” section linked in the issue and review the discussion in json-schema-org/understanding-json-schema#197. Update the examples to demonstrate independent schemas with $ref and $defs, and add a forward pointer to the schema-reference documentation; the section should clearly explain schema extension without the distracting single-constraint allOf workaround.

Written by the indexing model from the issue text.

Assessment

Tech stack
html, json
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.