vet-data-utils-ts 0.5.37 → 0.7.0

package/README.md

@@ -23,15 +23,20 @@ and fear context as a claims-first social-history Observation. It deliberately
 uses narrative text rather than inventing a veterinary diagnosis code.
 
 The product-local `place-service-directory` export models persistent public
-sites as claims-only Schema.org `Place` resources and their offerings as
-claims-only `Service` or `Product` resources. A care organization publishes
-services; an insurance organization publishes products in a Schema.org
-`OfferCatalog`. Photos, accessibility, coordinates, address and opening-hours
-specifications remain neutral indexed claims. Native FHIR R5 `Location`,
-`HealthcareService` and `InsurancePlan` are produced only by explicit
-projection helpers. Member-specific FHIR `Coverage` is never a public catalog
-entry. The shared `gdc-*` claim catalog remains unchanged while this profile is
-validated in VetChain.
+departments as claims-only Schema.org `Organization` resources, their sites as
+`Place`, and their offerings as `Service` or `Product`. A department has one
+parent legal organization, one or more Places and several offered Services.
+Each offered Service projects through
+`projectServiceToFhirR5HealthcareService(...)` to its own stable FHIR
+`HealthcareService`; the department remains the provider Organization and
+communication sender. The old aggregate department projection fails closed. A care organization
+publishes services; an insurance organization publishes products in a
+Schema.org `OfferCatalog`. Logos, images, accessibility, coordinates, address
+and opening-hours specifications remain neutral indexed claims. Native FHIR R5
+`Organization`, `Location`, `HealthcareService` and `InsurancePlan` are
+produced only by explicit projection helpers. Member-specific FHIR `Coverage`
+is never a public catalog entry. The shared `gdc-*` claim catalog remains
+unchanged while this profile is validated in VetChain.
 
 The customer-facing Schema.org `OfferCatalog` is distinct from the Eclipse
 Dataspace Protocol catalog. `buildDataspaceCatalogAdvertisement(...)` exposes a
@@ -122,6 +127,25 @@ and applies weekly or monthly-ordinal exceptions that restrict or extend one or
 more consultation Locations. It converts clinic-local times through an IANA
 time zone, including daylight-saving changes.
 
+Every Schedule identifies exactly one HealthcareService and the resources that
+must be available together. A child Location is the independently reservable
+capacity unit; `PractitionerRole` and `Device` actors are optional and included
+only when that professional or particular machine constrains capacity. Slot duration comes only from its start/end instants.
+Schedule and Slot business identity is independent from those mutable actors.
+Callers supply one canonical service-owned Schedule URN for each reservable
+Location. `Schedule.identifier` preserves that URN and `Schedule.id` is its
+SHA3-256 base58btc multihash. `Slot.identifier` appends one
+`<startEpochSeconds>-<endEpochSeconds>` interval segment and `Slot.id` is
+derived the same way. Do not concatenate practitioner, Location, Device or DID
+values into either identity.
+Reservable rooms, booths, chairs and beds are child Locations; machines remain
+Devices. The neutral builders and canonical Schedule/Slot claim catalogs come
+from `fhir-data-utils-ts` rather than being duplicated here.
+
+An equipment failure is not itself an appointment cancellation. The equipment
+record captures the fault or availability change; scheduling separately marks
+only the affected future Slots unavailable and reconciles their appointments.
+
 The official searchable facts remain resource-qualified flat claims. The
 exported `VeterinarySlotSearchParameters` catalogue identifies the supported
 FHIR R5 Slot query codes; generated resources include `Slot.identifier`,

package/dist/place-service-directory.d.ts

@@ -21,6 +21,19 @@ export declare enum ClaimsPlaceSchemaorg {
     specialOpeningHoursSpecification = "org.schema.Place.specialOpeningHoursSpecification",
     userSelected = "Place.user-selected"
 }
