Skip to content

docs(understanding-json-schema): complete 'Extending Recursive Schemas' guide - #2632

Open
Siddharth-Dangi wants to merge 1 commit into
json-schema-org:mainfrom
Siddharth-Dangi:docs/extending-recursive-schemas
Open

Siddharth-Dangi wants to merge 1 commit into
json-schema-org:mainfrom
Siddharth-Dangi:docs/extending-recursive-schemas

Conversation

@Siddharth-Dangi

@Siddharth-Dangi Siddharth-Dangi commented Nov 7, 2026 •

Copy link
Copy Markdown

What kind of change does this PR introduce?

Documentation update.

Issue Number:

Summary

This pull request completes the long-standing "Documentation Coming Soon" placeholder in the Extending Recursive Schemas section of Understanding JSON Schema (pages/understanding-json-schema/structuring.md).

Key Additions:

  1. Conceptual Explanation: Explains why standard static $ref: "#" fails when extending recursive structures (e.g. adding properties to all recursive child nodes).
  2. Dynamic Referencing: Introduces $dynamicAnchor and $dynamicRef (Draft 2020-12) using a clean, concrete tree (base) and labeled-tree (extended) example.
  3. Valid & Invalid Test Instances: Includes real-world valid tree instances and demonstrates how child nodes lacking extension properties are correctly rejected.
  4. Draft-Specific Comparison Tabs: Provides tabs comparing Draft 2020-12 ($dynamicRef/$dynamicAnchor bookending) with Draft 2019-09 ($recursiveRef/$recursiveAnchor) and historical drafts.

All examples have been verified against official meta-schemas and live Python jsonschema engines.

Does this PR introduce a breaking change?

No breaking change.

Checklist

…s' section

- Replaces the legacy 'Documentation Coming Soon' placeholder with a complete guide
- Explains dynamic referencing ($dynamicAnchor and $dynamicRef in Draft 2020-12)
- Provides tree and labeled-tree examples demonstrating polymorphic recursive extension
- Adds multi-draft comparison tabs for Draft 2020-12, Draft 2019-09, and Draft 4-7
@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Name Status Preview Last Commit
website ✅ Ready (View Log) Visit Preview d37e3b4

@codecov

codecov Bot commented Nov 7, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (ff13109) to head (d37e3b4).

Additional details and impacted files
@@            Coverage Diff            @@
##              main     #2632   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           31        31           
  Lines          737       737           
  Branches       229       229           
=========================================
  Hits           737       737           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

This branch was successfully deployed

1 active deployment
Preview — d37e3b41 Deployed Nov 7, 2026 by github-actions[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Ready to review

Development

Successfully merging this pull request may close these issues.

Implement the new website docs structure

1 participant