fix: resolve JSON schema $ref/$defs for UI display of titles and descriptions

[hartra344]

Commit Type

• fix - Bug fix

Risk Level

• Low - Minor changes, limited scope

What & Why

When users provide JSON schemas with $ref and $defs/definitions (e.g., in Parse JSON actions or Request triggers), the referenced definitions' titles, descriptions, and other metadata are not displayed in the designer UI even though validation still works correctly.

Root cause: The SchemaProcessor only handled cyclical $refs left over from Swagger dereferencing (via metadata). For standalone user-provided schemas, $ref pointers against $defs/definitions were never resolved, causing _dereferenceRefSchema() to return {} and all metadata (title, description, enum, etc.) to be lost.

This PR adds a dereferenceJsonSchema() utility that resolves local $ref pointers in standalone JSON schemas against their own $defs or definitions containers before they reach SchemaProcessor.

Closes #8689

Impact of Change

• Users: Schemas using $ref/$defs or $ref/definitions in Parse JSON actions and Request triggers will now correctly display titles, descriptions, and other metadata from referenced definitions in the designer UI.
• Developers: New exported dereferenceJsonSchema() utility available from @microsoft/logic-apps-shared. IJsonSchema type now includes $ref and $defs properties for JSON Schema Draft 2019-09+ support.
• System: No performance impact — dereferencing is a single-pass recursive walk with cycle detection, only triggered when $defs or definitions are present.

Test Plan

• Unit tests added/updated
• E2E tests added/updated
• Manual testing completed
• Tested in: 13 unit tests covering:
  • $defs resolution (JSON Schema 2019-09+)
  • definitions resolution (Draft 4/7)
  • Nested $refs (definition referencing another definition)
  • Direct and indirect cyclical $refs
  • External URL $refs (kept unchanged)
  • Non-existent definition refs (kept unchanged)
  • Title/description preservation
  • Multiple refs, array items, JSON Pointer encoding
  • Edge cases (null, undefined, empty $defs)

[github-actions]

🤖 AI PR Validation Report

PR Review Results

Thank you for your submission! Here's detailed feedback on your PR title and body compliance:

✅ PR Title

• Current: fix: resolve JSON schema $ref/$defs for UI display of titles and descriptions
• Issue: None — title follows conventional-commit style and clearly describes the change and intent.
• Recommendation: (Optional) You could shorten slightly or mention the consumer (designer UI) if desired, e.g. fix: resolve local JSON Schema $ref/$defs so designer shows titles/descriptions — but the current title is already high quality.

---

✅ Commit Type

• Properly selected (fix).
• Only one commit type selected in the PR body, which is correct.

---

✅ Risk Level

• The PR body selects Low and the PR has the risk:low label. This matches the code changes (adding a small utility, unit tests, and a couple of local call sites). Advised risk: Low.

---

✅ What & Why

• Current: Clearly described in the PR body with root cause and the introduced solution (dereferenceJsonSchema).
• Issue: None.
• Recommendation: None required — the explanation is concise and adequate.

---

✅ Impact of Change

• The Impact section is present and correctly describes Users, Developers, and System effects.
• Recommendation:
  • Users: Correctly notes metadata will now display in designer UI.
  • Developers: Notes new exported utility and type updates.
  • System: States no performance impact and reasoning — appropriate.

---

✅ Test Plan

• Unit tests were added (a new comprehensive spec file is present in the diff). The PR body marks Unit tests and Manual testing; E2E is intentionally not included.
• Assessment: Adequate. The presence of the detailed unit test coverage in the diff matches the Test Plan claim.
• Recommendation (optional): Consider adding a lightweight E2E or integration test that asserts the designer UI renders titles/descriptions when given a schema with $defs — only if you want additional coverage for the user-visible behavior.

---

⚠️ Contributors

• The Contributors section is blank.
• Assessment: This is optional and non-blocking.
• Recommendation: If others (PMs, designers, reviewers) contributed to the change, consider adding their names to give credit. If there are none, leaving it blank is fine.

---

⚠️ Screenshots/Videos

• No screenshots/videos included.
• Assessment: Optional. This PR fixes metadata display in the designer UI; while tests and code changes are sufficient, a single before/after screenshot could be useful for reviewers to quickly confirm the UX impact.
• Recommendation: Add a short before/after screenshot of the designer displaying title/description from a referenced definition if convenient. Not required to merge.

---

Summary Table

Section	Status	Recommendation
Title	✅	Title is good; optional minor rewording suggested
Commit Type	✅	Correct (fix)
Risk Level	✅	Low matches code changes and label
What & Why	✅	Clear and complete
Impact of Change	✅	Good coverage for Users/Developers/System
Test Plan	✅	Unit tests present and match claims
Contributors	⚠️	Optional: add credits if applicable
Screenshots/Videos	⚠️	Optional: add before/after screenshot for UI

---

Final message:
This PR passes the PR title/body checklist. The commit type and risk level are correctly selected and the risk:low label matches the declared Low risk. The PR body includes a clear What & Why, a detailed Impact section, and a matching Test Plan — and the diff includes the new utility, its export, the call sites, and comprehensive unit tests.

Minor, optional suggestions:

• Consider adding a short E2E/integration test that exercises the designer path (schema -> manifest -> UI) to lock in the user-visible behavior.
• Optionally include before/after screenshots demonstrating the UI change for reviewers.
• If others contributed, consider listing them in Contributors for credit.

Please update only if you want to add the optional items above; otherwise this PR is good to merge. Thank you for the clear description and thorough unit tests!

---

Last updated: Wed, 11 Feb 2026 19:18:22 GMT

[github-actions]

📊 Coverage check completed. See workflow run for details.

[github-actions]

📊 Coverage check completed. See workflow run for details.

[Copilot]

Pull request overview

This PR fixes issue #8689 where JSON schemas using $ref pointers to $defs or definitions don't display titles, descriptions, and other metadata in the Logic Apps designer UI. The fix adds a new dereferenceJsonSchema() utility that resolves local $ref pointers in user-provided schemas before they're processed by the SchemaProcessor, ensuring all metadata is preserved and displayed.

Changes:

• Added $ref and $defs properties to the IJsonSchema interface for JSON Schema 2019-09+ compatibility
• Created dereferenceJsonSchema() utility with cycle detection and JSON Pointer decoding per RFC 6901
• Integrated the utility into the designer library's schema processing pipeline
• Added comprehensive unit tests covering various scenarios including nested refs, cycles, and edge cases

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
libs/logic-apps-shared/src/utils/src/lib/models/openApiV2.ts	Extended IJsonSchema interface with $ref and $defs properties to support JSON Schema Draft 2019-09+
libs/logic-apps-shared/src/parsers/lib/common/helpers/dereferenceJsonSchema.ts	New utility function that resolves local $ref pointers with cycle detection and RFC 6901-compliant JSON Pointer decoding
libs/logic-apps-shared/src/parsers/lib/common/helpers/__test__/dereferenceJsonSchema.spec.ts	Comprehensive test suite with 13 test cases covering various dereferencing scenarios
libs/logic-apps-shared/src/parsers/index.ts	Exported the new dereferenceJsonSchema function for use across the codebase
libs/designer/src/lib/core/utils/outputs.ts	Integrated dereferenceJsonSchema() into the schema processing pipeline for Parse JSON actions and Request triggers

[github-actions]

📊 Coverage check completed. See workflow run for details.

[github-actions]

📊 Coverage check completed. See workflow run for details.