fhir-data-utils-ts 0.6.18 → 0.6.19

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+- Add the official `HealthcareService.appointmentRequired` flat claim and
+  R4/R5 materialization round trip. Availability remains authoritative in the
+  associated Schedule and Slot resources and is not duplicated on the service.
+
 ## 0.6.18 - 2026-10-08
 
 - Add the canonical Immunization series-dose claim, its FHIR R4 round trip,

package/dist/claims/healthcare-service-claims.d.ts

@@ -8,6 +8,7 @@ import type { ClaimSpec } from './claim-types.js';
  */
 export declare const HealthcareServiceClaim: Readonly<{
     readonly Active: "HealthcareService.active";
+    readonly AppointmentRequired: "HealthcareService.appointment-required";
     readonly Characteristic: "HealthcareService.characteristic";
     readonly CoverageArea: "HealthcareService.coverage-area";
     readonly Endpoint: "HealthcareService.endpoint";

package/dist/claims/healthcare-service-claims.js

@@ -9,6 +9,7 @@ import { defineFlatSearchParameter } from '../search-parameters.js';
  */
 export const HealthcareServiceClaim = Object.freeze({
     Active: 'HealthcareService.active',
+    AppointmentRequired: 'HealthcareService.appointment-required',
     Characteristic: 'HealthcareService.characteristic',
     CoverageArea: 'HealthcareService.coverage-area',
     Endpoint: 'HealthcareService.endpoint',
@@ -39,6 +40,7 @@ export const HealthcareServiceR4SearchParameterCatalog = Object.freeze([
 ]);
 export const HealthcareServiceClaimSpecs = Object.freeze([
     { key: HealthcareServiceClaim.Active, meaning: 'Whether the service is active.', example: 'true' },
+    { key: HealthcareServiceClaim.AppointmentRequired, meaning: 'Whether an appointment is required before receiving the service.', example: 'true' },
     { key: HealthcareServiceClaim.Characteristic, meaning: 'Repeatable service characteristic tokens as CSV.', example: 'https://example.org/CodeSystem/service-characteristic|24-hours' },
     { key: HealthcareServiceClaim.CoverageArea, meaning: 'Repeatable intended coverage Location references as CSV.', example: 'Location/british-columbia' },
     { key: HealthcareServiceClaim.Endpoint, meaning: 'Repeatable technical Endpoint references as CSV.', example: 'Endpoint/emergency-group-inbox' },

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

@@ -23,6 +23,9 @@ export function healthcareServiceFlatToFhirR4(claims) {
         active: claims[HealthcareServiceClaim.Active] === undefined
             ? undefined
             : claims[HealthcareServiceClaim.Active] === 'true',
+        appointmentRequired: claims[HealthcareServiceClaim.AppointmentRequired] === undefined
+            ? undefined
+            : claims[HealthcareServiceClaim.AppointmentRequired] === 'true',
         providedBy: claims[HealthcareServiceClaim.Organization]
             ? { reference: claims[HealthcareServiceClaim.Organization] }
             : undefined,
@@ -42,6 +45,9 @@ export function healthcareServiceFlatToFhirR4(claims) {
 export function healthcareServiceFhirR4ToFlat(resource) {
     return {
         [HealthcareServiceClaim.Active]: resource.active === undefined ? undefined : String(resource.active),
+        [HealthcareServiceClaim.AppointmentRequired]: resource.appointmentRequired === undefined
+            ? undefined
+            : String(resource.appointmentRequired),
         [HealthcareServiceClaim.Characteristic]: conceptsToCsv(resource.characteristic),
         [HealthcareServiceClaim.CoverageArea]: referenceListToCsv(resource.coverageArea),
         [HealthcareServiceClaim.Endpoint]: referenceListToCsv(resource.endpoint),

package/docs/HEALTHCARE_SERVICE_DEPARTMENT_CATALOG.md

@@ -18,6 +18,12 @@ donation independently. Each service can own different Location references and
 be the actor of a different Schedule; Slot duration and availability follow
 that Schedule rather than the department.
 
+`HealthcareService.appointmentRequired` states whether a person or animal must
+have an appointment before receiving the service. It does not describe when
+the service is available. Operational availability remains authoritative in
+the service's `Schedule` and its `Slot` resources; clients must not copy those
+intervals into a second service-level availability model.
+
 `buildServiceScheduleFlatGraph(...)` implements that boundary. It emits one
 independent claims-first `Schedule` plus independent `Slot` rows. A 15-minute
 blood-donation interval and a one-hour plasma-donation interval are represented
@@ -143,6 +149,9 @@ Repeatable coding identities remain complete `system|code` tokens; labels are
 resolved by the terminology service and are not trusted storage identity.
 `HealthcareService.comment` and R5 `Organization.description` are governed
 materialization claims, but are not falsely advertised as R4 SearchParameters.
+The same applies to `HealthcareService.appointmentRequired`: it is an official
+R4/R5 element and a governed materialization claim, not a resource-specific R4
+SearchParameter.
 
 `materializeClaimsFirstResourceToFhirR5(...)` accepts only minimal resource
 identity plus `resource.meta.claims`. It rejects nested native FHIR fields and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fhir-data-utils-ts",
-  "version": "0.6.18",
+  "version": "0.6.19",
   "description": "FHIR-version-neutral flat-claim and SearchParameter data utilities",
   "license": "Apache-2.0",
   "type": "module",