fhir-data-utils-ts 0.4.0 → 0.6.0

package/dist/claims/schedule-slot-claims.js

@@ -0,0 +1,70 @@
+// Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+import { defineFlatSearchParameter } from '../search-parameters.js';
+/** Canonical flat claims for the official FHIR R5 Schedule search surface. */
+export const ScheduleClaim = Object.freeze({
+    Active: 'Schedule.active',
+    Actor: 'Schedule.actor',
+    Date: 'Schedule.date',
+    Identifier: 'Schedule.identifier',
+    Name: 'Schedule.name',
+    ServiceCategory: 'Schedule.service-category',
+    ServiceType: 'Schedule.service-type',
+    ServiceTypeReference: 'Schedule.service-type-reference',
+    Specialty: 'Schedule.specialty',
+    PlanningHorizonStart: 'Schedule.planning-horizon-start',
+    PlanningHorizonEnd: 'Schedule.planning-horizon-end',
+    Comment: 'Schedule.comment',
+});
+/** Canonical flat claims for the official FHIR R5 Slot search surface. */
+export const SlotClaim = Object.freeze({
+    AppointmentType: 'Slot.appointment-type',
+    Identifier: 'Slot.identifier',
+    Schedule: 'Slot.schedule',
+    ServiceCategory: 'Slot.service-category',
+    ServiceType: 'Slot.service-type',
+    ServiceTypeReference: 'Slot.service-type-reference',
+    Specialty: 'Slot.specialty',
+    Start: 'Slot.start',
+    Status: 'Slot.status',
+    End: 'Slot.end',
+    Overbooked: 'Slot.overbooked',
+    Comment: 'Slot.comment',
+});
+export const ScheduleR5SearchParameterCatalog = Object.freeze([
+    defineFlatSearchParameter({ claim: ScheduleClaim.Active, resourceType: 'Schedule', elementPath: 'Schedule.active', type: 'token' }),
+    defineFlatSearchParameter({ claim: ScheduleClaim.Actor, resourceType: 'Schedule', elementPath: 'Schedule.actor', type: 'reference' }),
+    defineFlatSearchParameter({ claim: ScheduleClaim.Date, resourceType: 'Schedule', elementPath: 'Schedule.planningHorizon', type: 'date' }),
+    defineFlatSearchParameter({ claim: ScheduleClaim.Identifier, resourceType: 'Schedule', elementPath: 'Schedule.identifier', type: 'token' }),
+    defineFlatSearchParameter({ claim: ScheduleClaim.Name, resourceType: 'Schedule', elementPath: 'Schedule.name', type: 'string' }),
+    defineFlatSearchParameter({ claim: ScheduleClaim.ServiceCategory, resourceType: 'Schedule', elementPath: 'Schedule.serviceCategory', type: 'token' }),
+    defineFlatSearchParameter({ claim: ScheduleClaim.ServiceType, resourceType: 'Schedule', elementPath: 'Schedule.serviceType.concept', type: 'token' }),
+    defineFlatSearchParameter({ claim: ScheduleClaim.ServiceTypeReference, resourceType: 'Schedule', elementPath: 'Schedule.serviceType.reference', type: 'reference' }),
+    defineFlatSearchParameter({ claim: ScheduleClaim.Specialty, resourceType: 'Schedule', elementPath: 'Schedule.specialty', type: 'token' }),
+]);
+export const SlotR5SearchParameterCatalog = Object.freeze([
+    defineFlatSearchParameter({ claim: SlotClaim.AppointmentType, resourceType: 'Slot', elementPath: 'Slot.appointmentType', type: 'token' }),
+    defineFlatSearchParameter({ claim: SlotClaim.Identifier, resourceType: 'Slot', elementPath: 'Slot.identifier', type: 'token' }),
+    defineFlatSearchParameter({ claim: SlotClaim.Schedule, resourceType: 'Slot', elementPath: 'Slot.schedule', type: 'reference' }),
+    defineFlatSearchParameter({ claim: SlotClaim.ServiceCategory, resourceType: 'Slot', elementPath: 'Slot.serviceCategory', type: 'token' }),
+    defineFlatSearchParameter({ claim: SlotClaim.ServiceType, resourceType: 'Slot', elementPath: 'Slot.serviceType.concept', type: 'token' }),
+    defineFlatSearchParameter({ claim: SlotClaim.ServiceTypeReference, resourceType: 'Slot', elementPath: 'Slot.serviceType.reference', type: 'reference' }),
+    defineFlatSearchParameter({ claim: SlotClaim.Specialty, resourceType: 'Slot', elementPath: 'Slot.specialty', type: 'token' }),
+    defineFlatSearchParameter({ claim: SlotClaim.Start, resourceType: 'Slot', elementPath: 'Slot.start', type: 'date' }),
+    defineFlatSearchParameter({ claim: SlotClaim.Status, resourceType: 'Slot', elementPath: 'Slot.status', type: 'token' }),
+]);
+export const ScheduleClaimSpecs = Object.freeze([
+    { key: ScheduleClaim.Identifier, meaning: 'Logical schedule identifier.', example: 'urn:uuid:blood-donation-weekday' },
+    { key: ScheduleClaim.Active, meaning: 'Whether this schedule is in active use.', example: 'true' },
+    { key: ScheduleClaim.Actor, meaning: 'Repeatable independently schedulable actors as CSV references.', example: 'HealthcareService/blood-donation,Location/blood-donation-room' },
+    { key: ScheduleClaim.ServiceType, meaning: 'Repeatable service-type concept tokens as CSV.', example: 'http://terminology.hl7.org/CodeSystem/service-type|117' },
+    { key: ScheduleClaim.ServiceTypeReference, meaning: 'Repeatable HealthcareService references corresponding to service-type concepts.', example: 'HealthcareService/blood-donation' },
+    { key: ScheduleClaim.PlanningHorizonStart, meaning: 'Start of the period covered by this schedule.', example: '2026-10-01' },
+    { key: ScheduleClaim.PlanningHorizonEnd, meaning: 'End of the period covered by this schedule.', example: '2026-10-31' },
+]);
+export const SlotClaimSpecs = Object.freeze([
+    { key: SlotClaim.Identifier, meaning: 'Logical slot identifier.', example: 'urn:uuid:blood-20261001-0900' },
+    { key: SlotClaim.Schedule, meaning: 'The Schedule that owns this independent slot.', example: 'Schedule/blood-donation-weekday' },
+    { key: SlotClaim.Status, meaning: 'FHIR Slot status.', example: 'free' },
+    { key: SlotClaim.Start, meaning: 'Start instant.', example: '2026-10-01T09:00:00Z' },
+    { key: SlotClaim.End, meaning: 'End instant; duration is derived from start and end.', example: '2026-10-01T09:15:00Z' },
+]);