+/** Schema.org flat claims for a public department/subOrganization. */
+export declare enum ClaimsDirectoryOrganizationSchemaorg {
+    identifier = "org.schema.Organization.identifier",
+    name = "org.schema.Organization.name",
+    description = "org.schema.Organization.description",
+    parentOrganizationIdentifier = "org.schema.Organization.parentOrganization.identifier",
+    additionalType = "org.schema.Organization.additionalType",
+    sameAs = "org.schema.Organization.sameAs",
+    locationIdentifier = "org.schema.Organization.location.identifier",
+    logoContentUrl = "org.schema.Organization.logo.contentUrl",
+    imageContentUrl = "org.schema.Organization.image.contentUrl",
+    userSelected = "Organization.user-selected"
+}
 /** Schema.org Service claims needed to join a public service to one or more Places. */
 export declare enum ClaimsDirectoryServiceSchemaorg {
     identifier = "org.schema.Service.identifier",
@@ -55,6 +68,7 @@ export declare enum ClaimsProductSchemaorg {
 }
 /** Product-local allowlist for the experimental Place, Service and Product directory profile. */
 export declare const DirectoryFlatClaimCatalog: Readonly<{
+    readonly Organization: readonly ClaimsDirectoryOrganizationSchemaorg[];
     readonly Place: readonly ClaimsPlaceSchemaorg[];
     readonly Service: readonly ClaimsDirectoryServiceSchemaorg[];
     readonly Product: readonly ClaimsProductSchemaorg[];
@@ -89,6 +103,21 @@ export type SpecialOpeningHoursInput = Readonly<{
     opens?: string;
     closes?: string;
 }>;
+export type DepartmentDirectoryInput = Readonly<{
+    id: string;
+    legalOrganizationIdentifier: string;
+    name: string;
+    description?: string;
+    specialty?: Readonly<{
+        system: 'http://loinc.org';
+        code: string;
+        display: string;
+    }>;
+    placeIdentifiers: readonly string[];
+    logoUrl?: string;
+    imageUrls?: readonly string[];
+    userSelected?: boolean;
+}>;
 export type PlaceDirectoryInput = Readonly<{
     id: string;
     organizationIdentifier: string;
@@ -165,6 +194,14 @@ export declare const DataspaceProtocol2025: Readonly<{
     readonly context: "https://w3id.org/dspace/2025/1/context.jsonld";
     readonly httpEndpointType: "https://w3id.org/idsa/v4.1/HTTP";
 }>;
+/**
+ * Builds the claims-only public department Organization.
+ *
+ * One department is one Schema.org/FHIR Organization. Each offered Service
+ * remains a separate directory record and owns its own HealthcareService
+ * projection through providerIdentifier.
+ */
+export declare function buildDepartmentDirectoryResource(input: DepartmentDirectoryInput): DirectoryResource;
 /** Builds the claims-only public Place authored by an organization. */
 export declare function buildPlaceDirectoryResource(input: PlaceDirectoryInput): DirectoryResource;
 /** Builds a claims-only Schema.org Service joined to its provider and public Places. */
@@ -173,6 +210,43 @@ export declare function buildServiceDirectoryResource(input: ServiceDirectoryInp
 export declare function buildProductDirectoryResource(input: ProductDirectoryInput): DirectoryResource;
 /** Rejects native fields and converts a directory resource into deterministic array-valued claims. */
 export declare function normalizeDirectoryFlatClaimsResource(input: unknown): DirectoryFlatClaimsResource;
+/** Explicitly projects one public department to a native FHIR R5 Organization. */
+export declare function projectDepartmentToFhirR5Organization(department: DirectoryResource | DirectoryFlatClaimsResource): Readonly<{
+    meta: {
+        claims: {
+            'Organization.identifier': string;
+            'Organization.active': string;
+            'Organization.name': string | undefined;
+            'Organization.part-of': string;
+        };
+    };
+    type?: {
+        coding: {
+            system: string;
+            code: string;
+        }[];
+    }[] | undefined;
+    partOf: {
+        reference: string;
+    };
+    description?: string | undefined;
+    resourceType: "Organization";
+    id: string;
+    active: true;
+    identifier: {
+        value: string;
+    }[];
+    name: string;
+}>;
+/**
+ * @deprecated Aggregate department HealthcareService projection is forbidden.
+ * Project each offered Service independently with
+ * projectServiceToFhirR5HealthcareService(...).
+ */
+export declare function projectDepartmentToFhirR5HealthcareService(department: DirectoryResource | DirectoryFlatClaimsResource, input: Readonly<{
+    services: readonly (DirectoryResource | DirectoryFlatClaimsResource)[];
+    places: readonly (DirectoryResource | DirectoryFlatClaimsResource)[];
+}>): void;
 /** Explicitly projects one neutral Place to native FHIR R5 Location for export or interop. */
 export declare function projectPlaceToFhirR5Location(place: DirectoryResource | DirectoryFlatClaimsResource): Readonly<{
     resourceType: "Location";
@@ -340,7 +414,7 @@ export declare function buildOrganizationOfferCatalog(input: Readonly<{
     itemListElement: readonly Readonly<{
         '@type': "Offer";
         itemOffered: Readonly<{
-            '@type': "Place" | "Service" | "Product";
+            '@type': "Organization" | "Place" | "Service" | "Product";
             identifier: string;
             name: string;
         }>;

package/dist/place-service-directory.js

@@ -23,6 +23,20 @@ export var ClaimsPlaceSchemaorg;
     ClaimsPlaceSchemaorg["specialOpeningHoursSpecification"] = "org.schema.Place.specialOpeningHoursSpecification";
     ClaimsPlaceSchemaorg["userSelected"] = "Place.user-selected";
 })(ClaimsPlaceSchemaorg || (ClaimsPlaceSchemaorg = {}));
+/** Schema.org flat claims for a public department/subOrganization. */
+export var ClaimsDirectoryOrganizationSchemaorg;
+(function (ClaimsDirectoryOrganizationSchemaorg) {
+    ClaimsDirectoryOrganizationSchemaorg["identifier"] = "org.schema.Organization.identifier";
+    ClaimsDirectoryOrganizationSchemaorg["name"] = "org.schema.Organization.name";
+    ClaimsDirectoryOrganizationSchemaorg["description"] = "org.schema.Organization.description";
+    ClaimsDirectoryOrganizationSchemaorg["parentOrganizationIdentifier"] = "org.schema.Organization.parentOrganization.identifier";
+    ClaimsDirectoryOrganizationSchemaorg["additionalType"] = "org.schema.Organization.additionalType";
+    ClaimsDirectoryOrganizationSchemaorg["sameAs"] = "org.schema.Organization.sameAs";
+    ClaimsDirectoryOrganizationSchemaorg["locationIdentifier"] = "org.schema.Organization.location.identifier";
+    ClaimsDirectoryOrganizationSchemaorg["logoContentUrl"] = "org.schema.Organization.logo.contentUrl";
+    ClaimsDirectoryOrganizationSchemaorg["imageContentUrl"] = "org.schema.Organization.image.contentUrl";
+    ClaimsDirectoryOrganizationSchemaorg["userSelected"] = "Organization.user-selected";
+})(ClaimsDirectoryOrganizationSchemaorg || (ClaimsDirectoryOrganizationSchemaorg = {}));
 /** Schema.org Service claims needed to join a public service to one or more Places. */
 export var ClaimsDirectoryServiceSchemaorg;
 (function (ClaimsDirectoryServiceSchemaorg) {
@@ -59,6 +73,7 @@ export var ClaimsProductSchemaorg;
 })(ClaimsProductSchemaorg || (ClaimsProductSchemaorg = {}));
 /** Product-local allowlist for the experimental Place, Service and Product directory profile. */
 export const DirectoryFlatClaimCatalog = Object.freeze({
+    Organization: Object.freeze(Object.values(ClaimsDirectoryOrganizationSchemaorg)),
     Place: Object.freeze(Object.values(ClaimsPlaceSchemaorg)),
     Service: Object.freeze(Object.values(ClaimsDirectoryServiceSchemaorg)),
     Product: Object.freeze(Object.values(ClaimsProductSchemaorg)),
@@ -151,6 +166,51 @@ function encodeSpecialOpeningHours(value) {
         throw new TypeError('place_special_opening_hours_invalid');
     return JSON.stringify({ validFrom, validThrough, opens: value.opens, closes: value.closes });
 }
+/**
+ * Builds the claims-only public department Organization.
+ *
+ * One department is one Schema.org/FHIR Organization. Each offered Service
+ * remains a separate directory record and owns its own HealthcareService
+ * projection through providerIdentifier.
+ */
+export function buildDepartmentDirectoryResource(input) {
+    const id = required(input.id, 'department_id_required');
+    if (!RESOURCE_ID_PATTERN.test(id))
+        throw new TypeError('department_id_invalid');
+    const placeIdentifiers = unique(input.placeIdentifiers, 'department_place_invalid');
+    if (!placeIdentifiers.length)
+        throw new TypeError('department_place_required');
+    const logoUrl = optionalHttpsUrl(input.logoUrl, 'department_logo_url_invalid');
+    const imageUrls = unique(input.imageUrls, 'department_image_url_invalid').map(value => {
+        const imageUrl = optionalHttpsUrl(value, 'department_image_url_invalid');
+        if (!imageUrl)
+            throw new TypeError('department_image_url_invalid');
+        return imageUrl;
+    });
+    const claims = {
+        [ClaimsDirectoryOrganizationSchemaorg.identifier]: id,
+        [ClaimsDirectoryOrganizationSchemaorg.name]: required(input.name, 'department_name_required'),
+        [ClaimsDirectoryOrganizationSchemaorg.parentOrganizationIdentifier]: required(input.legalOrganizationIdentifier, 'department_parent_organization_required'),
+        [ClaimsDirectoryOrganizationSchemaorg.sameAs]: `Organization/${id}`,
+        [ClaimsDirectoryOrganizationSchemaorg.locationIdentifier]: placeIdentifiers,
+        [ClaimsDirectoryOrganizationSchemaorg.userSelected]: input.userSelected ?? false,
+    };
+    const description = optional(input.description);
+    if (description)
+        claims[ClaimsDirectoryOrganizationSchemaorg.description] = description;
+    if (input.specialty) {
+        if (input.specialty.system !== 'http://loinc.org'
+            || !/^L(?:A|P)\d+(?:-\d+)?$/.test(input.specialty.code)
+            || !optional(input.specialty.display))
+            throw new TypeError('department_specialty_invalid');
+        claims[ClaimsDirectoryOrganizationSchemaorg.additionalType] = `${input.specialty.system}/${input.specialty.code}`;
+    }
+    if (logoUrl)
+        claims[ClaimsDirectoryOrganizationSchemaorg.logoContentUrl] = logoUrl;
+    if (imageUrls.length)
+        claims[ClaimsDirectoryOrganizationSchemaorg.imageContentUrl] = Object.freeze(imageUrls);
+    return Object.freeze({ resourceType: 'Organization', id, meta: Object.freeze({ claims: Object.freeze(claims) }) });
+}
 /** Builds the claims-only public Place authored by an organization. */
 export function buildPlaceDirectoryResource(input) {
     const id = required(input.id, 'place_id_required');
@@ -302,7 +362,7 @@ export function normalizeDirectoryFlatClaimsResource(input) {
     if (!input || typeof input !== 'object' || Array.isArray(input))
         throw new TypeError('directory_flat_resource_invalid');
     const value = input;
-    if ((value.resourceType !== 'Place' && value.resourceType !== 'Service' && value.resourceType !== 'Product') || Object.keys(value).some(key => !['resourceType', 'id', 'meta'].includes(key)))
+    if ((value.resourceType !== 'Organization' && value.resourceType !== 'Place' && value.resourceType !== 'Service' && value.resourceType !== 'Product') || Object.keys(value).some(key => !['resourceType', 'id', 'meta'].includes(key)))
         throw new TypeError('directory_flat_resource_invalid');
     const resourceType = value.resourceType;
     const id = required(value.id, 'directory_flat_resource_invalid');
@@ -338,6 +398,38 @@ function parseJson(value, code) {
         throw new TypeError(code);
     }
 }
+/** Explicitly projects one public department to a native FHIR R5 Organization. */
+export function projectDepartmentToFhirR5Organization(department) {
+    if (department.resourceType !== 'Organization')
+        throw new TypeError('department_resource_required');
+    const parent = required(first(department, ClaimsDirectoryOrganizationSchemaorg.parentOrganizationIdentifier), 'department_parent_organization_required');
+    const additionalType = first(department, ClaimsDirectoryOrganizationSchemaorg.additionalType);
+    return Object.freeze({
+        resourceType: 'Organization', id: department.id, active: true,
+        identifier: [{ value: department.id }],
+        name: required(first(department, ClaimsDirectoryOrganizationSchemaorg.name), 'department_name_required'),
+        ...(first(department, ClaimsDirectoryOrganizationSchemaorg.description)
+            ? { description: first(department, ClaimsDirectoryOrganizationSchemaorg.description) } : {}),
+        partOf: { reference: parent },
+        ...(additionalType ? { type: [{ coding: [{ system: 'http://loinc.org', code: additionalType.replace('http://loinc.org/', '') }] }] } : {}),
+        meta: { claims: {
+                'Organization.identifier': department.id,
+                'Organization.active': 'true',
+                'Organization.name': first(department, ClaimsDirectoryOrganizationSchemaorg.name),
+                'Organization.part-of': parent,
+            } },
+    });
+}
+/**
+ * @deprecated Aggregate department HealthcareService projection is forbidden.
+ * Project each offered Service independently with
+ * projectServiceToFhirR5HealthcareService(...).
+ */
+export function projectDepartmentToFhirR5HealthcareService(department, input) {
+    void department;
+    void input;
+    throw new TypeError('department_aggregate_healthcare_service_forbidden');
+}
 /** Explicitly projects one neutral Place to native FHIR R5 Location for export or interop. */
 export function projectPlaceToFhirR5Location(place) {
     if (place.resourceType !== 'Place')
@@ -387,7 +479,8 @@ export function projectServiceToFhirR5HealthcareService(service, input) {
     });
     const serviceTypes = values(service, ClaimsDirectoryServiceSchemaorg.serviceType);
     const categories = values(service, ClaimsDirectoryServiceSchemaorg.category);
-    const organization = required(first(service, ClaimsDirectoryServiceSchemaorg.providerIdentifier), 'service_organization_required');
+    const rawOrganization = required(first(service, ClaimsDirectoryServiceSchemaorg.providerIdentifier), 'service_organization_required');
+    const organization = rawOrganization.startsWith('Organization/') ? rawOrganization : `Organization/${rawOrganization}`;
     const photoUrl = places.map(place => first(place, ClaimsPlaceSchemaorg.photoContentUrl)).find(Boolean);
     const concept = (code) => ({ coding: [{ code }] });
     return Object.freeze({

package/dist/scheduling.d.ts

@@ -1,3 +1,4 @@
+import { buildSchedulableLocationFlatResource } from 'fhir-data-utils-ts';
 /** FHIR R5 Slot statuses accepted by reusable scheduling. */
 export declare const SlotStatuses: Readonly<{
     readonly Busy: "busy";
@@ -28,12 +29,12 @@ export declare const AppointmentStatuses: Readonly<{
     readonly Waitlist: "waitlist";
 }>;
 /** Official FHIR R5 Slot resource-specific SearchParameter codes. */
-export declare const SlotSearchParameters: readonly ["appointment-type", "identifier", "schedule", "service-category", "service-type", "service-type-reference", "specialty", "start", "status"];
+export declare const SlotSearchParameters: readonly string[];
 /** Official FHIR R5 SearchParameter codes used by reusable scheduling. */
 export declare const SchedulingSearchParameterCatalog: Readonly<{
     readonly Location: readonly string[];
     readonly Schedule: readonly string[];
-    readonly Slot: readonly ["appointment-type", "identifier", "schedule", "service-category", "service-type", "service-type-reference", "specialty", "start", "status"];
+    readonly Slot: readonly string[];
     readonly Appointment: readonly string[];
     readonly AppointmentResponse: readonly string[];
 }>;
@@ -47,7 +48,7 @@ export type SchedulingFlatClaimsResource = Readonly<Record<string, unknown> & {
         claims: Readonly<Record<string, readonly string[]>>;
     }>;
 }>;
-/** Validates native FHIR scheduling data and normalizes indexed SearchParameter claims to strings. */
+/** Rejects nested native FHIR and normalizes governed flat claims to strings. */
 export declare function normalizeSchedulingFlatClaimsResource(input: unknown): SchedulingFlatClaimsResource;
 export type ClaimsFirstResource = Readonly<Record<string, unknown> & {
     resourceType: string;
@@ -68,15 +69,18 @@ export declare function buildLocationResource(input: Readonly<{
     characteristicCodes?: readonly string[];
     photoUrl?: string;
 }>): ClaimsFirstResource;
-/** Builds the claims-first FHIR R5 Schedule joining one practitioner and consultation Location. */
+/** Builds one service-specific Schedule through the neutral FHIR claims graph. */
 export declare function buildScheduleResource(input: Readonly<{
-    id: string;
+    scheduleUrn: string;
     name: string;
-    practitionerReference: string;
-    locationReference: string;
+    healthcareServiceReference: string;
+    resourceActorReferences: readonly string[];
+    serviceType: string;
     planningHorizonStart: string;
     planningHorizonEnd: string;
 }>): ClaimsFirstResource;
+/** Builds one independently reservable child Location; equipment remains Device. */
+export declare const buildSchedulableLocationResource: typeof buildSchedulableLocationFlatResource;
 export type AvailabilityPeriod = Readonly<{
     daysOfWeek: readonly number[];
     startTime: string;
@@ -101,11 +105,13 @@ export type ExpandedSlot = Readonly<{
     locationReference: string;
     resource: ClaimsFirstResource;
 }>;
-/** Produces the stable Schedule id for one practitioner/location availability stream. */
-export declare function scheduleIdForLocation(baseScheduleId: string, locationReference: string): string;
 /** Expands bounded weekly availability into claims-first Slots, applying recurring restrictions or expansions. */
 export declare function expandAvailability(input: Readonly<{
-    scheduleId: string;
+    /** One service-owned Schedule URN for each independently reservable Location. */
+    scheduleUrnsByLocation: Readonly<Record<string, string>>;
+    healthcareServiceReference: string;
+    serviceType: string;
+    resourceActorReferencesByLocation: Readonly<Record<string, readonly string[]>>;
     startDate: string;
     endDate: string;
     timeZone: string;
@@ -161,7 +167,7 @@ export declare function buildAppointmentNotificationResource(input: Readonly<{
     reason: string;
 }>): ClaimsFirstResource;
 /** @deprecated Use {@link SlotSearchParameters}. */
-export declare const VeterinarySlotSearchParameters: readonly ["appointment-type", "identifier", "schedule", "service-category", "service-type", "service-type-reference", "specialty", "start", "status"];
+export declare const VeterinarySlotSearchParameters: readonly string[];
 /** @deprecated Use {@link SchedulingFlatClaimCatalog}. */
 export declare const VeterinarySchedulingFlatClaimCatalog: Readonly<Record<"Appointment" | "AppointmentResponse" | "Location" | "Schedule" | "Slot", readonly string[]>>;
 /** @deprecated Use {@link SchedulingResourceType}. */

package/dist/scheduling.js

@@ -1,3 +1,5 @@
+import { ScheduleR5SearchParameterCatalog, SlotR5SearchParameterCatalog, buildSchedulableLocationFlatResource, buildServiceScheduleFlatGraph, } from 'fhir-data-utils-ts';
+import { buildScheduleSlotIdentity, deriveFhirResourceIdFromUrn, } from 'sos-data-utils-ts/organization-scoped-resource-identity';
 /** FHIR R5 Slot statuses accepted by reusable scheduling. */
 export const SlotStatuses = Object.freeze({ Busy: 'busy', Free: 'free', BusyUnavailable: 'busy-unavailable', BusyTentative: 'busy-tentative', EnteredInError: 'entered-in-error' });
 /** FHIR R5 AppointmentResponse participant statuses. */
@@ -8,11 +10,11 @@ export const AppointmentStatuses = Object.freeze({
     Cancelled: 'cancelled', NoShow: 'noshow', EnteredInError: 'entered-in-error', CheckedIn: 'checked-in', Waitlist: 'waitlist',
 });
 /** Official FHIR R5 Slot resource-specific SearchParameter codes. */
-export const SlotSearchParameters = Object.freeze(['appointment-type', 'identifier', 'schedule', 'service-category', 'service-type', 'service-type-reference', 'specialty', 'start', 'status']);
+export const SlotSearchParameters = Object.freeze(SlotR5SearchParameterCatalog.map(definition => definition.claim.slice('Slot.'.length)));
 /** Official FHIR R5 SearchParameter codes used by reusable scheduling. */
 export const SchedulingSearchParameterCatalog = Object.freeze({
     Location: Object.freeze(['characteristic', 'identifier', 'name', 'near', 'organization', 'status', 'type']),
-    Schedule: Object.freeze(['active', 'actor', 'date', 'identifier', 'name', 'service-category', 'service-type', 'specialty']),
+    Schedule: Object.freeze(ScheduleR5SearchParameterCatalog.map(definition => definition.claim.slice('Schedule.'.length))),
     Slot: SlotSearchParameters,
     Appointment: Object.freeze(['actor', 'appointment-type', 'based-on', 'date', 'identifier', 'location', 'part-status', 'patient', 'practitioner', 'reason-code', 'reason-reference', 'service-category', 'service-type', 'slot', 'specialty', 'status', 'subject', 'supporting-info']),
     AppointmentResponse: Object.freeze(['_lastUpdated', 'actor', 'appointment', 'group', 'identifier', 'location', 'part-status', 'patient', 'practitioner']),
@@ -22,17 +24,12 @@ export const SchedulingFlatClaimCatalog = Object.freeze(Object.fromEntries(Objec
     resourceType,
     Object.freeze([
         ...parameters.map(parameter => `${resourceType}.${parameter}`),
+        ...(resourceType === 'Schedule' ? ['Schedule.planning-horizon-start', 'Schedule.planning-horizon-end'] : []),
+        ...(resourceType === 'Slot' ? ['Slot.end'] : []),
         ...(resourceType === 'Appointment' ? ['Appointment.user-selected'] : []),
     ]),
 ])));
-const nativeFieldsByResource = Object.freeze({
-    Location: new Set(['identifier', 'status', 'mode', 'name', 'description', 'type', 'telecom', 'address', 'physicalType', 'position', 'managingOrganization', 'characteristic', 'contained']),
-    Schedule: new Set(['identifier', 'active', 'serviceCategory', 'serviceType', 'specialty', 'name', 'actor', 'planningHorizon', 'comment']),
-    Slot: new Set(['identifier', 'serviceCategory', 'serviceType', 'specialty', 'appointmentType', 'schedule', 'status', 'start', 'end', 'overbooked', 'comment']),
-    Appointment: new Set(['identifier', 'status', 'serviceCategory', 'serviceType', 'specialty', 'appointmentType', 'reason', 'description', 'start', 'end', 'slot', 'participant', 'subject', 'note', 'supportingInformation', 'contained']),
-    AppointmentResponse: new Set(['identifier', 'appointment', 'proposedNewTime', 'start', 'end', 'participantType', 'actor', 'participantStatus', 'comment', 'recurring', 'occurrenceDate', 'recurrenceId', 'contained']),
-});
-/** Validates native FHIR scheduling data and normalizes indexed SearchParameter claims to strings. */
+/** Rejects nested native FHIR and normalizes governed flat claims to strings. */
 export function normalizeSchedulingFlatClaimsResource(input) {
     if (!input || typeof input !== 'object' || Array.isArray(input))
         throw new TypeError('scheduling_flat_resource_invalid');
@@ -40,7 +37,7 @@ export function normalizeSchedulingFlatClaimsResource(input) {
     if (typeof value.resourceType !== 'string' || !(value.resourceType in SchedulingFlatClaimCatalog))
         throw new TypeError('scheduling_flat_resource_invalid');
     const resourceType = value.resourceType;
-    if (Object.keys(value).some(key => !['resourceType', 'id', 'meta'].includes(key) && !nativeFieldsByResource[resourceType].has(key)))
+    if (Object.keys(value).some(key => !['resourceType', 'id', 'meta'].includes(key)))
         throw new TypeError('scheduling_flat_resource_invalid');
     const id = required(String(value.id || ''), 'scheduling_flat_resource_invalid');
     if (!/^[A-Za-z0-9\-.]{1,64}$/.test(id))
@@ -90,31 +87,25 @@ export function buildLocationResource(input) {
         'Location.near': `${input.latitude}|${input.longitude}`,
         'Location.organization': organizationReference,
         ...(characteristicCodes.length ? { 'Location.characteristic': characteristicCodes } : {}),
-    }, {
-        identifier: [{ value: input.id }], status: 'active', mode: 'instance', name,
-        ...(input.description ? { description: input.description.trim() } : {}),
-        position: { latitude: input.latitude, longitude: input.longitude, ...(input.altitude === undefined ? {} : { altitude: input.altitude }) },
-        managingOrganization: { reference: organizationReference },
-        ...(characteristicCodes.length ? { characteristic: characteristicCodes.map(code => ({ coding: [{ code }] })) } : {}),
-        ...(input.photoUrl ? { contained: [{ resourceType: 'DocumentReference', id: 'location-photo', status: 'current', content: [{ attachment: { url: input.photoUrl } }] }] } : {}),
     });
 }
-/** Builds the claims-first FHIR R5 Schedule joining one practitioner and consultation Location. */
+/** Builds one service-specific Schedule through the neutral FHIR claims graph. */
 export function buildScheduleResource(input) {
-    const start = assertDate(input.planningHorizonStart);
-    const end = assertDate(input.planningHorizonEnd);
-    if (start > end)
-        throw new Error('schedule_horizon_invalid');
-    const name = required(input.name, 'schedule_name_required');
-    const actors = Object.freeze([required(input.practitionerReference, 'schedule_practitioner_required'), required(input.locationReference, 'schedule_location_required')]);
-    return claimsResource('Schedule', input.id, {
-        'Schedule.identifier': input.id, 'Schedule.active': true, 'Schedule.name': name,
-        'Schedule.actor': actors, 'Schedule.date': Object.freeze([start, end]),
-    }, {
-        identifier: [{ value: input.id }], active: true, name,
-        actor: actors.map(reference => ({ reference })), planningHorizon: { start, end },
+    const id = deriveFhirResourceIdFromUrn(input.scheduleUrn);
+    const graph = buildServiceScheduleFlatGraph({
+        scheduleId: id,
+        scheduleIdentifier: input.scheduleUrn,
+        name: input.name,
+        healthcareServiceReference: input.healthcareServiceReference,
+        resourceActorReferences: input.resourceActorReferences,
+        serviceType: input.serviceType,
+        planningHorizon: { start: input.planningHorizonStart, end: input.planningHorizonEnd },
+        slots: [],
     });
+    return graph[0];
 }
+/** Builds one independently reservable child Location; equipment remains Device. */
+export const buildSchedulableLocationResource = buildSchedulableLocationFlatResource;
 const minutes = (value) => { const [hour, minute] = assertTime(value).split(':').map(Number); return hour * 60 + minute; };
 const timeFromMinutes = (value) => `${String(Math.floor(value / 60)).padStart(2, '0')}:${String(value % 60).padStart(2, '0')}`;
 const dates = (start, end) => { const result = []; const cursor = new Date(`${start}T00:00:00Z`); const last = new Date(`${end}T00:00:00Z`); while (cursor <= last) {
@@ -140,12 +131,6 @@ const matchesExceptionDate = (date, recurrence) => { const [, , day] = dateParts
 const validateRange = (startTime, endTime, code) => { const start = minutes(startTime); const end = minutes(endTime); if (start >= end)
     throw new Error(code); return [start, end]; };
 const slotKey = (location, date, start, end) => `${location}|${date}|${start}|${end}`;
-/** Produces the stable Schedule id for one practitioner/location availability stream. */
-export function scheduleIdForLocation(baseScheduleId, locationReference) {
-    const base = required(baseScheduleId, 'schedule_id_required');
-    const locationId = required(locationReference, 'availability_location_required').split('/').at(-1);
-    return `${base}-${locationId}`;
-}
 /** Expands bounded weekly availability into claims-first Slots, applying recurring restrictions or expansions. */
 export function expandAvailability(input) {
     const startDate = assertDate(input.startDate);
@@ -201,11 +186,33 @@ export function expandAvailability(input) {
     return Object.freeze([...base.values()].sort((left, right) => slotKey(left.locationReference, left.localDate, left.localStart, left.localEnd).localeCompare(slotKey(right.locationReference, right.localDate, right.localStart, right.localEnd))).map(slot => {
         const start = zonedInstant(slot.localDate, slot.localStart, input.timeZone);
         const end = zonedInstant(slot.localDate, slot.localEnd, input.timeZone);
-        const id = `${input.scheduleId}-${slot.localDate}-${slot.localStart.replace(':', '')}-${slot.locationReference.split('/').at(-1)}`;
-        const scheduleReference = `Schedule/${scheduleIdForLocation(input.scheduleId, slot.locationReference)}`;
-        return Object.freeze({ ...slot, resource: claimsResource('Slot', id, {
-                'Slot.identifier': id, 'Slot.schedule': scheduleReference, 'Slot.status': SlotStatuses.Free, 'Slot.start': start,
-            }, { identifier: [{ value: id }], schedule: { reference: scheduleReference }, status: SlotStatuses.Free, start, end }) });
+        const scheduleUrn = required(input.scheduleUrnsByLocation[slot.locationReference] || '', 'availability_schedule_urn_required');
+        const scheduleResourceId = deriveFhirResourceIdFromUrn(scheduleUrn);
+        const slotIdentity = buildScheduleSlotIdentity({ scheduleUrn, start, end });
+        const scheduleReference = `Schedule/${scheduleResourceId}`;
+        const actors = input.resourceActorReferencesByLocation[slot.locationReference];
+        if (!actors?.includes(slot.locationReference))
+            throw new Error('availability_resource_actors_required');
+        const graph = buildServiceScheduleFlatGraph({
+            scheduleId: scheduleReference.slice('Schedule/'.length),
+            scheduleIdentifier: scheduleReference,
+            name: scheduleReference,
+            healthcareServiceReference: input.healthcareServiceReference,
+            resourceActorReferences: actors,
+            serviceType: input.serviceType,
+            planningHorizon: {
+                start: zonedInstant(startDate, '00:00', input.timeZone),
+                end: new Date(Date.parse(zonedInstant(endDate, '23:59', input.timeZone)) + 60_000).toISOString(),
+            },
+            slots: [{
+                    slotId: slotIdentity.id,
+                    slotIdentifier: slotIdentity.identifier,
+                    status: SlotStatuses.Free,
+                    start,
+                    end,
+                }],
+        });
+        return Object.freeze({ ...slot, resource: graph[1] });
     }));
 }
 /** Builds a claims-first response that confirms, declines or proposes a new appointment time. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vet-data-utils-ts",
-  "version": "0.5.37",
+  "version": "0.7.0",
   "description": "Browser-safe governed VetChain data contracts",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -157,10 +157,10 @@
     "typescript": "^5.5.4"
   },
   "dependencies": {
-    "fhir-data-utils-ts": "0.2.4",
+    "fhir-data-utils-ts": "0.6.0",
     "gdc-common-utils-ts": "2.9.12",
     "pako": "^2.2.0",
-    "sos-data-utils-ts": "0.3.7"
+    "sos-data-utils-ts": "0.5.1"
   },
   "engines": {
     "node": ">=20"