gdc-common-utils-ts 2.3.26 → 2.3.27

package/dist/utils/bundle-document-builder.js

@@ -5,7 +5,9 @@ import { ConditionClaim } from '../models/interoperable-claims/condition-claims.
 import { DiagnosticReportClaim } from '../models/interoperable-claims/diagnostic-report-claims.js';
 import { MedicationStatementClaim } from '../models/interoperable-claims/medication-statement-claims.js';
 import { ClaimConsent } from '../models/consent-rule.js';
-import { allergyIntoleranceFlatToFhirR4, appointmentFlatToFhirR4, carePlanFlatToFhirR4, clinicalImpressionFlatToFhirR4, compositionFlatToFhirR4, conditionFlatToFhirR4, consentFlatToFhirR4, convertFhirResourceToClaims, coverageFlatToFhirR4, deviceFlatToFhirR4, documentReferenceFlatToFhirR4, diagnosticReportFlatToFhirR4, encounterFlatToFhirR4, flagFlatToFhirR4, flatClaimsToFhirResource, immunizationFlatToFhirR4, locationFlatToFhirR4, medicationStatementFlatToFhirR4, observationFromFlatToFhirR4, organizationFlatToFhirR4, procedureFlatToFhirR4, practitionerRoleFlatToFhirR4, relatedPersonFlatToFhirR4, } from './clinical-resource-converters.js';
+import { allergyIntoleranceFlatToFhirR4, appointmentResponseFlatToFhirR4, appointmentFlatToFhirR4, carePlanFlatToFhirR4, clinicalImpressionFlatToFhirR4, compositionFlatToFhirR4, conditionFlatToFhirR4, consentFlatToFhirR4, convertFhirResourceToClaims, coverageFlatToFhirR4, deviceFlatToFhirR4, deviceUseStatementFlatToFhirR4, documentReferenceFlatToFhirR4, diagnosticReportFlatToFhirR4, encounterFlatToFhirR4, flagFlatToFhirR4, flatClaimsToFhirResource, immunizationFlatToFhirR4, locationFlatToFhirR4, medicationStatementFlatToFhirR4, observationFromFlatToFhirR4, organizationFlatToFhirR4, procedureFlatToFhirR4, practitionerRoleFlatToFhirR4, relatedPersonFlatToFhirR4, } from './clinical-resource-converters.js';
+/** Version-independent FHIR SearchParameter claim context. */
+const FHIR_API_CLAIMS_CONTEXT = 'org.hl7.fhir.api';
 function asTrimmedString(value) {
     if (value === undefined || value === null)
         return '';
@@ -22,8 +24,7 @@ export function getSimpleClaimAttributeName(key) {
     if (!value)
         return '';
     const knownPrefixes = [
-        'org.hl7.fhir.r4.',
-        'org.hl7.fhir.api.',
+        `${FHIR_API_CLAIMS_CONTEXT}.`,
     ];
     for (const prefix of knownPrefixes) {
         if (value.startsWith(prefix)) {
@@ -39,19 +40,13 @@ export function extractFlatClaimValue(record, key) {
     const direct = record[normalizedKey];
     if (typeof direct === 'string' && direct.trim())
         return direct.trim();
-    const contextualizedR4 = record[`org.hl7.fhir.r4.${normalizedKey}`];
-    if (typeof contextualizedR4 === 'string' && contextualizedR4.trim())
-        return contextualizedR4.trim();
-    const contextualizedApi = record[`org.hl7.fhir.api.${normalizedKey}`];
+    const contextualizedApi = record[`${FHIR_API_CLAIMS_CONTEXT}.${normalizedKey}`];
     if (typeof contextualizedApi === 'string' && contextualizedApi.trim())
         return contextualizedApi.trim();
     const nested = record?.meta?.claims?.[normalizedKey];
     if (typeof nested === 'string' && nested.trim())
         return nested.trim();
-    const nestedR4 = record?.meta?.claims?.[`org.hl7.fhir.r4.${normalizedKey}`];
-    if (typeof nestedR4 === 'string' && nestedR4.trim())
-        return nestedR4.trim();
-    const nestedApi = record?.meta?.claims?.[`org.hl7.fhir.api.${normalizedKey}`];
+    const nestedApi = record?.meta?.claims?.[`${FHIR_API_CLAIMS_CONTEXT}.${normalizedKey}`];
     if (typeof nestedApi === 'string' && nestedApi.trim())
         return nestedApi.trim();
     return '';
@@ -59,12 +54,33 @@ export function extractFlatClaimValue(record, key) {
 function claimsToFlatStrings(claims) {
     const out = {};
     for (const [key, value] of Object.entries(claims || {})) {
-        if (value === undefined || value === null)
+        if (value === undefined || value === null || key === '@context')
+            continue;
+        const canonicalKey = getSimpleClaimAttributeName(key);
+        if (canonicalKey === key)
+            continue;
+        out[canonicalKey] = typeof value === 'string' ? value : String(value);
+    }
+    for (const [key, value] of Object.entries(claims || {})) {
+        if (value === undefined || value === null || key === '@context')
+            continue;
+        const canonicalKey = getSimpleClaimAttributeName(key);
+        if (canonicalKey !== key)
             continue;
         out[key] = typeof value === 'string' ? value : String(value);
     }
     return out;
 }
+/** Rejects version-specific FHIR resource contexts from the claims contract. */
+function assertFhirApiClaimsContext(claims) {
+    const context = asTrimmedString(claims?.['@context']);
+    const hasVersionSpecificContext = context.startsWith('org.hl7.fhir.')
+        && context !== FHIR_API_CLAIMS_CONTEXT;
+    const hasVersionSpecificExpandedKey = Object.keys(claims || {}).some((key) => key.startsWith('org.hl7.fhir.') && !key.startsWith(`${FHIR_API_CLAIMS_CONTEXT}.`));
+    if (hasVersionSpecificContext || hasVersionSpecificExpandedKey) {
+        throw new Error(`FHIR claims require @context ${FHIR_API_CLAIMS_CONTEXT}. Version-specific FHIR resource contexts are not claim namespaces.`);
+    }
+}
 function ensureClaimsIdentifier(claims, resource) {
     const resourceType = asTrimmedString(resource?.resourceType);
     const identifierKey = resourceType ? `${resourceType}.identifier` : '';
@@ -202,7 +218,7 @@ export function prepareBundleDocumentForSubject(bundle, subjectDid, options = {}
         if (!resource || typeof resource !== 'object')
             continue;
         replacePatientSubjectReference(resource, normalizedSubjectDid);
-        const generated = convertFhirResourceToClaims(resource, options.context || 'org.hl7.fhir.r4');
+        const generated = convertFhirResourceToClaims(resource, options.context || FHIR_API_CLAIMS_CONTEXT);
         const existing = resource?.meta?.claims;
         const claims = {
             ...generated,
@@ -324,7 +340,7 @@ export function detectClaimsResourceType(claims) {
         return ResourceTypesFhirR4.DocumentReference;
     const firstContextualized = keys
         .map((key) => getSimpleClaimAttributeName(key))
-        .find((key) => key.includes('.'));
+        .find((key) => key.includes('.') && !key.startsWith(`${ResourceTypesFhirR4.Composition}.`));
     if (firstContextualized) {
         return firstContextualized.split('.')[0];
     }
@@ -332,10 +348,11 @@ export function detectClaimsResourceType(claims) {
 }
 export function convertClaimsToFhirResource(claims, version = 'r4') {
     void version;
+    assertFhirApiClaimsContext(claims);
     const flatClaims = claimsToFlatStrings(claims);
     const resourceType = detectClaimsResourceType(claims);
     const resource = convertClaimsToFhirResourceByType(flatClaims, resourceType);
-    const language = resourceType ? asTrimmedString(claims[`${resourceType}.language`]) : '';
+    const language = resourceType ? asTrimmedString(flatClaims[`${resourceType}.language`]) : '';
     return language ? { ...resource, language } : resource;
 }
 function convertClaimsToFhirResourceByType(flatClaims, resourceType) {
@@ -348,6 +365,8 @@ function convertClaimsToFhirResourceByType(flatClaims, resourceType) {
             return conditionFlatToFhirR4(flatClaims);
         case ResourceTypesFhirR4.DocumentReference:
             return documentReferenceFlatToFhirR4(flatClaims);
+        case ResourceTypesFhirR4.DeviceUseStatement:
+            return deviceUseStatementFlatToFhirR4(flatClaims);
         case 'Immunization':
             return immunizationFlatToFhirR4(flatClaims);
         case 'Location':
@@ -370,6 +389,8 @@ function convertClaimsToFhirResourceByType(flatClaims, resourceType) {
             return compositionFlatToFhirR4(flatClaims);
         case 'Appointment':
             return appointmentFlatToFhirR4(flatClaims);
+        case 'AppointmentResponse':
+            return appointmentResponseFlatToFhirR4(flatClaims);
         case 'Encounter':
             return encounterFlatToFhirR4(flatClaims);
         case 'RelatedPerson':
@@ -397,7 +418,7 @@ function convertClaimsToFhirResourceByType(flatClaims, resourceType) {
  * not yet part of the clinical claims-first pipeline:
  * `Composition`, `Patient`, `Practitioner`, `PractitionerRole`.
  */
-export function extractBundleDocumentClaimsList(bundle, context = 'org.hl7.fhir.r4') {
+export function extractBundleDocumentClaimsList(bundle, context = 'org.hl7.fhir.api') {
     const entries = Array.isArray(bundle?.entry) ? bundle.entry : [];
     const ignoredResourceTypes = new Set([
         ResourceTypesFhirR4.Composition,

package/dist/utils/bundle-entry-editor.d.ts

@@ -75,6 +75,19 @@ export declare class BundleEntryEditor {
     hasClaim(key: string): boolean;
     /** Writes one claim on this entry. */
     setClaim(key: string, value: unknown): this;
+    /**
+     * Writes one viewer/editor field using the canonical short FHIR API claim.
+     * Expanded `org.hl7.fhir.api.*` input is normalized; versioned FHIR claim
+     * namespaces and structural/camelCase paths are rejected.
+     */
+    setFhirApiClaim(key: string, value: unknown): this;
+    /** Reads one short or expanded FHIR API claim through the canonical short key. */
+    getFhirApiClaim(key: string): unknown;
+    /** Applies a complete field collection returned by a clinical card view. */
+    setFhirApiClaimFields(fields: readonly Readonly<{
+        claim: string;
+        value: unknown;
+    }>[]): this;
     /** Appends one claim value on this entry. */
     addClaim(key: string, value: unknown): this;
     /** Removes one claim from this entry. */

package/dist/utils/bundle-entry-editor.js

@@ -6,6 +6,7 @@
  */
 import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
 import { BundleEditableResourceTypes, } from '../models/bundle-editor-types.js';
+import { normalizeFhirApiClaimKey } from './fhir-api-claim-helpers.js';
 import { EmployeeResourceTypes, } from './employee.js';
 import { cloneClaimValue, normalizeOptionalIdentifier } from './bundle-editor-helpers.js';
 import { createRegisteredBundleEntryEditor } from './bundle-editor-registry.js';
@@ -241,6 +242,23 @@ export class BundleEntryEditor {
         };
         return this;
     }
+    /**
+     * Writes one viewer/editor field using the canonical short FHIR API claim.
+     * Expanded `org.hl7.fhir.api.*` input is normalized; versioned FHIR claim
+     * namespaces and structural/camelCase paths are rejected.
+     */
+    setFhirApiClaim(key, value) {
+        return this.setClaim(normalizeFhirApiClaimKey(key), value);
+    }
+    /** Reads one short or expanded FHIR API claim through the canonical short key. */
+    getFhirApiClaim(key) {
+        return this.getClaim(normalizeFhirApiClaimKey(key));
+    }
+    /** Applies a complete field collection returned by a clinical card view. */
+    setFhirApiClaimFields(fields) {
+        fields.forEach((field) => this.setFhirApiClaim(field.claim, field.value));
+        return this;
+    }
     /** Appends one claim value on this entry. */
     addClaim(key, value) {
         const normalizedKey = String(key).trim();

package/dist/utils/clinical-resource-converters.js

@@ -99,12 +99,14 @@ export const practitionerRoleFhirToFlat = practitionerRoleFhirR4ToFlat;
  * resource-specific converter exists. Unsupported resources fall back to the
  * generic structural flattening.
  */
-export function convertFhirResourceToClaims(resource, context = 'org.hl7.fhir.r4') {
+export function convertFhirResourceToClaims(resource, context = 'org.hl7.fhir.api') {
     const claims = convertFhirResourceToClaimsByType(resource, context);
     const language = typeof resource.language === 'string' ? resource.language.trim() : '';
-    return language
-        ? { ...claims, [`${resource.resourceType}.language`]: language }
-        : claims;
+    return {
+        '@context': context,
+        ...claims,
+        ...(language ? { [`${resource.resourceType}.language`]: language } : {}),
+    };
 }
 function convertFhirResourceToClaimsByType(resource, context) {
     switch (resource.resourceType) {

package/dist/utils/clinical-resource-view.d.ts

@@ -20,9 +20,54 @@ export type ClinicalResourceCommonView = Readonly<{
 export type ClinicalResourceCardView = Readonly<{
     title: string;
     resourceType: string;
+    /** Stable business identifier used to reconcile repeated readbacks. */
+    identifier?: string;
     date?: string;
+    periodStart?: string;
+    periodEnd?: string;
     fullUrl?: string;
     actorsCount: number;
+    /** Resource status resolved from canonical claims first, then native FHIR. */
+    status?: string;
+    /** Observation scalar value for result cards. */
+    value?: string | number;
+    /** Observation quantity unit for result cards. */
+    unit?: string;
+    /** Immunization lot number. */
+    lotNumber?: string;
+    /** Immunization dose sequence. */
+    doseSequence?: string;
+    /** AllergyIntolerance criticality. */
+    criticality?: string;
+    /** AllergyIntolerance onset date/time. */
+    onsetDateTime?: string;
+    /** MedicationStatement human-readable dosage instruction. */
+    dosageInstruction?: string;
+    category?: string;
+    severity?: string;
+    recordedDate?: string;
+    source?: string;
+    route?: string;
+    site?: string;
+    doseQuantityValue?: number;
+    doseQuantityUnit?: string;
+    referenceRangeText?: string;
+    description?: string;
+    /**
+     * Complete editable field surface resolved from `resource.meta.claims`.
+     *
+     * `claim` always uses the short, version-independent FHIR API form
+     * (`<ResourceType>.<search-param>`). Consumers can therefore render and
+     * hydrate fields that do not yet have a dedicated card convenience member.
+     */
+    fields: readonly ClinicalResourceClaimFieldView[];
+}>;
+export type ClinicalResourceClaimFieldView = Readonly<{
+    /** Canonical short FHIR API claim, for example `Immunization.lot-number`. */
+    claim: string;
+    /** Concrete FHIR API SearchParameter name, for example `lot-number`. */
+    parameter: string;
+    value: unknown;
 }>;
 export type ClinicalTerminologyTranslationInput = Readonly<{
     resourceType: string;
@@ -110,6 +155,16 @@ export declare function toClinicalResourceCommonViews(bundle: ClinicalResourceBu
  * Maps one bundle entry to a minimal card view for section counters/list cards.
  */
 export declare function toClinicalResourceCardView(entry: ClinicalResourceEntryLike, options?: ClinicalResourceDisplayOptions): ClinicalResourceCardView;
+/**
+ * Normalizes all clinical `meta.claims` into the short FHIR API vocabulary
+ * consumed by generic clinical viewers and editors.
+ *
+ * Short claims take precedence over their expanded
+ * `org.hl7.fhir.api.<ResourceType>.<search-param>` equivalent. Versioned
+ * `org.hl7.fhir.<version>.*` namespaces are rejected because they are native
+ * FHIR representation namespaces, never claims vocabularies.
+ */
+export declare function toClinicalResourceClaimFieldViews(claims: ClinicalViewClaims): ClinicalResourceClaimFieldView[];
 /**
  * Maps all entries from a Bundle into minimal card views.
  */

package/dist/utils/clinical-resource-view.js

@@ -14,6 +14,7 @@ import { MedicationStatementClaim, MedicationStatementClaimsFhirApi, MedicationS
 import { ObservationClaim } from '../models/interoperable-claims/observation-claims.js';
 import { PractitionerRoleClaim } from '../models/interoperable-claims/practitioner-role-claims.js';
 import { ProcedureClaim } from '../models/interoperable-claims/procedure-claims.js';
+import { normalizeFhirApiClaimKey } from './fhir-api-claim-helpers.js';
 const CONSENT_ACTOR_REFERENCE_CLAIM = 'Consent.actor-reference';
 const GENERIC_CREATOR_CLAIM_SUFFIX = '.creator';
 const GENERIC_PERFORMER_CLAIM_SUFFIX = '.performer';
@@ -49,14 +50,112 @@ export function toClinicalResourceCommonViews(bundle, options = {}) {
  */
 export function toClinicalResourceCardView(entry, options = {}) {
     const common = toClinicalResourceCommonView(entry, options);
+    const resource = entry.resource;
+    const status = resolveCardStatus(common.resourceType, common.claims, resource);
+    const value = resolveCardValue(common.resourceType, common.claims, resource);
+    const unit = resolveCardUnit(common.resourceType, common.claims, resource);
+    const lotNumber = readCanonicalClaimValue(common.claims, ImmunizationClaim.LotNumber)
+        || trimValue(resource?.lotNumber);
+    const doseSequence = readCanonicalClaimValue(common.claims, ImmunizationClaim.DoseSequence)
+        || trimValue(asRecord(asArray(resource?.protocolApplied)[0]).doseNumberString);
+    const criticality = readCanonicalClaimValue(common.claims, AllergyIntoleranceClaim.Criticality)
+        || trimValue(resource?.criticality);
+    const onsetDateTime = readCanonicalClaimValue(common.claims, AllergyIntoleranceClaim.OnsetDateTime)
+        || trimValue(resource?.onsetDateTime);
+    const dosageInstruction = readCanonicalClaimValue(common.claims, MedicationStatementClaim.DosageInstruction)
+        || trimValue(asRecord(asArray(resource?.dosage)[0]).text);
+    const fields = toClinicalResourceClaimFieldViews(common.claims);
+    const category = readCanonicalClaimValue(common.claims, `${common.resourceType}.category`);
+    const severity = readCanonicalClaimValue(common.claims, `${common.resourceType}.severity`);
+    const recordedDate = readCanonicalClaimValue(common.claims, ConditionClaim.RecordedDate);
+    const source = readCanonicalClaimValue(common.claims, MedicationStatementClaim.Source);
+    const route = readCanonicalClaimValue(common.claims, ImmunizationClaim.Route);
+    const site = readCanonicalClaimValue(common.claims, ImmunizationClaim.Site);
+    const doseQuantityValueRaw = readCanonicalClaimValue(common.claims, MedicationStatementClaim.DoseQuantityValue);
+    const doseQuantityValue = doseQuantityValueRaw === undefined ? undefined : Number(doseQuantityValueRaw);
+    const doseQuantityUnit = readCanonicalClaimValue(common.claims, MedicationStatementClaim.DoseQuantityUnit);
+    const referenceRangeText = readCanonicalClaimValue(common.claims, ObservationClaim.ReferenceRangeText);
+    const description = readCanonicalClaimValue(common.claims, CarePlanClaim.Description);
     return {
         title: common.title,
         resourceType: common.resourceType,
+        ...(common.identifier ? { identifier: common.identifier } : {}),
         date: common.date,
+        ...(common.periodStart ? { periodStart: common.periodStart } : {}),
+        ...(common.periodEnd ? { periodEnd: common.periodEnd } : {}),
         fullUrl: common.fullUrl,
         actorsCount: common.actors.length,
+        fields,
+        ...(status ? { status } : {}),
+        ...(value !== undefined ? { value } : {}),
+        ...(unit ? { unit } : {}),
+        ...(lotNumber ? { lotNumber } : {}),
+        ...(doseSequence ? { doseSequence } : {}),
+        ...(criticality ? { criticality } : {}),
+        ...(onsetDateTime ? { onsetDateTime } : {}),
+        ...(dosageInstruction ? { dosageInstruction } : {}),
+        ...(category ? { category } : {}),
+        ...(severity ? { severity } : {}),
+        ...(recordedDate ? { recordedDate } : {}),
+        ...(source ? { source } : {}),
+        ...(route ? { route } : {}),
+        ...(site ? { site } : {}),
+        ...(doseQuantityValue !== undefined && Number.isFinite(doseQuantityValue) ? { doseQuantityValue } : {}),
+        ...(doseQuantityUnit ? { doseQuantityUnit } : {}),
+        ...(referenceRangeText ? { referenceRangeText } : {}),
+        ...(description ? { description } : {}),
     };
 }
+/**
+ * Normalizes all clinical `meta.claims` into the short FHIR API vocabulary
+ * consumed by generic clinical viewers and editors.
+ *
+ * Short claims take precedence over their expanded
+ * `org.hl7.fhir.api.<ResourceType>.<search-param>` equivalent. Versioned
+ * `org.hl7.fhir.<version>.*` namespaces are rejected because they are native
+ * FHIR representation namespaces, never claims vocabularies.
+ */
+export function toClinicalResourceClaimFieldViews(claims) {
+    const fields = new Map();
+    const entries = Object.entries(claims || {});
+    for (const [rawClaim, value] of entries) {
+        if (rawClaim.startsWith('@') || value === undefined)
+            continue;
+        if (rawClaim.startsWith('org.hl7.fhir.') && !rawClaim.startsWith('org.hl7.fhir.api.')) {
+            throw new Error(`FHIR meta.claims must use org.hl7.fhir.api, not version-specific key: ${rawClaim}`);
+        }
+        if (!rawClaim.startsWith('org.hl7.fhir.api.') && !/^[A-Z][A-Za-z0-9]+\./.test(rawClaim))
+            continue;
+        const claim = normalizeFhirApiClaimKey(rawClaim);
+        const separator = claim.indexOf('.');
+        if (separator <= 0 || separator === claim.length - 1)
+            continue;
+        if (!fields.has(claim)) {
+            fields.set(claim, {
+                claim,
+                parameter: claim.slice(separator + 1),
+                value,
+            });
+        }
+    }
+    // Apply canonical short keys last so they win over expanded aliases even
+    // when the expanded property appeared later in insertion order.
+    for (const [claim, value] of entries) {
+        if (claim.startsWith('@') || claim.startsWith('org.hl7.fhir.') || value === undefined)
+            continue;
+        if (!/^[A-Z][A-Za-z0-9]+\./.test(claim))
+            continue;
+        const separator = claim.indexOf('.');
+        if (separator <= 0 || separator === claim.length - 1)
+            continue;
+        fields.set(claim, {
+            claim,
+            parameter: claim.slice(separator + 1),
+            value,
+        });
+    }
+    return [...fields.values()].sort((left, right) => left.claim.localeCompare(right.claim));
+}
 /**
  * Maps all entries from a Bundle into minimal card views.
  */
@@ -196,6 +295,42 @@ export function getNarrative(resource) {
         source: 'derived-from-claims',
     };
 }
+function resolveCardStatus(resourceType, claims, resource) {
+    const claimsStatus = resourceType === ResourceTypesFhirR4.AllergyIntolerance
+        ? readCanonicalClaimValue(claims, AllergyIntoleranceClaim.ClinicalStatus)
+        : readCanonicalClaimValue(claims, `${resourceType}.status`);
+    if (claimsStatus)
+        return claimsStatus;
+    const nativeStatus = trimValue(resource?.status);
+    if (nativeStatus)
+        return nativeStatus;
+    return trimValue(asRecord(asArray(asRecord(resource?.clinicalStatus).coding)[0]).code) || undefined;
+}
+function resolveCardValue(resourceType, claims, resource) {
+    if (resourceType !== ResourceTypesFhirR4.Observation)
+        return undefined;
+    const claimNumber = readCanonicalClaimValue(claims, ObservationClaim.ValueQuantityNumber);
+    if (claimNumber !== undefined) {
+        const numeric = Number(claimNumber);
+        if (Number.isFinite(numeric))
+            return numeric;
+    }
+    const claimString = readCanonicalClaimValue(claims, ObservationClaim.ValueString);
+    if (claimString)
+        return claimString;
+    const nativeNumber = asRecord(resource?.valueQuantity).value;
+    if (typeof nativeNumber === 'number' && Number.isFinite(nativeNumber))
+        return nativeNumber;
+    return trimValue(resource?.valueString) || undefined;
+}
+function resolveCardUnit(resourceType, claims, resource) {
+    if (resourceType !== ResourceTypesFhirR4.Observation)
+        return undefined;
+    return readCanonicalClaimValue(claims, ObservationClaim.ValueQuantityUnit)
+        || trimValue(asRecord(resource?.valueQuantity).unit)
+        || trimValue(asRecord(resource?.valueQuantity).code)
+        || undefined;
+}
 function readClaims(entry) {
     const resourceClaims = asRecord(entry?.resource?.meta?.claims);
     const legacyClaims = asRecord(entry?.meta?.claims);
@@ -397,7 +532,8 @@ function resolveIdentifier(resourceType, claims, resource) {
             AllergyIntoleranceClaimsFhirApi.Identifier,
         ]) || resolveFhirIdentifier(resource);
     }
-    return resolveFhirIdentifier(resource);
+    return readCanonicalClaimValue(claims, `${resourceType}.identifier`)
+        || resolveFhirIdentifier(resource);
 }
 function resolveDate(resourceType, claims, resource) {
     if (resourceType === ResourceTypesFhirR4.Communication) {

package/dist/utils/communication-bundle-document-request.js

@@ -67,7 +67,7 @@ export function buildBundleDocumentRequestCommunicationClaims(input) {
             : `Request ${documentTypeDescriptor.id} Bundle search with sections: ${sections.join(', ')}`)).trim();
     const noteText = String(input.noteText || text).trim();
     const claims = {
-        '@context': 'org.hl7.fhir.r4',
+        '@context': 'org.hl7.fhir.api',
         [CommunicationClaim.Identifier]: communicationIdentifier,
         [CommunicationClaim.Status]: String(input.status || 'completed').trim(),
         [CommunicationClaim.Category]: CommunicationCategoryCodes.Notification.claim,

package/dist/utils/communication-fhir-r4.js

@@ -121,7 +121,7 @@ export function extractCommunicationClaimsFromResourceFhirR4(resource, options =
         return { ...existingClaims };
     }
     const claims = {};
-    claims['@context'] = 'org.hl7.fhir.r4';
+    claims['@context'] = 'org.hl7.fhir.api';
     const identifierValue = resource?.identifier?.[0]?.value;
     const status = resource?.status;
     const sent = resource?.sent;

package/dist/utils/fhir-api-claim-helpers.d.ts

@@ -0,0 +1,2 @@
+/** Returns the canonical short FHIR API claim or throws for another vocabulary. */
+export declare function normalizeFhirApiClaimKey(claimKey: string): string;

package/dist/utils/fhir-api-claim-helpers.js

@@ -0,0 +1,16 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+const FHIR_API_PREFIX = 'org.hl7.fhir.api.';
+const FHIR_VERSIONED_PREFIX = 'org.hl7.fhir.';
+const SHORT_FHIR_API_CLAIM = /^[A-Z][A-Za-z0-9]+\.[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Returns the canonical short FHIR API claim or throws for another vocabulary. */
+export function normalizeFhirApiClaimKey(claimKey) {
+    const raw = String(claimKey || '').trim();
+    if (raw.startsWith(FHIR_VERSIONED_PREFIX) && !raw.startsWith(FHIR_API_PREFIX)) {
+        throw new Error(`FHIR claims must use org.hl7.fhir.api, not version-specific key: ${raw}`);
+    }
+    const normalized = raw.startsWith(FHIR_API_PREFIX) ? raw.slice(FHIR_API_PREFIX.length) : raw;
+    if (!SHORT_FHIR_API_CLAIM.test(normalized)) {
+        throw new Error(`Invalid FHIR API claim key: ${raw}`);
+    }
+    return normalized;
+}

package/dist/utils/ips-bundle-claims.d.ts

@@ -17,10 +17,9 @@ export type FhirMetaTagCoding = Readonly<{
     display?: string;
 }>;
 /**
- * Removes the versioned/contextualized FHIR prefix from a flattened claim key.
+ * Removes the version-independent FHIR API context from a flattened claim key.
  *
  * Examples:
- * - `org.hl7.fhir.r4.Immunization.vaccine-code` -> `Immunization.vaccine-code`
  * - `org.hl7.fhir.api.MedicationStatement.subject` -> `MedicationStatement.subject`
  * - `Consent.identifier` -> `Consent.identifier`
  */
@@ -35,8 +34,8 @@ export declare function extractResourceMetaClaimsFromBundle(bundle: BundleLike):
 /**
  * Builds FHIR `meta.tag[]` codings from a flat claims record.
  *
- * The generated `code` is version-agnostic so UI/frontends can use the same
- * tag keys across `org.hl7.fhir.r4.*` and `org.hl7.fhir.api.*` payloads.
+ * The generated `code` removes the sole valid FHIR claims context,
+ * `org.hl7.fhir.api`, so UI/frontends receive the canonical short key.
  */
 export declare function createFhirMetaTagsFromClaims(claims: Record<string, unknown>, options?: Readonly<{
     system?: string;

package/dist/utils/ips-bundle-claims.js

@@ -1,10 +1,9 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
 export const DEFAULT_META_CLAIM_TAG_SYSTEM = 'urn:gdc:fhir:meta-claim';
 /**
- * Removes the versioned/contextualized FHIR prefix from a flattened claim key.
+ * Removes the version-independent FHIR API context from a flattened claim key.
  *
  * Examples:
- * - `org.hl7.fhir.r4.Immunization.vaccine-code` -> `Immunization.vaccine-code`
  * - `org.hl7.fhir.api.MedicationStatement.subject` -> `MedicationStatement.subject`
  * - `Consent.identifier` -> `Consent.identifier`
  */
@@ -12,9 +11,10 @@ export function toVersionAgnosticMetaClaimKey(claimKey) {
     const raw = String(claimKey || '').trim();
     if (!raw)
         return '';
-    return raw
-        .replace(/^org\.hl7\.fhir\.[a-z0-9]+\./i, '')
-        .replace(/^org\.hl7\.fhir\.api\./i, '');
+    if (raw.startsWith('org.hl7.fhir.') && !raw.startsWith('org.hl7.fhir.api.')) {
+        throw new Error('FHIR claims require @context org.hl7.fhir.api.');
+    }
+    return raw.replace(/^org\.hl7\.fhir\.api\./i, '');
 }
 /**
  * Extracts all `resource.meta.claims` blocks from a FHIR/JSON:API bundle.
@@ -35,8 +35,8 @@ export function extractResourceMetaClaimsFromBundle(bundle) {
 /**
  * Builds FHIR `meta.tag[]` codings from a flat claims record.
  *
- * The generated `code` is version-agnostic so UI/frontends can use the same
- * tag keys across `org.hl7.fhir.r4.*` and `org.hl7.fhir.api.*` payloads.
+ * The generated `code` removes the sole valid FHIR claims context,
+ * `org.hl7.fhir.api`, so UI/frontends receive the canonical short key.
  */
 export function createFhirMetaTagsFromClaims(claims, options) {
     const system = String(options?.system || DEFAULT_META_CLAIM_TAG_SYSTEM).trim();

package/dist/utils/medication-statement-entry-editor.js

@@ -63,25 +63,25 @@ export class MedicationStatementEntryEditor extends ClinicalResourceEntryEditor
     /** Returns the medication category/section tags. */
     getCategoryList() { return this.getCsvClaimList(MedicationStatementClaim.Category); }
     /** Sets the numeric dose quantity value. */
-    setDoseQuantityValue(value) { return this.setNumberClaim(MedicationStatementClaimsFhirApiExtended.DoseQuantityValue, value); }
+    setDoseQuantityValue(value) { return this.setNumberClaim(MedicationStatementClaim.DoseQuantityValue, value); }
     /** Returns the numeric dose quantity value. */
-    getDoseQuantityValue() { return this.getNumberClaim(MedicationStatementClaimsFhirApiExtended.DoseQuantityValue); }
+    getDoseQuantityValue() { return this.getNumberClaim(MedicationStatementClaim.DoseQuantityValue); }
     /** Sets the dose quantity unit token. */
-    setDoseQuantityUnit(value) { return this.setScalarClaim(MedicationStatementClaimsFhirApiExtended.DoseQuantityUnit, value); }
+    setDoseQuantityUnit(value) { return this.setScalarClaim(MedicationStatementClaim.DoseQuantityUnit, value); }
     /** Returns the dose quantity unit token. */
-    getDoseQuantityUnit() { return this.getScalarClaim(MedicationStatementClaimsFhirApiExtended.DoseQuantityUnit); }
+    getDoseQuantityUnit() { return this.getScalarClaim(MedicationStatementClaim.DoseQuantityUnit); }
     /** Sets the timing frequency for structured dosage authoring. */
-    setTimingFrequency(value) { return this.setNumberClaim(MedicationStatementClaimsFhirApiExtended.TimingFrequency, value); }
+    setTimingFrequency(value) { return this.setNumberClaim(MedicationStatementClaim.TimingFrequency, value); }
     /** Returns the timing frequency. */
-    getTimingFrequency() { return this.getNumberClaim(MedicationStatementClaimsFhirApiExtended.TimingFrequency); }
+    getTimingFrequency() { return this.getNumberClaim(MedicationStatementClaim.TimingFrequency); }
     /** Sets the timing period for structured dosage authoring. */
-    setTimingPeriod(value) { return this.setNumberClaim(MedicationStatementClaimsFhirApiExtended.TimingPeriod, value); }
+    setTimingPeriod(value) { return this.setNumberClaim(MedicationStatementClaim.TimingPeriod, value); }
     /** Returns the timing period. */
-    getTimingPeriod() { return this.getNumberClaim(MedicationStatementClaimsFhirApiExtended.TimingPeriod); }
+    getTimingPeriod() { return this.getNumberClaim(MedicationStatementClaim.TimingPeriod); }
     /** Sets the timing period unit token. */
-    setTimingPeriodUnit(value) { return this.setScalarClaim(MedicationStatementClaimsFhirApiExtended.TimingPeriodUnit, value); }
+    setTimingPeriodUnit(value) { return this.setScalarClaim(MedicationStatementClaim.TimingPeriodUnit, value); }
     /** Returns the timing period unit token. */
-    getTimingPeriodUnit() { return this.getScalarClaim(MedicationStatementClaimsFhirApiExtended.TimingPeriodUnit); }
+    getTimingPeriodUnit() { return this.getScalarClaim(MedicationStatementClaim.TimingPeriodUnit); }
     /** Marks whether this dosage is `as needed`. */
     setDosageAsNeeded(value) { return this.setBooleanClaim(MedicationStatementClaimsFhirApiExtended.DosageAsNeeded, value); }
     /** Returns whether this dosage is `as needed`. */

package/dist/utils/observation-component-entry-editor.d.ts

@@ -6,14 +6,14 @@
  * - Move shared helpers to reusable helper/base modules instead of duplicating logic here.
  */
 import { type CodingDescriptor } from '../constants/vital-signs';
-import { BundleEntryEditor } from './bundle-entry-editor';
+import { ClinicalResourceEntryEditor } from './clinical-resource-entry-editor';
 /**
  * Typed editor for one staged ObservationComponent resource entry.
  *
  * Keep this surface thin and claim-focused so 101 tests can teach one
  * resource at a time without exposing bundle-internal plumbing.
  */
-export declare class ObservationComponentEntryEditor extends BundleEntryEditor {
+export declare class ObservationComponentEntryEditor extends ClinicalResourceEntryEditor {
     setCode(code: CodingDescriptor | string): this;
     getCode(): string | undefined;
     setCodeSystem(system: string): this;

package/dist/utils/observation-component-entry-editor.js

@@ -1,13 +1,13 @@
 import { ObservationClaim } from '../models/interoperable-claims/observation-claims.js';
 import { normalizeOptionalIdentifier } from './bundle-editor-helpers.js';
-import { BundleEntryEditor } from './bundle-entry-editor.js';
+import { ClinicalResourceEntryEditor } from './clinical-resource-entry-editor.js';
 /**
  * Typed editor for one staged ObservationComponent resource entry.
  *
  * Keep this surface thin and claim-focused so 101 tests can teach one
  * resource at a time without exposing bundle-internal plumbing.
  */
-export class ObservationComponentEntryEditor extends BundleEntryEditor {
+export class ObservationComponentEntryEditor extends ClinicalResourceEntryEditor {
     setCode(code) {
         const token = typeof code === 'string' ? code.trim() : code.claim;
         this.setClaim(ObservationClaim.Code, token);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-common-utils-ts",
-  "version": "2.3.26",
+  "version": "2.3.27",
   "publishConfig": {
     "access": "public"
   },