package/dist/constants/fhir-resource-types.d.ts

@@ -25,6 +25,7 @@ export declare const ResourceTypesFhirR4: Readonly<{
     readonly Encounter: "Encounter";
     readonly Flag: "Flag";
     readonly Group: "Group";
+    readonly HealthcareService: "HealthcareService";
     readonly ImagingStudy: "ImagingStudy";
     readonly Immunization: "Immunization";
     readonly ImmunizationRecommendation: "ImmunizationRecommendation";
@@ -47,7 +48,9 @@ export declare const ResourceTypesFhirR4: Readonly<{
     readonly RelatedPerson: "RelatedPerson";
     readonly ResearchStudy: "ResearchStudy";
     readonly ResearchSubject: "ResearchSubject";
+    readonly Schedule: "Schedule";
     readonly Specimen: "Specimen";
+    readonly Slot: "Slot";
     readonly ServiceRequest: "ServiceRequest";
     readonly Task: "Task";
     readonly DetectedIssue: "DetectedIssue";
@@ -81,6 +84,7 @@ export declare const FhirResourceTypes: Readonly<{
     readonly Encounter: "Encounter";
     readonly Flag: "Flag";
     readonly Group: "Group";
+    readonly HealthcareService: "HealthcareService";
     readonly ImagingStudy: "ImagingStudy";
     readonly Immunization: "Immunization";
     readonly ImmunizationRecommendation: "ImmunizationRecommendation";
@@ -103,7 +107,9 @@ export declare const FhirResourceTypes: Readonly<{
     readonly RelatedPerson: "RelatedPerson";
     readonly ResearchStudy: "ResearchStudy";
     readonly ResearchSubject: "ResearchSubject";
+    readonly Schedule: "Schedule";
     readonly Specimen: "Specimen";
+    readonly Slot: "Slot";
     readonly ServiceRequest: "ServiceRequest";
     readonly Task: "Task";
     readonly DetectedIssue: "DetectedIssue";
@@ -133,6 +139,7 @@ export declare const ResourceTypesFhirR5: Readonly<{
     readonly Encounter: "Encounter";
     readonly Flag: "Flag";
     readonly Group: "Group";
+    readonly HealthcareService: "HealthcareService";
     readonly ImagingStudy: "ImagingStudy";
     readonly Immunization: "Immunization";
     readonly ImmunizationRecommendation: "ImmunizationRecommendation";
@@ -155,7 +162,9 @@ export declare const ResourceTypesFhirR5: Readonly<{
     readonly RelatedPerson: "RelatedPerson";
     readonly ResearchStudy: "ResearchStudy";
     readonly ResearchSubject: "ResearchSubject";
+    readonly Schedule: "Schedule";
     readonly Specimen: "Specimen";
+    readonly Slot: "Slot";
     readonly ServiceRequest: "ServiceRequest";
     readonly Task: "Task";
     readonly DetectedIssue: "DetectedIssue";

package/dist/constants/fhir-resource-types.js

@@ -25,6 +25,7 @@ export const ResourceTypesFhirR4 = Object.freeze({
     Encounter: 'Encounter',
     Flag: 'Flag',
     Group: 'Group',
+    HealthcareService: 'HealthcareService',
     ImagingStudy: 'ImagingStudy',
     Immunization: 'Immunization',
     ImmunizationRecommendation: 'ImmunizationRecommendation',
@@ -47,7 +48,9 @@ export const ResourceTypesFhirR4 = Object.freeze({
     RelatedPerson: 'RelatedPerson',
     ResearchStudy: 'ResearchStudy',
     ResearchSubject: 'ResearchSubject',
+    Schedule: 'Schedule',
     Specimen: 'Specimen',
+    Slot: 'Slot',
     ServiceRequest: 'ServiceRequest',
     Task: 'Task',
     DetectedIssue: 'DetectedIssue',

package/dist/converters/convert-appointment-communication.d.ts

@@ -0,0 +1,14 @@
+import { type FlatClaimResourceEntry } from '../flat-claim-resource-graph.js';
+export type SupportedAppointmentFhirRelease = 'r4' | 'r5';
+export type AppointmentCommunicationFlatGraph = Readonly<{
+    communications: readonly FlatClaimResourceEntry[];
+    appointments: readonly FlatClaimResourceEntry[];
+    documentReferences: readonly FlatClaimResourceEntry[];
+    entries: readonly FlatClaimResourceEntry[];
+}>;
+/**
+ * Projects a validated appointment exchange into independently persisted flat
+ * claim resources. Transport parsing is delegated to the shared Bundle Reader;
+ * native FHIR remains an adapter input and is never persisted beside claims.
+ */
+export declare function projectAppointmentCommunicationBatchToFlatGraph(input: unknown, release: SupportedAppointmentFhirRelease): AppointmentCommunicationFlatGraph;

package/dist/converters/convert-appointment-communication.js

@@ -0,0 +1,97 @@
+import { AppointmentClaim } from '../claims/appointment-claims.js';
+import { CommunicationClaim } from '../claims/communication-claims.js';
+import { DocumentReferenceClaim } from '../claims/document-reference-claims.js';
+import { readBundleResources, readCommunicationBundlePayloads } from '../fhir-bundle.js';
+import { buildFlatClaimResourceEntry } from '../flat-claim-resource-graph.js';
+import { appointmentFhirR4ToFlat } from './convert-appointment.js';
+import { documentReferenceFhirR4ToFlat } from './convert-document-reference.js';
+/**
+ * Projects a validated appointment exchange into independently persisted flat
+ * claim resources. Transport parsing is delegated to the shared Bundle Reader;
+ * native FHIR remains an adapter input and is never persisted beside claims.
+ */
+export function projectAppointmentCommunicationBatchToFlatGraph(input, release) {
+    if (release !== 'r4' && release !== 'r5')
+        throw new TypeError('fhir_release_unsupported');
+    const communications = [];
+    const appointments = [];
+    const documentReferences = [];
+    for (const { communication, attachment, bundle } of readCommunicationBundlePayloads(input)) {
+        const communicationId = resourceId(communication, 'communication_identifier_required');
+        communications.push(buildFlatClaimResourceEntry({
+            entryId: communicationId,
+            resourceType: 'Communication',
+            claims: compactClaims({
+                [CommunicationClaim.Identifier]: communicationId,
+                [CommunicationClaim.Status]: stringValue(communication.status),
+                [CommunicationClaim.Subject]: referenceValue(communication.subject),
+                [CommunicationClaim.Recipient]: referenceList(communication.recipient),
+                [CommunicationClaim.Sender]: referenceValue(communication.sender),
+                [CommunicationClaim.Sent]: stringValue(communication.sent),
+                [CommunicationClaim.ContentAttachmentType]: attachment.contentType,
+                [CommunicationClaim.ContentAttachmentData]: attachment.data,
+                [CommunicationClaim.ContentAttachmentTitle]: attachment.title,
+            }),
+        }));
+        for (const child of readBundleResources(bundle)) {
+            if (child.resourceType === 'Appointment') {
+                const entryId = resourceId(child, 'appointment_identifier_required');
+                const structural = appointmentFhirR4ToFlat(child);
+                appointments.push(buildFlatClaimResourceEntry({
+                    entryId,
+                    resourceType: 'Appointment',
+                    claims: compactClaims({
+                        ...structural,
+                        [AppointmentClaim.Identifier]: structural[AppointmentClaim.Identifier] || entryId,
+                    }),
+                }));
+            }
+            else if (child.resourceType === 'DocumentReference') {
+                const entryId = resourceId(child, 'document_reference_identifier_required');
+                const structural = documentReferenceFhirR4ToFlat(child);
+                documentReferences.push(buildFlatClaimResourceEntry({
+                    entryId,
+                    resourceType: 'DocumentReference',
+                    claims: compactClaims({
+                        ...structural,
+                        [DocumentReferenceClaim.Identifier]: structural[DocumentReferenceClaim.Identifier] || entryId,
+                    }),
+                }));
+            }
+        }
+    }
+    return Object.freeze({
+        communications: Object.freeze(communications),
+        appointments: Object.freeze(appointments),
+        documentReferences: Object.freeze(documentReferences),
+        entries: Object.freeze([...communications, ...appointments, ...documentReferences]),
+    });
+}
+function resourceId(resource, error) {
+    const identifier = Array.isArray(resource.identifier)
+        ? resource.identifier.find(item => typeof item?.value === 'string')?.value
+        : undefined;
+    const value = String(resource.id || identifier || '').trim();
+    if (!value)
+        throw new TypeError(error);
+    return value;
+}
+function compactClaims(input) {
+    return Object.freeze(Object.fromEntries(Object.entries(input)
+        .filter((entry) => entry[1] !== undefined && entry[1] !== null && String(entry[1]).trim() !== '')
+        .map(([name, value]) => [name, String(value).trim()])));
+}
+function stringValue(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function referenceValue(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    return stringValue(value.reference);
+}
+function referenceList(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const references = value.map(referenceValue).filter((item) => Boolean(item));
+    return references.length ? [...new Set(references)].join(',') : undefined;
+}

package/dist/converters/convert-appointment.js

@@ -21,6 +21,8 @@ export function appointmentFlatToFhirR4(claims) {
         note: claims[AppointmentClaim.NoteText] ? [{ text: claims[AppointmentClaim.NoteText] }] : undefined,
         patientInstruction: claims[AppointmentClaim.PatientInstruction],
         basedOn: claims[AppointmentClaim.BasedOn] ? claims[AppointmentClaim.BasedOn].split(',').map((reference) => ({ reference: reference.trim() })) : undefined,
+        slot: claims[AppointmentClaim.Slot] ? claims[AppointmentClaim.Slot].split(',').map((reference) => ({ reference: reference.trim() })) : undefined,
+        supportingInformation: claims[AppointmentClaim.SupportingInfo] ? claims[AppointmentClaim.SupportingInfo].split(',').map((reference) => ({ reference: reference.trim() })) : undefined,
         participant: claims[AppointmentClaim.ParticipantActor]
             ? claims[AppointmentClaim.ParticipantActor].split(',').map((reference) => ({
                 actor: { reference: reference.trim() },
@@ -32,11 +34,17 @@ export function appointmentFlatToFhirR4(claims) {
 }
 export function appointmentFhirR4ToFlat(resource) {
     const participant = Array.isArray(resource.participant) ? resource.participant[0] : undefined;
+    const actorReferences = Array.isArray(resource.participant)
+        ? resource.participant
+            .map((item) => referenceToValue(item?.actor))
+            .filter((item) => Boolean(item))
+        : [];
+    const serviceType = resource.serviceType?.[0];
     return {
         [AppointmentClaim.Identifier]: resource.identifier?.[0]?.value,
         [AppointmentClaim.Status]: resource.status,
         [AppointmentClaim.ServiceCategory]: codingToValue(resource.serviceCategory?.[0]?.coding?.[0]),
-        [AppointmentClaim.ServiceType]: codingToValue(resource.serviceType?.[0]?.coding?.[0]),
+        [AppointmentClaim.ServiceType]: codingToValue(serviceType?.concept?.coding?.[0] ?? serviceType?.coding?.[0]),
         [AppointmentClaim.Specialty]: codingToValue(resource.specialty?.[0]?.coding?.[0]),
         [AppointmentClaim.AppointmentType]: codingToValue(resource.appointmentType?.coding?.[0]),
         [AppointmentClaim.ReasonCode]: codingToValue(resource.reasonCode?.[0]?.coding?.[0]),
@@ -49,13 +57,14 @@ export function appointmentFhirR4ToFlat(resource) {
         [AppointmentClaim.NoteText]: resource.note?.[0]?.text,
         [AppointmentClaim.PatientInstruction]: resource.patientInstruction,
         [AppointmentClaim.BasedOn]: referenceListToCsv(resource.basedOn),
-        [AppointmentClaim.ParticipantActor]: Array.isArray(resource.participant)
-            ? resource.participant
-                .map((item) => referenceToValue(item?.actor))
-                .filter((item) => Boolean(item))
-                .join(',')
-            : undefined,
+        [AppointmentClaim.ParticipantActor]: actorReferences.length ? actorReferences.join(',') : undefined,
         [AppointmentClaim.ParticipantStatus]: participant?.status,
         [AppointmentClaim.ParticipantType]: codingToValue(participant?.type?.[0]?.coding?.[0]),
+        [AppointmentClaim.Date]: resource.start,
+        [AppointmentClaim.Location]: actorReferences.filter(reference => reference.startsWith('Location/')).join(',') || undefined,
+        [AppointmentClaim.Patient]: actorReferences.filter(reference => reference.startsWith('Patient/')).join(',') || undefined,
+        [AppointmentClaim.Practitioner]: actorReferences.filter(reference => reference.startsWith('Practitioner/') || reference.startsWith('PractitionerRole/')).join(',') || undefined,
+        [AppointmentClaim.Slot]: referenceListToCsv(resource.slot),
+        [AppointmentClaim.SupportingInfo]: referenceListToCsv(resource.supportingInformation),
     };
 }

package/dist/converters/convert-device-metric.d.ts

@@ -0,0 +1,3 @@
+import type { FhirResource, FlatClaims } from './convert-shared.js';
+export declare function deviceMetricFlatToFhirR5(claims: FlatClaims): FhirResource;
+export declare function deviceMetricFhirR5ToFlat(resource: FhirResource): FlatClaims;

package/dist/converters/convert-device-metric.js

@@ -0,0 +1,37 @@
+import { DeviceMetricClaim } from '../claims/device-metric-claims.js';
+import { codingFromValue, codingToValue, referenceToValue } from './convert-shared.js';
+export function deviceMetricFlatToFhirR5(claims) {
+    const calibration = claims[DeviceMetricClaim.CalibrationType]
+        || claims[DeviceMetricClaim.CalibrationState]
+        || claims[DeviceMetricClaim.CalibrationTime]
+        ? [{
+                type: claims[DeviceMetricClaim.CalibrationType],
+                state: claims[DeviceMetricClaim.CalibrationState],
+                time: claims[DeviceMetricClaim.CalibrationTime],
+            }]
+        : undefined;
+    return {
+        resourceType: 'DeviceMetric',
+        identifier: claims[DeviceMetricClaim.Identifier] ? [{ value: claims[DeviceMetricClaim.Identifier] }] : undefined,
+        type: { coding: codingFromValue(claims[DeviceMetricClaim.Type]) },
+        unit: claims[DeviceMetricClaim.Unit] ? { coding: codingFromValue(claims[DeviceMetricClaim.Unit]) } : undefined,
+        device: claims[DeviceMetricClaim.Device] ? { reference: claims[DeviceMetricClaim.Device] } : undefined,
+        operationalStatus: claims[DeviceMetricClaim.OperationalStatus],
+        category: claims[DeviceMetricClaim.Category],
+        calibration,
+    };
+}
+export function deviceMetricFhirR5ToFlat(resource) {
+    const calibration = resource.calibration?.[0];
+    return {
+        [DeviceMetricClaim.Identifier]: resource.identifier?.[0]?.value,
+        [DeviceMetricClaim.Type]: codingToValue(resource.type?.coding?.[0]),
+        [DeviceMetricClaim.Unit]: codingToValue(resource.unit?.coding?.[0]),
+        [DeviceMetricClaim.Device]: referenceToValue(resource.device),
+        [DeviceMetricClaim.OperationalStatus]: resource.operationalStatus,
+        [DeviceMetricClaim.Category]: resource.category,
+        [DeviceMetricClaim.CalibrationType]: calibration?.type,
+        [DeviceMetricClaim.CalibrationState]: calibration?.state,
+        [DeviceMetricClaim.CalibrationTime]: calibration?.time,
+    };
+}

package/dist/converters/convert-document-reference.js

@@ -25,6 +25,9 @@ export function documentReferenceFlatToFhirR4(claims) {
             }
             : undefined,
         date: claims[DocumentReferenceClaim.Date],
+        context: claims[DocumentReferenceClaim.EventReference]
+            ? { related: claims[DocumentReferenceClaim.EventReference].split(',').map((reference) => ({ reference: reference.trim() })) }
+            : undefined,
         content: [{ attachment: {
                     contentType: claims[DocumentReferenceClaim.ContentType],
                     data: claims[DocumentReferenceClaim.ContentData],
@@ -45,6 +48,8 @@ export function documentReferenceFhirR4ToFlat(resource) {
         [DocumentReferenceClaim.TypeText]: resource.type?.text,
         [DocumentReferenceClaim.TypeDisplay]: resource.type?.coding?.[0]?.display,
         [DocumentReferenceClaim.Date]: resource.date,
+        [DocumentReferenceClaim.EventReference]: resource.context
+            ?.related?.map((related) => related.reference).filter((reference) => Boolean(reference)).join(',') || undefined,
         [DocumentReferenceClaim.ContentType]: attachment?.contentType,
         [DocumentReferenceClaim.ContentData]: attachment?.data,
         [DocumentReferenceClaim.Location]: attachment?.url,

package/dist/converters/convert-healthcare-service.d.ts

@@ -0,0 +1,7 @@
+import type { FhirResource, FlatClaims } from './convert-shared.js';
+/** Materializes canonical HealthcareService claims as native FHIR R4. */
+export declare function healthcareServiceFlatToFhirR4(claims: FlatClaims): FhirResource;
+/** Extracts only official R4 HealthcareService SearchParameters into flat claims. */
+export declare function healthcareServiceFhirR4ToFlat(resource: FhirResource): FlatClaims;
+/** Materializes canonical HealthcareService claims as native FHIR R5. */
+export declare const healthcareServiceFlatToFhirR5: typeof healthcareServiceFlatToFhirR4;

package/dist/converters/convert-healthcare-service.js

@@ -0,0 +1,60 @@
+// Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+import { HealthcareServiceClaim } from '../claims/healthcare-service-claims.js';
+import { codingListFromCsv, codingListToCsv, identifierFromValue, identifierToValue, referenceListToCsv, referenceToValue, } from './convert-shared.js';
+const conceptsFromCsv = (value) => {
+    const coding = codingListFromCsv(value);
+    return coding?.map(item => ({ coding: [item] }));
+};
+const conceptsToCsv = (value) => codingListToCsv((Array.isArray(value) ? value : [])
+    .flatMap(item => item && typeof item === 'object' && Array.isArray(item.coding)
+    ? item.coding ?? []
+    : []));
+const referencesFromCsv = (value) => {
+    const references = String(value || '').split(',').map(item => item.trim()).filter(Boolean);
+    return references.length ? references.map(reference => ({ reference })) : undefined;
+};
+/** Materializes canonical HealthcareService claims as native FHIR R4. */
+export function healthcareServiceFlatToFhirR4(claims) {
+    return {
+        resourceType: 'HealthcareService',
+        identifier: claims[HealthcareServiceClaim.Identifier]
+            ? [identifierFromValue(claims[HealthcareServiceClaim.Identifier])]
+            : undefined,
+        active: claims[HealthcareServiceClaim.Active] === undefined
+            ? undefined
+            : claims[HealthcareServiceClaim.Active] === 'true',
+        providedBy: claims[HealthcareServiceClaim.Organization]
+            ? { reference: claims[HealthcareServiceClaim.Organization] }
+            : undefined,
+        category: conceptsFromCsv(claims[HealthcareServiceClaim.ServiceCategory]),
+        type: conceptsFromCsv(claims[HealthcareServiceClaim.ServiceType]),
+        specialty: conceptsFromCsv(claims[HealthcareServiceClaim.Specialty]),
+        location: referencesFromCsv(claims[HealthcareServiceClaim.Location]),
+        name: claims[HealthcareServiceClaim.Name],
+        comment: claims[HealthcareServiceClaim.Comment],
+        coverageArea: referencesFromCsv(claims[HealthcareServiceClaim.CoverageArea]),
+        program: conceptsFromCsv(claims[HealthcareServiceClaim.Program]),
+        characteristic: conceptsFromCsv(claims[HealthcareServiceClaim.Characteristic]),
+        endpoint: referencesFromCsv(claims[HealthcareServiceClaim.Endpoint]),
+    };
+}
+/** Extracts only official R4 HealthcareService SearchParameters into flat claims. */
+export function healthcareServiceFhirR4ToFlat(resource) {
+    return {
+        [HealthcareServiceClaim.Active]: resource.active === undefined ? undefined : String(resource.active),
+        [HealthcareServiceClaim.Characteristic]: conceptsToCsv(resource.characteristic),
+        [HealthcareServiceClaim.CoverageArea]: referenceListToCsv(resource.coverageArea),
+        [HealthcareServiceClaim.Endpoint]: referenceListToCsv(resource.endpoint),
+        [HealthcareServiceClaim.Identifier]: identifierToValue(resource.identifier?.[0]),
+        [HealthcareServiceClaim.Location]: referenceListToCsv(resource.location),
+        [HealthcareServiceClaim.Name]: resource.name,
+        [HealthcareServiceClaim.Comment]: resource.comment,
+        [HealthcareServiceClaim.Organization]: referenceToValue(resource.providedBy),
+        [HealthcareServiceClaim.Program]: conceptsToCsv(resource.program),
+        [HealthcareServiceClaim.ServiceCategory]: conceptsToCsv(resource.category),
+        [HealthcareServiceClaim.ServiceType]: conceptsToCsv(resource.type),
+        [HealthcareServiceClaim.Specialty]: conceptsToCsv(resource.specialty),
+    };
+}
+/** Materializes canonical HealthcareService claims as native FHIR R5. */
+export const healthcareServiceFlatToFhirR5 = healthcareServiceFlatToFhirR4;

package/dist/converters/convert-location.d.ts

@@ -1,3 +1,7 @@
 import type { FhirResource, FlatClaims } from './convert-shared.js';
 export declare function locationFlatToFhirR4(claims: FlatClaims): FhirResource;
 export declare function locationFhirR4ToFlat(resource: FhirResource): FlatClaims;
+/** Materializes canonical Location claims as native FHIR R5 (`form`, not the removed R4 `physicalType`). */
+export declare function locationFlatToFhirR5(claims: FlatClaims): FhirResource;
+/** Extracts the version-neutral Location claims from native FHIR R5. */
+export declare function locationFhirR5ToFlat(resource: FhirResource): FlatClaims;

package/dist/converters/convert-location.js

@@ -1,7 +1,7 @@
 // Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
 // File: src/convert/convert-location.ts
 import { LocationClaim } from '../claims/location-claims.js';
-import { codingFromValue, codingToValue, referenceToValue } from './convert-shared.js';
+import { codingFromValue, codingToValue, identifierFromValue, identifierToValue, referenceToValue } from './convert-shared.js';
 function splitCsv(value) {
     return String(value || '')
         .split(',')
@@ -11,7 +11,7 @@ function splitCsv(value) {
 export function locationFlatToFhirR4(claims) {
     return {
         resourceType: 'Location',
-        identifier: claims[LocationClaim.Identifier] ? [{ value: claims[LocationClaim.Identifier] }] : undefined,
+        identifier: claims[LocationClaim.Identifier] ? [identifierFromValue(claims[LocationClaim.Identifier])] : undefined,
         status: claims[LocationClaim.Status],
         name: claims[LocationClaim.Name],
         description: claims[LocationClaim.Description],
@@ -22,6 +22,15 @@ export function locationFlatToFhirR4(claims) {
         physicalType: claims[LocationClaim.PhysicalType] ? { coding: codingFromValue(claims[LocationClaim.PhysicalType]) } : undefined,
         managingOrganization: claims[LocationClaim.ManagingOrganization] ? { reference: claims[LocationClaim.ManagingOrganization] } : undefined,
         partOf: claims[LocationClaim.PartOf] ? { reference: claims[LocationClaim.PartOf] } : undefined,
+        position: claims[LocationClaim.PositionLongitude] !== undefined && claims[LocationClaim.PositionLatitude] !== undefined
+            ? {
+                longitude: Number(claims[LocationClaim.PositionLongitude]),
+                latitude: Number(claims[LocationClaim.PositionLatitude]),
+                ...(claims[LocationClaim.PositionAltitude] !== undefined
+                    ? { altitude: Number(claims[LocationClaim.PositionAltitude]) }
+                    : {}),
+            }
+            : undefined,
     };
 }
 export function locationFhirR4ToFlat(resource) {
@@ -29,7 +38,7 @@ export function locationFhirR4ToFlat(resource) {
         ?.map((item) => item?.value)
         .filter((item) => Boolean(item));
     return {
-        [LocationClaim.Identifier]: resource.identifier?.[0]?.value,
+        [LocationClaim.Identifier]: identifierToValue(resource.identifier?.[0]),
         [LocationClaim.Status]: resource.status,
         [LocationClaim.Name]: resource.name,
         [LocationClaim.Description]: resource.description,
@@ -40,5 +49,34 @@ export function locationFhirR4ToFlat(resource) {
         [LocationClaim.PhysicalType]: codingToValue(resource.physicalType?.coding?.[0]),
         [LocationClaim.ManagingOrganization]: referenceToValue(resource.managingOrganization),
         [LocationClaim.PartOf]: referenceToValue(resource.partOf),
+        [LocationClaim.PositionLongitude]: resource.position?.longitude?.toString(),
+        [LocationClaim.PositionLatitude]: resource.position?.latitude?.toString(),
+        [LocationClaim.PositionAltitude]: resource.position?.altitude?.toString(),
+    };
+}
+/** Materializes canonical Location claims as native FHIR R5 (`form`, not the removed R4 `physicalType`). */
+export function locationFlatToFhirR5(claims) {
+    const r4 = locationFlatToFhirR4(claims);
+    const { physicalType: _physicalType, telecom: _telecom, ...common } = r4;
+    const telecom = _telecom;
+    return {
+        ...common,
+        contact: telecom?.length ? [{ telecom }] : undefined,
+        form: claims[LocationClaim.PhysicalType]
+            ? { coding: codingFromValue(claims[LocationClaim.PhysicalType]) }
+            : undefined,
+    };
+}
+/** Extracts the version-neutral Location claims from native FHIR R5. */
+export function locationFhirR5ToFlat(resource) {
+    const flat = locationFhirR4ToFlat(resource);
+    const telecom = resource.contact
+        ?.flatMap(contact => contact.telecom ?? [])
+        .map(point => point.value)
+        .filter((value) => Boolean(value));
+    return {
+        ...flat,
+        [LocationClaim.Telecom]: telecom?.length ? telecom.join(',') : undefined,
+        [LocationClaim.PhysicalType]: codingToValue(resource.form?.coding?.[0]),
     };
 }

package/dist/converters/convert-organization.d.ts

@@ -1,3 +1,5 @@
 import type { FhirResource, FlatClaims } from './convert-shared.js';
 export declare function organizationFlatToFhirR4(claims: FlatClaims): FhirResource;
 export declare function organizationFhirR4ToFlat(resource: FhirResource): FlatClaims;
+/** Materializes canonical Organization claims as native FHIR R5. */
+export declare function organizationFlatToFhirR5(claims: FlatClaims): FhirResource;

package/dist/converters/convert-organization.js

@@ -1,7 +1,7 @@
 // Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
 // File: src/convert/convert-organization.ts
 import { OrganizationClaim } from '../claims/organization-claims.js';
-import { codingFromValue, codingToValue, referenceToValue } from './convert-shared.js';
+import { codingFromValue, codingToValue, identifierFromValue, identifierToValue, referenceToValue } from './convert-shared.js';
 function splitCsv(value) {
     return String(value || '')
         .split(',')
@@ -11,7 +11,7 @@ function splitCsv(value) {
 export function organizationFlatToFhirR4(claims) {
     return {
         resourceType: 'Organization',
-        identifier: claims[OrganizationClaim.Identifier] ? [{ value: claims[OrganizationClaim.Identifier] }] : undefined,
+        identifier: claims[OrganizationClaim.Identifier] ? [identifierFromValue(claims[OrganizationClaim.Identifier])] : undefined,
         active: claims[OrganizationClaim.Active] === undefined ? undefined : claims[OrganizationClaim.Active] === 'true',
         type: claims[OrganizationClaim.Type] ? [{ coding: codingFromValue(claims[OrganizationClaim.Type]) }] : undefined,
         name: claims[OrganizationClaim.Name],
@@ -27,7 +27,7 @@ export function organizationFhirR4ToFlat(resource) {
         ?.map((item) => item?.value)
         .filter((item) => Boolean(item));
     return {
-        [OrganizationClaim.Identifier]: resource.identifier?.[0]?.value,
+        [OrganizationClaim.Identifier]: identifierToValue(resource.identifier?.[0]),
         [OrganizationClaim.Active]: resource.active === undefined ? undefined : String(resource.active),
         [OrganizationClaim.Type]: codingToValue(resource.type?.[0]?.coding?.[0]),
         [OrganizationClaim.Name]: resource.name,
@@ -37,3 +37,20 @@ export function organizationFhirR4ToFlat(resource) {
         [OrganizationClaim.Address]: resource.address?.[0]?.text,
     };
 }
+/** Materializes canonical Organization claims as native FHIR R5. */
+export function organizationFlatToFhirR5(claims) {
+    const identifier = identifierFromValue(claims[OrganizationClaim.Identifier]);
+    const telecom = splitCsv(claims[OrganizationClaim.Telecom]).map((value) => ({ value }));
+    const address = claims[OrganizationClaim.Address] ? [{ text: claims[OrganizationClaim.Address] }] : [];
+    return {
+        resourceType: 'Organization',
+        identifier: identifier ? [identifier] : undefined,
+        active: claims[OrganizationClaim.Active] === undefined ? undefined : claims[OrganizationClaim.Active] === 'true',
+        type: claims[OrganizationClaim.Type] ? [{ coding: codingFromValue(claims[OrganizationClaim.Type]) }] : undefined,
+        name: claims[OrganizationClaim.Name],
+        alias: splitCsv(claims[OrganizationClaim.Alias]),
+        description: claims[OrganizationClaim.Description],
+        partOf: claims[OrganizationClaim.PartOf] ? { reference: claims[OrganizationClaim.PartOf] } : undefined,
+        contact: telecom.length || address.length ? [{ telecom, address }] : undefined,
+    };
+}

package/dist/converters/convert-procedure.d.ts

@@ -1,3 +1,5 @@
 import type { FhirResource, FlatClaims } from './convert-shared.js';
 export declare function procedureFlatToFhirR4(claims: FlatClaims): FhirResource;
 export declare function procedureFhirR4ToFlat(resource: FhirResource): FlatClaims;
+/** Explicit FHIR R5 projection, including equipment calibration and inspection. */
+export declare function procedureFlatToFhirR5(claims: FlatClaims): FhirResource;

package/dist/converters/convert-procedure.js

@@ -62,3 +62,24 @@ export function procedureFhirR4ToFlat(resource) {
         [ProcedureClaim.Note]: resource.note?.[0]?.text,
     };
 }
+/** Explicit FHIR R5 projection, including equipment calibration and inspection. */
+export function procedureFlatToFhirR5(claims) {
+    const resource = procedureFlatToFhirR4(claims);
+    const { performedDateTime, reasonCode, reasonReference, ...common } = resource;
+    return {
+        ...common,
+        occurrenceDateTime: performedDateTime,
+        reason: reasonCode || reasonReference
+            ? [
+                ...(Array.isArray(reasonCode) ? reasonCode.map(concept => ({ concept })) : []),
+                ...(Array.isArray(reasonReference) ? reasonReference.map(reference => ({ reference })) : []),
+            ]
+            : undefined,
+        focalDevice: claims[ProcedureClaim.FocalDevice]
+            ? claims[ProcedureClaim.FocalDevice].split(',').map(reference => ({ manipulated: { reference: reference.trim() } }))
+            : undefined,
+        report: claims[ProcedureClaim.Report]
+            ? claims[ProcedureClaim.Report].split(',').map(reference => ({ reference: reference.trim() }))
+            : undefined,
+    };
+}

package/dist/converters/convert-regulated-authorization.d.ts

@@ -0,0 +1,3 @@
+import type { FhirResource, FlatClaims } from './convert-shared.js';
+export declare function regulatedAuthorizationFlatToFhirR5(claims: FlatClaims): FhirResource;
+export declare function regulatedAuthorizationFhirR5ToFlat(resource: FhirResource): FlatClaims;