json-schema-org / json-schema-org/website
Please clarify the examples of "Extending Closed Schemas" with Schema references
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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