Use $resolveReference to resolve canonical URL to OCL repo version

[paynejd]

OCL's FHIR Service currently resolves canonical URLs and relative references using internal logic. OCL provides a standardized $resolveReference operation that handles version-aware resolution of canonical URLs (e.g. https://loinc.org) and OCL relative URLs (e.g. /orgs/Regenstrief/sources/LOINC/) to a specific repository versions.

Problem Statement

Use of $resolveReference addresses these challenges:

• Multi-tenancy conflicts: Multiple organizations may publish content using the same canonical URLs but in different OCL namespaces
• Version ambiguity: Resolving to "latest" version vs. specific versions may not be handled consistently across FHIR operations
• Maintenance burden: Custom resolution logic scattered across different endpoints/services rather than centralized
• Future-proofing: As OCL evolves, it needs a needs a single source of truth across the entire OCL stack

Proposed Solution

Refactor the FHIR service to use OCL's $resolveReference operation for resolving all repository references before performing FHIR operations.

MVP requirements:

1. Replace inline resolution logic in the FHIR service with calls to $resolveReference

• Applies to all FHIR CRUDS requests, operations ($lookup, $validate-code, $translate, etc.), and any other endpoint that resolves terminology references

2. Handle version resolution

• No version specified --> use $resolveReference to resolve to latest

3. Implicit namespace context

• OCL infers namespace from request context when not explicit -- this should work fine for the MVP even if there are multiple uses of a canonical URL defined in OCL, but we need to test and confirm that there are no gaps

Acceptance Criteria

• All FHIR operations that reference repositories (e.g. CodeSystems, ValueSets, or ConceptMaps) use $resolveReference
• Version-specific requests resolve to the correct version
• Versionless requests resolve according to latest based on namespace configuration
• Multi-tenant scenarios correctly resolve different resources with same canonical URL in different namespaces
• Error handling gracefully manages resolution failures (404, ambiguous references, repo version not found)
• Unit and integration tests cover key scenarios:
  • Only one use of canonical: canonical with version, canonical without version
  • Canonical defined in multiple namespaces: canonical with version, canonical without version -- should resolve based on OCL's canonical URL registry configuration

Resources

Documentation: https://docs.openconceptlab.org/en/latest/oclapi/apireference/resolveReference.html

Additional work post-MVP

1. Both canonical URLs and OCL relative URLs are supported by the FHIR service and resolve correctly
2. Explicit namespace context: Support request-level control of namespace and pass namespace to $resolveReference for multi-tenant resolution

[ocl-automation]

Automated Triage — 2026-04-06

Dimension	Score
Complexity	4
Scope	4
Clarity	3
Dependency	3
Risk	4

Decision: decision/human-review
Type: type/feature
Signals: signal/high-risk, signal/large-scope, signal/has-dependencies

This involves implementing a new standardized operation ($resolveReference) to replace existing internal logic, affecting multiple components of the FHIR service with significant architectural implications. The issue describes the problem well but lacks specific implementation details and acceptance criteria.

---

Generated by ticket-triage pipeline v3. Model: anthropic/claude-sonnet-4 (openrouter).