Skip to content

Add local $ref resolution helpers and propagate nested-ref document context#542

Open
andreyyudin wants to merge 1 commit intopb33f:mainfrom
andreyyudin:feat/local-ref-resolution-doc-context
Open

Add local $ref resolution helpers and propagate nested-ref document context#542
andreyyudin wants to merge 1 commit intopb33f:mainfrom
andreyyudin:feat/local-ref-resolution-doc-context

Conversation

@andreyyudin
Copy link
Contributor

Summary

This PR adds reusable local reference-resolution helpers and ensures nested-reference context settings are consistently propagated from document-level config into index/resolver config.

What changed

  • Added ResolveReferenceValue in index:
    • Resolves refs through SpecIndex when available.
    • Falls back to local JSON Pointer resolution (# / #/...) via document data provider.
    • Supports escaped and URL-encoded JSON Pointer segments.
  • Added ResolveRefsInNode in index:
    • Recursively resolves local $ref values in YAML nodes.
    • Preserves non-local refs.
    • Merges sibling fields with resolved mappings (sibling values win on key conflicts).
    • Guards against circular/self-referential loops and safely falls back when unresolved.
  • Added ResolveNestedRefsWithDocumentContext to datamodel.DocumentConfiguration.
  • Wired ResolveNestedRefsWithDocumentContext through:
    • datamodel/low/v2/createDocument
    • datamodel/low/v3/createDocument
    • SpecIndexConfig.ToDocumentConfiguration mapping

Why

Nested relative refs can require document-context-aware resolution to behave correctly across split specs. This PR makes that behavior configurable end-to-end and adds reusable helpers for local $ref handling and pointer resolution.

Compatibility

  • Non-breaking, additive change.
  • Default behavior remains unchanged unless ResolveNestedRefsWithDocumentContext is explicitly enabled.

- add ResolveReferenceValue with SpecIndex lookup and local JSON Pointer fallback
- add ResolveRefsInNode to recursively resolve local $ref mappings and merge sibling fields
- add ResolveNestedRefsWithDocumentContext to DocumentConfiguration and wire it through v2/v3 document creation
- map ResolveNestedRefsWithDocumentContext in SpecIndexConfig.ToDocumentConfiguration
- expand tests for helper behavior and config propagation
@codecov
Copy link

codecov bot commented Mar 11, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.61%. Comparing base (39e91d7) to head (48b5a21).

Additional details and impacted files
@@           Coverage Diff            @@
##             main     #542    +/-   ##
========================================
  Coverage   99.60%   99.61%            
========================================
  Files         234      236     +2     
  Lines       27886    28033   +147     
========================================
+ Hits        27777    27926   +149     
+ Misses         66       65     -1     
+ Partials       43       42     -1     
Flag Coverage Δ
unittests 99.61% <100.00%> (+<0.01%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant