👌 Include JSON location in $ref resolution errors#1736
Merged
Conversation
`resolve_refs` errors (circular / invalid / missing $ref) gave no indication of *where* the faulty reference was, forcing users to hunt through the whole `needs_schema_definitions`. Thread the JSON path of the current item through the recursive walk and append it to each error, e.g.: Circular reference detected for 'type-impl'. -> Circular reference detected for 'type-impl' (at $defs.type-impl.allOf[0]). Reference 'type-spec' not found in definitions. -> Reference 'type-spec' not found in definitions (at schemas[0].select). Other config errors already carry a schema name via `get_schema_name`; this closes the gap for the global $ref-resolution pass.
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## master #1736 +/- ##
==========================================
+ Coverage 86.87% 89.37% +2.49%
==========================================
Files 56 72 +16
Lines 6532 10551 +4019
==========================================
+ Hits 5675 9430 +3755
- Misses 857 1121 +264
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
ubmarco
approved these changes
Jun 30, 2026
Merged
chrisjsewell
added a commit
that referenced
this pull request
Jul 1, 2026
Prepares the **8.2.0** release. ## Version bumps - `sphinx_needs/__init__.py` → `8.2.0` - `.github/workflows/docker.yaml` (`NEEDS_VERSION`) → `8.2.0` - `docs/_static/tutorial_needs.json` regenerated with the new version ## Changelog Rewrote the `Unreleased` section into a user-friendly `8.2.0` entry. Reviewing every PR since v8.1.1 surfaced several that were missing from the draft (notably the full variant-data feature set), so those are now included and categorised. The entry leads with the two headline features: - **Variant data** — a dedicated narrative section tying together the new variant-data tooling (#1715, #1716, #1721, #1737): `needs_variant_data` / `needs_variant_data_file`, the inline `<{ ... }>` field syntax, the `variant` role, and the `if` directive — with runnable examples showing the shared `var` namespace across filters, fields, prose, and whole blocks. - **`network_back` schema validation** (#1731) — incoming-link validation, letting coverage rules ("every requirement must be covered by a test") be expressed once on the target. Remaining changes are grouped into **Improvements** (#1632, #1717, #1736, #1730, context7), **Deprecations** (`needs_filter_data`), **Breaking changes** (Open-Needs removal, #1732), and **Bug fixes** (#1727, #1371, #1564). Internal/test-only PRs were intentionally omitted. Docs build cleanly — all cross-references in the new section resolve without warnings. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- _Generated by [Claude Code](https://claude.ai/code/session_01HQwraRU189oRFK5j4yRiYo)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
resolve_refserrors (circular / invalid / missing$ref,$ref-with-siblings) gave no indication of where the faulty reference lived, so on a non-trivialneeds_schema_definitionsusers had to hunt through the whole config to find it. Other config errors already carry a schema name viaget_schema_name(id[idx]); the global$ref-resolution pass was the gap.This threads the JSON path of the current item through the recursive
resolve_refswalk and appends it to each error message.Before → after
The path is the JSON location from the root of
needs_schema_definitions(schemas[i]...or$defs.<name>...), inherently encoding which schema (by index) the$refsits in. When there is no path (root), the suffix is omitted, so behaviour is unchanged for that degenerate case.Notes
ref_*config fixtures intests/schema/__snapshots__/test_schema.ambrnow include the location.