fhir-data-utils-ts 0.6.20 → 0.6.22

package/.codex/skills/govern-fhir-data-utilities/SKILL.md

@@ -1,25 +1,23 @@
 ---
 name: govern-fhir-data-utilities
-description: Complete or audit migrations, claim catalogs, converters, builders, tests and releases in fhir-data-utils-ts. Use for shared FHIR types or utilities copied from frozen gdc-common-utils, former UHC utilities, SOS, Vet or UHC packages; raw flat-claim literals; duplicate root and family modules; Observation components; Immunization graphs; Group or ResearchStudy projections; package exports; coverage gates; or downstream promotion.
+description: Complete or audit migrations, claim catalogs, converters, builders, tests and releases in fhir-data-utils-ts. Use for shared FHIR types or utilities recovered from standards-based compatibility evidence; raw flat-claim literals; duplicate root and family modules; Observation components; Immunization graphs; Group or ResearchStudy projections; package exports; coverage gates; or downstream promotion.
 ---
 
 # Govern FHIR Data Utilities
 
 ## Keep ownership explicit
 
-1. Read `docs/UHC_FHIR_UTILS_MIGRATION.md` and inventory every relevant source
-   family before declaring a migration complete.
+1. Inventory every relevant standards-based source family before declaring a
+   migration complete.
 2. Treat `gdc-*` repositories as read-only evidence unless the user explicitly
    changes that scope. Never patch them as part of this migration.
 3. Keep neutral FHIR data semantics here. Keep HTTP, SMART, DIDComm, storage,
    authorization and product policy in their owning services or sector packages.
 4. Define every flat key once in its owning named catalog. Import that symbol in
    converters, builders, tests and examples; never repeat a claim-path literal.
-5. For SHC and DGC archaeology, treat `uhc-helpers-typescript` as the early
-   flow source, the later UHC common models/data/common/crypto split as the
-   preferred implementation evidence, and `gdc-common-utils-ts` as its later
-   consolidation. Do not copy an earlier helper when a later governed contract
-   exists.
+5. For SHC and DGC archaeology, prefer the latest governed standards-based
+   implementation evidence. Do not copy an earlier helper when a later
+   governed contract exists.
 
 ## Separate catalogs, adapters and builders
 
@@ -68,9 +66,8 @@ description: Complete or audit migrations, claim catalogs, converters, builders,
   subscriber persistence, authentication or product notification policy.
 - Validate and project the canonical outer `Bundle[type=batch]` ->
   `Communication` -> inner `Bundle[type=document|batch|collection]` structure
-  here, but keep the cross-product high-level editor/reader in `sos-sdk-core`
-  and its data contracts in `sos-data-utils`. Neither replacement package may
-  import frozen `gdc-*`. Arbitrary files are DocumentReference entries in the
+  here, but keep high-level editors/readers and application data contracts in
+  downstream libraries. Arbitrary files are DocumentReference entries in the
   inner Bundle, never a second direct Communication attachment. Direct
   flat-claim CRUD is an internal persistence boundary, not this wire format.
 - Keep ImagingStudy searchable metadata, clinical references and protected

package/.codex/skills/govern-fhir-observation-components/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: govern-fhir-observation-components
-description: Implement or audit neutral FHIR Observation claim catalogs, vital-sign terminology, parent-owned component graphs, reduced component indexes, historical array and bp aliases, and R4/R5 projection adapters. Use when changing Observation.component, blood pressure, assessment scales, device readings, flat claims, portal or assistant vital-sign builders, or migrating code from gdc-common-utils-ts or uhc-fhir-utils-typescript.
+description: Implement or audit neutral FHIR Observation claim catalogs, vital-sign terminology, parent-owned component graphs, reduced component indexes, historical array and bp aliases, and R4/R5 projection adapters. Use when changing Observation.component, blood pressure, assessment scales, device readings, flat claims, portal or assistant vital-sign builders, or migrating neutral compatibility code.
 ---
 
 # Govern FHIR Observation Components
@@ -9,12 +9,12 @@ description: Implement or audit neutral FHIR Observation claim catalogs, vital-s
 
 1. Treat native FHIR import/export as an adapter boundary. Keep flat claims as
    the version-neutral internal contract.
-2. Read `src/observation-claims.ts`, `src/vital-sign-observations.ts`, their
-   tests, and `docs/UHC_FHIR_UTILS_MIGRATION.md` before changing behavior.
-3. Treat every `gdc-*` repository and `uhc-fhir-utils-typescript` as read-only
-   compatibility evidence unless the user explicitly changes that scope.
-4. Keep product policies in SOS, Vet or UHC packages. This package owns only
-   neutral FHIR data semantics.
+2. Read `src/observation-claims.ts`, `src/vital-sign-observations.ts` and their
+   tests before changing behavior.
+3. Treat external compatibility repositories as read-only evidence unless the
+   user explicitly changes that scope.
+4. Keep product policies downstream. This package owns only neutral FHIR data
+   semantics.
 
 ## Preserve the component contract
 
@@ -79,15 +79,13 @@ description: Implement or audit neutral FHIR Observation claim catalogs, vital-s
 
 ## Audit migrations completely
 
-- Inventory the old UHC package, `gdc-common-utils-ts`, `sos-data-utils-ts`,
-  `vet-data-utils-ts`, and the UHC/Vet/SOS SDKs before calling a migration
-  complete.
+- Inventory the relevant standards-based source and compatibility evidence
+  before calling a migration complete.
 - Move only neutral FHIR data types, claim catalogs, conversion rules and pure
   helpers here. Keep transport clients and sector authorization/policy in
   their owning package.
-- Record every migrated, retired or intentionally retained family in
-  `docs/UHC_FHIR_UTILS_MIGRATION.md`; an unmentioned file is an incomplete
-  audit.
+- Record every migrated, retired or intentionally retained family in neutral
+  repository documentation; an unmentioned file is an incomplete audit.
 - Expose each supported family through a stable package subpath and prove the
   packed artifact, not only root source imports.
 

package/.codex/skills/preserve-fhir-flat-coding-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: preserve-fhir-flat-coding-review
-description: Preserve the neutral flat-claim contract for imported local clinical text, terminology proposals and confirmed codings. Use when changing DataConv, Vet or UHC ingestion, ResearchSubject batches, contained clinical resources, coding-review UI/API contracts, examples, fixtures or tests.
+description: Preserve the neutral flat-claim contract for imported local clinical text, terminology proposals and confirmed codings. Use when changing ingestion, ResearchSubject batches, contained clinical resources, coding-review UI/API contracts, examples, fixtures or tests.
 ---
 
 # Preserve FHIR Flat Coding Review
@@ -24,7 +24,7 @@ redeclare governed claim paths, code systems, UUIDs or example values.
   `userSelected` as a draft or promotion flag.
 - Group review UI with the package-owned clinical families: allergies and
   intolerances, procedures, diagnostics and immunizations. Do not duplicate
-  resource-type lists in Vet, UHC or DataConv consumers.
+  resource-type lists in downstream consumers.
 - A localized generated label may use a language-qualified `-text_<BCP47>`
   companion. It must not overwrite the imported local text before explicit
   review.
@@ -60,9 +60,9 @@ redeclare governed claim paths, code systems, UUIDs or example values.
 ## Boundaries
 
 - This is FHIR-neutral shared data behavior. It belongs in
-  `fhir-data-utils-ts`, not SOSChain, Vet, UHC or frozen `gdc-*` packages.
-- DataConv applies the contract during import. Vet and UHC consume the same
-  contract and may add sector policy without forking its claim shape.
+  `fhir-data-utils-ts`, not in downstream or frozen compatibility packages.
+- Importers and sector applications consume the same contract and may add
+  policy without forking its claim shape.
 - Do not put HTTP clients, gateway policy, product authorization or terminology
   catalogs in this package.
 - Tests and examples import package-owned fixtures/builders. Do not scatter raw

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+- Re-establish the public repository from a clean source snapshot while
+  retaining this changelog as the package release record.
+
+## 0.6.22 - 2026-10-22
+
+- Add FHIR-owned flat claims and a lossless R4 extension round trip for the
+  optional US Core Patient race and ethnicity extensions. Preserve OMB and
+  detailed Coding tokens separately from the required human-readable text;
+  derive the official `Patient.race` and `Patient.ethnicity` token-search
+  claims instead of accepting them from a browser; and do not expose these
+  jurisdictional fields as universal demographics or org.schema properties.
+
+## 0.6.21 - 2026-10-21
+
+- Add the shared CommunicationRequest form, flat-claim and materialization
+  fields needed for categorized public alerts, related attachments and bounded
+  occurrence periods without introducing a proprietary alert resource.
+
 ## 0.6.20 - 2026-10-12
 
 - Export the deduplicated official LOINC Document Ontology subject-matter-
@@ -58,8 +76,8 @@
 - Give every reusable IPS authoring schema canonical initial claims so portal
   components do not invent resource status defaults.
 
-- Recover the useful locale-aware intent of the historical UHC
-  internationalization helpers as strict FHIR temporal presentation tools.
+- Recover useful locale-aware behavior from historical compatibility helpers
+  as strict FHIR temporal presentation tools.
   Date-only values retain their calendar day, instants render with the user's
   locale and IANA time zone, editor date/time fields compose a canonical FHIR
   instant with optional seconds defaulted to `00`, and inclusive ranges treat
@@ -86,8 +104,8 @@
   document so portals can update the Composition without duplicating LOINC
   section codes.
 
-- Recover neutral SHC and EU DGC QR prefix classification from the later UHC
-  data-utility lineage, with exported repository-safe `*.data.ts` examples.
+- Recover neutral SHC and EU DGC QR prefix classification from compatibility
+  evidence, with exported repository-safe `*.data.ts` examples.
   Recognition explicitly provides no decoding, verification or authorization.
 
 - Export one repository-safe, telephone-free IPS demo document with all sixteen
@@ -99,8 +117,8 @@
   historical source modules remain compatibility reexports.
 - Remove notification-channel policy from the general root and `builders`
   surfaces. The historical reminder subpath and non-standard `Task.channel`
-  claim remain deprecated compatibility only while product packages migrate;
-  SOS/Vet/UHC own channel choices and dispatch behavior.
+  claim remain deprecated compatibility only while consumers migrate;
+  downstream applications own channel choices and dispatch behavior.
 
 ## 0.6.2 - 2026-09-30
 
@@ -123,7 +141,7 @@
   the frozen shared implementation: outer batch Bundle, one FHIR Bundle
   attachment per Communication, and validated document/batch/collection inner
   Bundles. Reject direct clinical or binary Communication payloads while
-  leaving high-level mutable editors to `sos-sdk-core`.
+  leaving high-level mutable editors downstream.
 - Add a typed Appointment exchange projection that preserves start/end,
   participants, slots and supporting information while keeping an ICS calendar
   file as an independent DocumentReference flat-claim resource.
@@ -254,9 +272,9 @@
   modifying that frozen source repository.
 - Recover strict FHIR primitives, value/search/token utilities, Bundle readers,
   resource search/template types, terminology model types, RelatedPerson and
-  telecom helpers, and DICOMDIR structural types from the retired UHC package.
+  telecom helpers, and DICOMDIR structural types from compatibility evidence.
 - Move cross-sector terminology, Immunization graph/reminder, Group R5 and
-  ResearchStudy R5 contracts that existed only in SOS or Vet data packages.
+  ResearchStudy R5 contracts into their neutral standards-based owner.
 - Require component Observations to use independently indexable graph entries;
   deprecated JSON-array component claims remain read-only compatibility input.
 - Add stable package subpaths for every migrated contract family.
@@ -293,12 +311,12 @@
   JSON repeatable-component encoding, generic component index projection and
   explicit R4/R5 projection boundary. Historical component CSV and `bp-*`
   aliases remain read-only compatibility inputs.
-- Record the reuse/rewrite/retire audit of the original
-  `uhc-fhir-utils-typescript` architecture without adding its obsolete product,
-  transport, SHA-1, DICOM or build dependencies to the neutral package.
+- Record the reuse/rewrite/retire audit of historical compatibility utilities
+  without adding obsolete product, transport, SHA-1, DICOM or build
+  dependencies to the neutral package.
 - Add the neutral contained-resource coding-review contract: canonical imported
   `*-text`, resource-scoped `meta.codingProposals[]`, batch traversal, candidate
-  confirmation and reusable governed fixtures for DataConv, Vet and UHC.
+  confirmation and reusable governed fixtures for downstream consumers.
 - Add channel-neutral FHIR-like vital-sign Observation builders and lossless device-batch normalization while preserving device source without inventing professional attestation.
 - Introduce product-neutral flat-claim resource graphs, parent-owned
   `contained-reference-list`, narrative `language`/`xhtml`, and governed

package/README.md

@@ -2,26 +2,24 @@
 
 FHIR-neutral data contracts for flat claims, governed SearchParameter names,
 resource graphs and explicit R4/R5/R6 projection adapters. This package has no
-network clients and no dependency on GDC, SOS, Vet or UHC packages.
+network clients and no dependency on downstream product packages.
 
 Release order is local-first: local tarball consumers, complete local matrix,
 merge and push `main`, publish bottom-up, install exact registry versions, then
 staging. Never commit `file:`, Git or workspace dependencies.
 
-## Where this package sits
+## Public source history
 
-```text
-fhir-data-utils-ts
-  └─ FHIR SearchParameters, flat-claim graphs and R4/R5/R6 projection rules
-      ↓
-sos-data-utils-ts
-  └─ cross-sector clinical catalogs and shared SOS/Vet/UHC data contracts
-      ├─ vet-data-utils-ts: animal species and veterinary policy
-      └─ uhc-data-utils-ts: human-health policy
+The public repository begins from a clean 2026 source snapshot. The retained
+[`CHANGELOG.md`](CHANGELOG.md) records package releases without republishing
+the former Git push history.
 
-terminology-api-node-ts reads the neutral FHIR and shared SOS contracts.
-It never depends on Vet or UHC product packages.
-```
+## Ownership boundary
+
+This package owns only standards-based FHIR SearchParameters, flat-claim
+graphs, validation and explicit R4/R5/R6 projection rules. Sector terminology,
+product policy, transport, authorization, mutable editors, network clients and
+application workflows belong downstream and are deliberately unnamed here.
 
 FHIR resource graphs use independent entries. A parent links children only
 through `<ResourceType>.contained-reference-list`; children do not carry
@@ -48,8 +46,8 @@ Cross-participant data always uses an outer FHIR batch Bundle containing
 Communication entries. Each Communication carries exactly one
 `application/fhir+json` inner document, batch or collection Bundle; arbitrary
 files are DocumentReference resources inside that Bundle. This package owns
-strict parsing and projection tools; the shared high-level editor/reader belongs
-to `sos-sdk-core`, with cross-sector contracts in `sos-data-utils`. See
+strict parsing and projection tools; mutable editors, transport and
+cross-sector policy belong downstream. See
 [Communication Bundle contract](docs/COMMUNICATION_BUNDLE_CONTRACT.md).
 
 Reservable equipment remains a `Device` actor of its service-specific
@@ -70,10 +68,10 @@ The root export and stable subpaths provide:
 - complete flat-claim catalogs and claim helpers for the resource families
   formerly scattered through `gdc-common-utils-ts`;
 - explicit R4/R5 conversion adapters, including Consent and PractitionerRole;
-- the recovered UHC resource search/template types, terminology model types,
+- resource search/template types, terminology model types,
   RelatedPerson/telecom helpers and type-only DICOMDIR tree contract;
 - cross-sector terminology, Immunization graphs/reminders, and FHIR R5 Group
-  and ResearchStudy contracts previously located only in SOS or Vet packages.
+  and ResearchStudy contracts;
 - native FHIR R5 SubscriptionTopic/Subscription configuration builders,
   official search catalogs and a strict notification-Bundle parser; terminal
   asynchronous job messages remain claims-first Communication resources.
@@ -156,18 +154,13 @@ top-level Observations with a professional attester. Ledger hashing, index
 updates, Digital Twin and research eligibility remain owning-service policy.
 See [Daily vital-sign document lifecycle](docs/VITAL_SIGN_DAILY_DOCUMENT.md).
 
-See [the UHC FHIR utilities migration](docs/UHC_FHIR_UTILS_MIGRATION.md) for the
-reuse/rewrite/retire inventory and the rule for moving frozen contracts without
-changing any `gdc-*` repository.
-
 See [Clinical typed accessor boundary](docs/CLINICAL_TYPED_ACCESSOR_BOUNDARY.md)
 for the exact division between canonical clinical claims/converters here,
-shared SOS multichannel schemas and the mutable Bundle getters/setters exposed
-by runtime SDKs.
+downstream schemas and mutable Bundle getters/setters.
 
 ## Coding review for imported clinical text
 
-DataConv, Vet and UHC share one neutral review contract from
+Coding review uses one neutral contract from
 `fhir-data-utils-ts/coding-review-flat-claims`:
 
 - imported wording is the canonical `<ResourceType>.<code-field>-text` claim;
@@ -209,8 +202,7 @@ packed artifact and installs it in an isolated consumer before publication.
 
 ## Care, emergency and population-alert graphs
 
-The package provides the neutral FHIR foundation for the three SOSChain
-journeys proven first in VetChain/PetChain: Location-linked Encounter care
+The package provides the neutral FHIR foundation for Location-linked Encounter care
 journeys, emergency ServiceRequest plus triage Task, and cohort
 CommunicationRequest against a frozen Group snapshot. See
 [the contract guide](docs/CARE_EMERGENCY_ALERT_CONTRACTS.md). Product policy,

package/dist/builders/immunization-reminders.d.ts

@@ -7,7 +7,7 @@ export declare const ImmunizationReminderTaskValues: Readonly<{
 }>;
 /**
  * @deprecated Compatibility only. Notification-channel policy belongs to the
- * consuming SOS/Vet/UHC data package, not to the general FHIR data package.
+ * consuming downstream package, not to the general FHIR data package.
  */
 export declare const ImmunizationReminderChannels: readonly ["push", "email", "sms", "whatsapp", "telephone"];
 export type ImmunizationReminderChannel = (typeof ImmunizationReminderChannels)[number];

package/dist/builders/immunization-reminders.js

@@ -10,7 +10,7 @@ export const ImmunizationReminderTaskValues = Object.freeze({
 });
 /**
  * @deprecated Compatibility only. Notification-channel policy belongs to the
- * consuming SOS/Vet/UHC data package, not to the general FHIR data package.
+ * consuming downstream package, not to the general FHIR data package.
  */
 export const ImmunizationReminderChannels = Object.freeze([
     'push',

package/dist/claims/communication-request-claims.d.ts

@@ -20,6 +20,8 @@ export declare const CommunicationRequestClaim: Readonly<{
     readonly InformationProvider: "CommunicationRequest.information-provider";
     readonly AuthoredOn: "CommunicationRequest.authored-on";
     readonly Occurrence: "CommunicationRequest.occurrence";
+    readonly OccurrencePeriodStart: "CommunicationRequest.occurrence-period-start";
+    readonly OccurrencePeriodEnd: "CommunicationRequest.occurrence-period-end";
     readonly ReasonCode: "CommunicationRequest.reason-code";
     readonly ReasonReference: "CommunicationRequest.reason-reference";
     readonly PayloadContent: "CommunicationRequest.payload-content";

package/dist/claims/communication-request-claims.js

@@ -19,6 +19,8 @@ export const CommunicationRequestClaim = Object.freeze({
     InformationProvider: 'CommunicationRequest.information-provider',
     AuthoredOn: 'CommunicationRequest.authored-on',
     Occurrence: 'CommunicationRequest.occurrence',
+    OccurrencePeriodStart: 'CommunicationRequest.occurrence-period-start',
+    OccurrencePeriodEnd: 'CommunicationRequest.occurrence-period-end',
     ReasonCode: 'CommunicationRequest.reason-code',
     ReasonReference: 'CommunicationRequest.reason-reference',
     PayloadContent: 'CommunicationRequest.payload-content',
@@ -48,6 +50,8 @@ export const CommunicationRequestClaimSpecs = Object.freeze([
     { key: CommunicationRequestClaim.InformationProvider, meaning: 'Actors expected to provide or review message information.', example: 'PractitionerRole/doctor-1' },
     { key: CommunicationRequestClaim.AuthoredOn, meaning: 'Request authoring time.', example: '2026-09-26T11:00:00Z' },
     { key: CommunicationRequestClaim.Occurrence, meaning: 'Requested delivery time.', example: '2026-09-26T11:30:00Z' },
+    { key: CommunicationRequestClaim.OccurrencePeriodStart, meaning: 'Start of the requested delivery period.', example: '2026-09-26T11:30:00Z' },
+    { key: CommunicationRequestClaim.OccurrencePeriodEnd, meaning: 'End of the requested delivery period.', example: '2026-09-27T11:30:00Z' },
     { key: CommunicationRequestClaim.ReasonCode, meaning: 'Coded reasons for the request.', example: 'http://snomed.info/sct|246205007' },
     { key: CommunicationRequestClaim.ReasonReference, meaning: 'Resource references supporting the request reason.', example: 'Condition/condition-1' },
     { key: CommunicationRequestClaim.PayloadContent, meaning: 'R4 string payload compatibility value.', example: 'Family update ready for review.' },

package/dist/claims/index.d.ts

@@ -35,3 +35,4 @@ export * from './regulated-authorization-claims.js';
 export * from './service-request-claims.js';
 export * from './schedule-slot-claims.js';
 export * from './task-claims.js';
+export * from './us-core-patient-demographics-claims.js';

package/dist/claims/index.js

@@ -35,3 +35,4 @@ export * from './regulated-authorization-claims.js';
 export * from './service-request-claims.js';
 export * from './schedule-slot-claims.js';
 export * from './task-claims.js';
+export * from './us-core-patient-demographics-claims.js';

package/dist/claims/us-core-patient-demographics-claims.d.ts

@@ -0,0 +1,19 @@
+import type { ClaimSpec } from './claim-types.js';
+/** Canonical claims for the optional US Core Patient race and ethnicity extensions. */
+export declare const UsCorePatientDemographicClaim: Readonly<{
+    readonly RaceOmbCategory: "Patient.extension:us-core-race.extension:ombCategory";
+    readonly RaceDetailed: "Patient.extension:us-core-race.extension:detailed";
+    readonly RaceText: "Patient.extension:us-core-race.extension:text";
+    readonly EthnicityOmbCategory: "Patient.extension:us-core-ethnicity.extension:ombCategory";
+    readonly EthnicityDetailed: "Patient.extension:us-core-ethnicity.extension:detailed";
+    readonly EthnicityText: "Patient.extension:us-core-ethnicity.extension:text";
+}>;
+/** Derived claims backed by the two official optional US Core SearchParameters. */
+export declare const UsCorePatientDemographicSearchClaim: Readonly<{
+    readonly Race: "Patient.race";
+    readonly Ethnicity: "Patient.ethnicity";
+}>;
+export type UsCorePatientDemographicClaimKey = typeof UsCorePatientDemographicClaim[keyof typeof UsCorePatientDemographicClaim];
+export type UsCorePatientDemographicSearchClaimKey = typeof UsCorePatientDemographicSearchClaim[keyof typeof UsCorePatientDemographicSearchClaim];
+export declare const UsCorePatientDemographicClaimSpecs: readonly ClaimSpec[];
+export declare const UsCorePatientDemographicSearchClaimSpecs: readonly ClaimSpec[];

package/dist/claims/us-core-patient-demographics-claims.js

@@ -0,0 +1,26 @@
+/** Canonical claims for the optional US Core Patient race and ethnicity extensions. */
+export const UsCorePatientDemographicClaim = Object.freeze({
+    RaceOmbCategory: 'Patient.extension:us-core-race.extension:ombCategory',
+    RaceDetailed: 'Patient.extension:us-core-race.extension:detailed',
+    RaceText: 'Patient.extension:us-core-race.extension:text',
+    EthnicityOmbCategory: 'Patient.extension:us-core-ethnicity.extension:ombCategory',
+    EthnicityDetailed: 'Patient.extension:us-core-ethnicity.extension:detailed',
+    EthnicityText: 'Patient.extension:us-core-ethnicity.extension:text',
+});
+/** Derived claims backed by the two official optional US Core SearchParameters. */
+export const UsCorePatientDemographicSearchClaim = Object.freeze({
+    Race: 'Patient.race',
+    Ethnicity: 'Patient.ethnicity',
+});
+export const UsCorePatientDemographicClaimSpecs = Object.freeze([
+    { key: UsCorePatientDemographicClaim.RaceOmbCategory, meaning: 'Comma-separated OMB race Coding tokens.', example: 'urn:oid:2.16.840.1.113883.6.238|2028-9' },
+    { key: UsCorePatientDemographicClaim.RaceDetailed, meaning: 'Comma-separated detailed race Coding tokens.', example: 'urn:oid:2.16.840.1.113883.6.238|2036-2' },
+    { key: UsCorePatientDemographicClaim.RaceText, meaning: 'Patient-supplied race text required when the US Core race extension is present.', example: 'Asian' },
+    { key: UsCorePatientDemographicClaim.EthnicityOmbCategory, meaning: 'OMB ethnicity Coding token.', example: 'urn:oid:2.16.840.1.113883.6.238|2135-2' },
+    { key: UsCorePatientDemographicClaim.EthnicityDetailed, meaning: 'Comma-separated detailed ethnicity Coding tokens.', example: 'urn:oid:2.16.840.1.113883.6.238|2148-5' },
+    { key: UsCorePatientDemographicClaim.EthnicityText, meaning: 'Patient-supplied ethnicity text required when the US Core ethnicity extension is present.', example: 'Hispanic or Latino' },
+]);
+export const UsCorePatientDemographicSearchClaimSpecs = Object.freeze([
+    { key: UsCorePatientDemographicSearchClaim.Race, meaning: 'Derived token list for the official optional US Core race SearchParameter.', example: 'urn:oid:2.16.840.1.113883.6.238|2028-9' },
+    { key: UsCorePatientDemographicSearchClaim.Ethnicity, meaning: 'Derived token list for the official optional US Core ethnicity SearchParameter.', example: 'urn:oid:2.16.840.1.113883.6.238|2135-2' },
+]);

package/dist/clinical-terminology.d.ts

@@ -18,7 +18,7 @@ export declare const ClinicalTerminologySourceScopes: Readonly<{
     readonly AtcVet: "ATCVET";
 }>;
 export type ClinicalTerminologySourceScope = typeof ClinicalTerminologySourceScopes[keyof typeof ClinicalTerminologySourceScopes];
-/** Product-neutral terminology candidate returned to SOS, Vet or UHC channels. */
+/** Product-neutral terminology candidate returned to downstream channels. */
 export type ClinicalTerminologyCandidate = Readonly<{
     /** Governed source-scope identifier returned by the deployment capability. */
     source: string;

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

@@ -18,7 +18,7 @@ export function communicationRequestFlatToFhirR4(claims) {
         requester: claims[CommunicationRequestClaim.Requester] ? { reference: claims[CommunicationRequestClaim.Requester] } : undefined,
         sender: firstReference(claims[CommunicationRequestClaim.InformationProvider]),
         recipient: referenceCsv(claims[CommunicationRequestClaim.Recipient]), authoredOn: claims[CommunicationRequestClaim.AuthoredOn],
-        occurrenceDateTime: claims[CommunicationRequestClaim.Occurrence],
+        ...occurrenceToFhir(claims),
         reasonCode: claims[CommunicationRequestClaim.ReasonCode] ? [{ coding: codingListFromCsv(claims[CommunicationRequestClaim.ReasonCode]) }] : undefined,
         reasonReference: referenceCsv(claims[CommunicationRequestClaim.ReasonReference]),
         payload: payloadR4(claims),
@@ -44,7 +44,8 @@ export function communicationRequestFhirR4ToFlat(resource) {
         [CommunicationRequestClaim.Requester]: referenceToValue(resource.requester),
         [CommunicationRequestClaim.InformationProvider]: referenceToValue(resource.sender),
         [CommunicationRequestClaim.Recipient]: referenceListToCsv(resource.recipient),
-        [CommunicationRequestClaim.AuthoredOn]: resource.authoredOn, [CommunicationRequestClaim.Occurrence]: resource.occurrenceDateTime,
+        [CommunicationRequestClaim.AuthoredOn]: resource.authoredOn,
+        ...occurrenceToFlat(resource),
         [CommunicationRequestClaim.ReasonCode]: codingListToCsv(resource.reasonCode?.flatMap(value => value.coding ?? [])),
         [CommunicationRequestClaim.ReasonReference]: referenceListToCsv(resource.reasonReference),
         ...payloadToFlat(resource),
@@ -82,7 +83,7 @@ function communicationRequestFlatToFhirR5Resource(claims) {
         requester: claims[CommunicationRequestClaim.Requester] ? { reference: claims[CommunicationRequestClaim.Requester] } : undefined,
         recipient: referenceCsv(claims[CommunicationRequestClaim.Recipient]),
         informationProvider: referenceCsv(claims[CommunicationRequestClaim.InformationProvider]),
-        authoredOn: claims[CommunicationRequestClaim.AuthoredOn], occurrenceDateTime: claims[CommunicationRequestClaim.Occurrence],
+        authoredOn: claims[CommunicationRequestClaim.AuthoredOn], ...occurrenceToFhir(claims),
         reason: reasonsR5(claims), payload: payloadR5(claims), note: annotation(claims[CommunicationRequestClaim.Note]),
     };
 }
@@ -107,7 +108,7 @@ function communicationRequestFhirR5ResourceToFlat(resource) {
         [CommunicationRequestClaim.Recipient]: referenceListToCsv(resource.recipient),
         [CommunicationRequestClaim.InformationProvider]: referenceListToCsv(resource.informationProvider),
         [CommunicationRequestClaim.AuthoredOn]: resource.authoredOn,
-        [CommunicationRequestClaim.Occurrence]: resource.occurrenceDateTime,
+        ...occurrenceToFlat(resource),
         [CommunicationRequestClaim.ReasonCode]: codingListToCsv(reasons?.flatMap(value => value.concept?.coding ?? [])),
         [CommunicationRequestClaim.ReasonReference]: reasons?.map(value => value.reference?.reference).filter((value) => Boolean(value)).join(',') || undefined,
         ...payloadToFlat(resource), [CommunicationRequestClaim.Note]: annotationText(resource.note),
@@ -134,6 +135,24 @@ function optionalBoolean(value) {
 }
 function annotation(value) { return value ? [{ text: value }] : undefined; }
 function annotationText(value) { return value?.[0]?.text; }
+function occurrenceToFhir(claims) {
+    const occurrenceDateTime = claims[CommunicationRequestClaim.Occurrence];
+    const start = claims[CommunicationRequestClaim.OccurrencePeriodStart];
+    const end = claims[CommunicationRequestClaim.OccurrencePeriodEnd];
+    if (occurrenceDateTime && (start || end))
+        throw new TypeError('communication_request_occurrence_choice_invalid');
+    return occurrenceDateTime ? { occurrenceDateTime } : start || end ? { occurrencePeriod: compact({ start, end }) } : {};
+}
+function occurrenceToFlat(resource) {
+    const period = resource.occurrencePeriod;
+    if (resource.occurrenceDateTime && period)
+        throw new TypeError('communication_request_occurrence_choice_invalid');
+    return compact({
+        [CommunicationRequestClaim.Occurrence]: resource.occurrenceDateTime,
+        [CommunicationRequestClaim.OccurrencePeriodStart]: period?.start,
+        [CommunicationRequestClaim.OccurrencePeriodEnd]: period?.end,
+    });
+}
 function payloadR4(claims) {
     if (claims[CommunicationRequestClaim.PayloadReference])
         return [{ contentReference: { reference: claims[CommunicationRequestClaim.PayloadReference] } }];

package/dist/converters/convert-us-core-patient-demographics.d.ts

@@ -0,0 +1,29 @@
+import type { UsCorePatientDemographicSearchClaimKey } from '../claims/us-core-patient-demographics-claims.js';
+import type { FhirCoding, FhirResource } from '../fhir-types.js';
+import type { FlatClaims } from './convert-shared.js';
+export declare const UsCorePatientRaceExtensionUrl = "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race";
+export declare const UsCorePatientEthnicityExtensionUrl = "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity";
+export type UsCorePatientSearchParameterDefinition = Readonly<{
+    canonicalUrl: string;
+    code: 'race' | 'ethnicity';
+    base: 'Patient';
+    type: 'token';
+    expression: string;
+    claim: UsCorePatientDemographicSearchClaimKey;
+    sourceClaims: readonly string[];
+    multipleOr: true;
+    multipleAnd: true;
+}>;
+export declare const UsCorePatientDemographicSearchParameters: readonly UsCorePatientSearchParameterDefinition[];
+export type FhirExtension = Readonly<{
+    url: string;
+    extension?: readonly FhirExtension[];
+    valueCoding?: FhirCoding;
+    valueString?: string;
+}>;
+/** Materializes only the optional US Core extensions enabled by canonical claims. */
+export declare function usCorePatientDemographicsFlatToFhirR4Extensions(claims: FlatClaims): readonly FhirExtension[];
+/** Reads the two governed US Core extensions without treating them as universal demographics. */
+export declare function usCorePatientDemographicsFhirR4ToFlat(resource: FhirResource): FlatClaims;
+/** Derives the official token-search claims; callers never submit these independently. */
+export declare function deriveUsCorePatientDemographicSearchClaims(claims: FlatClaims): FlatClaims;

package/dist/converters/convert-us-core-patient-demographics.js

@@ -0,0 +1,114 @@
+import { UsCorePatientDemographicClaim, UsCorePatientDemographicSearchClaim } from '../claims/us-core-patient-demographics-claims.js';
+import { codingListFromCsv, codingListToCsv } from './convert-shared.js';
+export const UsCorePatientRaceExtensionUrl = 'http://hl7.org/fhir/us/core/StructureDefinition/us-core-race';
+export const UsCorePatientEthnicityExtensionUrl = 'http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity';
+export const UsCorePatientDemographicSearchParameters = Object.freeze([
+    Object.freeze({
+        canonicalUrl: 'http://hl7.org/fhir/us/core/SearchParameter/us-core-race',
+        code: 'race', base: 'Patient', type: 'token',
+        expression: `Patient.extension.where(url = '${UsCorePatientRaceExtensionUrl}').extension.value.code`,
+        claim: UsCorePatientDemographicSearchClaim.Race,
+        sourceClaims: Object.freeze([UsCorePatientDemographicClaim.RaceOmbCategory, UsCorePatientDemographicClaim.RaceDetailed]),
+        multipleOr: true, multipleAnd: true,
+    }),
+    Object.freeze({
+        canonicalUrl: 'http://hl7.org/fhir/us/core/SearchParameter/us-core-ethnicity',
+        code: 'ethnicity', base: 'Patient', type: 'token',
+        expression: `Patient.extension.where(url = '${UsCorePatientEthnicityExtensionUrl}').extension.value.code`,
+        claim: UsCorePatientDemographicSearchClaim.Ethnicity,
+        sourceClaims: Object.freeze([UsCorePatientDemographicClaim.EthnicityOmbCategory, UsCorePatientDemographicClaim.EthnicityDetailed]),
+        multipleOr: true, multipleAnd: true,
+    }),
+]);
+/** Materializes only the optional US Core extensions enabled by canonical claims. */
+export function usCorePatientDemographicsFlatToFhirR4Extensions(claims) {
+    return [
+        buildExtension({
+            url: UsCorePatientRaceExtensionUrl,
+            omb: claims[UsCorePatientDemographicClaim.RaceOmbCategory],
+            detailed: claims[UsCorePatientDemographicClaim.RaceDetailed],
+            text: claims[UsCorePatientDemographicClaim.RaceText],
+            textError: 'us_core_patient_race_text_required',
+        }),
+        buildExtension({
+            url: UsCorePatientEthnicityExtensionUrl,
+            omb: claims[UsCorePatientDemographicClaim.EthnicityOmbCategory],
+            detailed: claims[UsCorePatientDemographicClaim.EthnicityDetailed],
+            text: claims[UsCorePatientDemographicClaim.EthnicityText],
+            textError: 'us_core_patient_ethnicity_text_required',
+            singleOmbCategory: true,
+        }),
+    ].filter((extension) => Boolean(extension));
+}
+/** Reads the two governed US Core extensions without treating them as universal demographics. */
+export function usCorePatientDemographicsFhirR4ToFlat(resource) {
+    if (resource.resourceType !== 'Patient')
+        throw new TypeError('us_core_patient_resource_required');
+    const extensions = Array.isArray(resource.extension) ? resource.extension : [];
+    return {
+        ...readExtension(extensions, UsCorePatientRaceExtensionUrl, {
+            omb: UsCorePatientDemographicClaim.RaceOmbCategory,
+            detailed: UsCorePatientDemographicClaim.RaceDetailed,
+            text: UsCorePatientDemographicClaim.RaceText,
+            textError: 'us_core_patient_race_text_required',
+        }),
+        ...readExtension(extensions, UsCorePatientEthnicityExtensionUrl, {
+            omb: UsCorePatientDemographicClaim.EthnicityOmbCategory,
+            detailed: UsCorePatientDemographicClaim.EthnicityDetailed,
+            text: UsCorePatientDemographicClaim.EthnicityText,
+            textError: 'us_core_patient_ethnicity_text_required',
+            singleOmbCategory: true,
+        }),
+    };
+}
+/** Derives the official token-search claims; callers never submit these independently. */
+export function deriveUsCorePatientDemographicSearchClaims(claims) {
+    return {
+        [UsCorePatientDemographicSearchClaim.Race]: mergeTokenClaims(claims[UsCorePatientDemographicClaim.RaceOmbCategory], claims[UsCorePatientDemographicClaim.RaceDetailed]),
+        [UsCorePatientDemographicSearchClaim.Ethnicity]: mergeTokenClaims(claims[UsCorePatientDemographicClaim.EthnicityOmbCategory], claims[UsCorePatientDemographicClaim.EthnicityDetailed]),
+    };
+}
+function buildExtension(input) {
+    const omb = codingListFromCsv(input.omb) ?? [];
+    const detailed = codingListFromCsv(input.detailed) ?? [];
+    const text = String(input.text || '').trim();
+    if (!omb.length && !detailed.length && !text)
+        return undefined;
+    if (!text)
+        throw new TypeError(input.textError);
+    if (input.singleOmbCategory && omb.length > 1)
+        throw new TypeError('us_core_patient_ethnicity_omb_category_cardinality');
+    return Object.freeze({
+        url: input.url,
+        extension: Object.freeze([
+            ...omb.map((valueCoding) => Object.freeze({ url: 'ombCategory', valueCoding })),
+            ...detailed.map((valueCoding) => Object.freeze({ url: 'detailed', valueCoding })),
+            Object.freeze({ url: 'text', valueString: text }),
+        ]),
+    });
+}
+function readExtension(extensions, url, keys) {
+    const matches = extensions.filter((extension) => extension.url === url);
+    if (!matches.length)
+        return {};
+    if (matches.length > 1)
+        throw new TypeError('us_core_patient_extension_cardinality');
+    const children = matches[0]?.extension ?? [];
+    const omb = children.filter((extension) => extension.url === 'ombCategory' && extension.valueCoding).map((extension) => extension.valueCoding);
+    const detailed = children.filter((extension) => extension.url === 'detailed' && extension.valueCoding).map((extension) => extension.valueCoding);
+    const texts = children.filter((extension) => extension.url === 'text' && extension.valueString).map((extension) => extension.valueString.trim()).filter(Boolean);
+    if (texts.length !== 1)
+        throw new TypeError(keys.textError);
+    if (keys.singleOmbCategory && omb.length > 1)
+        throw new TypeError('us_core_patient_ethnicity_omb_category_cardinality');
+    return {
+        [keys.omb]: codingListToCsv(omb),
+        [keys.detailed]: codingListToCsv(detailed),
+        [keys.text]: texts[0],
+    };
+}
+function mergeTokenClaims(...values) {
+    const tokens = values.flatMap((value) => String(value || '').split(',')).map((value) => value.trim()).filter(Boolean);
+    const unique = [...new Set(tokens)];
+    return unique.length ? unique.join(',') : undefined;
+}

package/dist/converters/index.d.ts

@@ -32,3 +32,4 @@ export * from './convert-related-person.js';
 export * from './convert-service-request.js';
 export * from './convert-schedule-slot.js';
 export * from './materialize-claims-first-resource.js';
+export * from './convert-us-core-patient-demographics.js';

package/dist/converters/index.js

@@ -32,3 +32,4 @@ export * from './convert-related-person.js';
 export * from './convert-service-request.js';
 export * from './convert-schedule-slot.js';
 export * from './materialize-claims-first-resource.js';
+export * from './convert-us-core-patient-demographics.js';

package/dist/data/communication-request-form-schema.data.d.ts

@@ -7,13 +7,17 @@ export type CommunicationRequestFormData = Readonly<{
     status: typeof CommunicationRequestStatuses[number];
     intent: typeof CommunicationRequestIntents[number];
     priority?: typeof CommunicationRequestPriorities[number];
+    category?: string;
     subject: string;
+    about?: readonly string[];
     encounter?: string;
     requester: string;
     recipients: readonly string[];
     informationProviders?: readonly string[];
     authoredOn?: string;
     occurrence?: string;
+    occurrencePeriodStart?: string;
+    occurrencePeriodEnd?: string;
     payloadReference?: string;
     payloadAttachmentContentType?: string;
     payloadAttachmentData?: string;
@@ -45,10 +49,22 @@ export declare const FHIR_COMMUNICATION_REQUEST_FORM_SCHEMA: Readonly<{
             type: "string";
             enum: readonly ["routine", "urgent", "asap", "stat"];
         }>;
+        category: Readonly<{
+            type: "string";
+            pattern: "^https?://[^|,]+\\|[^|,]+$";
+        }>;
         subject: Readonly<{
             type: "string";
             pattern: "^[A-Za-z][A-Za-z0-9]+/[A-Za-z0-9.-]{1,64}$";
         }>;
+        about: Readonly<{
+            type: "array";
+            uniqueItems: true;
+            items: Readonly<{
+                type: "string";
+                pattern: "^[A-Za-z][A-Za-z0-9]+/[A-Za-z0-9.-]{1,64}$";
+            }>;
+        }>;
         encounter: Readonly<{
             type: "string";
             pattern: "^[A-Za-z][A-Za-z0-9]+/[A-Za-z0-9.-]{1,64}$";
@@ -82,6 +98,14 @@ export declare const FHIR_COMMUNICATION_REQUEST_FORM_SCHEMA: Readonly<{
             type: "string";
             format: "date-time";
         }>;
+        occurrencePeriodStart: Readonly<{
+            type: "string";
+            format: "date-time";
+        }>;
+        occurrencePeriodEnd: Readonly<{
+            type: "string";
+            format: "date-time";
+        }>;
         payloadReference: Readonly<{
             type: "string";
             pattern: "^[A-Za-z][A-Za-z0-9]+/[A-Za-z0-9.-]{1,64}$";

package/dist/data/communication-request-form-schema.data.js

@@ -20,10 +20,14 @@ export const FHIR_COMMUNICATION_REQUEST_FORM_SCHEMA = Object.freeze({
         status: Object.freeze({ type: 'string', enum: CommunicationRequestStatuses }),
         intent: Object.freeze({ type: 'string', enum: CommunicationRequestIntents }),
         priority: Object.freeze({ type: 'string', enum: CommunicationRequestPriorities }),
-        subject: referenceSchema(), encounter: referenceSchema(), requester: referenceSchema(),
+        category: codingSchema(),
+        subject: referenceSchema(),
+        about: Object.freeze({ type: 'array', uniqueItems: true, items: referenceSchema() }),
+        encounter: referenceSchema(), requester: referenceSchema(),
         recipients: Object.freeze({ type: 'array', minItems: 1, uniqueItems: true, items: referenceSchema() }),
         informationProviders: Object.freeze({ type: 'array', uniqueItems: true, items: referenceSchema() }),
-        authoredOn: dateTimeSchema(), occurrence: dateTimeSchema(), payloadReference: referenceSchema(),
+        authoredOn: dateTimeSchema(), occurrence: dateTimeSchema(),
+        occurrencePeriodStart: dateTimeSchema(), occurrencePeriodEnd: dateTimeSchema(), payloadReference: referenceSchema(),
         payloadAttachmentContentType: Object.freeze({ type: 'string', minLength: 1 }),
         payloadAttachmentData: Object.freeze({ type: 'string', minLength: 1, contentEncoding: 'base64' }),
         payloadAttachmentTitle: Object.freeze({ type: 'string', minLength: 1 }),
@@ -38,21 +42,34 @@ export function communicationRequestFormDataToFlatClaims(input) {
     const recipients = references(input.recipients, 'communication_request_recipient_required');
     const providers = input.informationProviders?.length
         ? references(input.informationProviders, 'communication_request_information_provider_invalid') : undefined;
+    const about = input.about?.length ? references(input.about, 'communication_request_about_invalid') : undefined;
     if (input.payloadAttachmentData && !input.payloadAttachmentContentType) {
         throw new TypeError('communication_request_attachment_content_type_required');
     }
+    const occurrence = dateTime(input.occurrence);
+    const occurrencePeriodStart = dateTime(input.occurrencePeriodStart);
+    const occurrencePeriodEnd = dateTime(input.occurrencePeriodEnd);
+    if (occurrence && (occurrencePeriodStart || occurrencePeriodEnd))
+        throw new TypeError('communication_request_occurrence_choice_invalid');
+    if (occurrencePeriodStart && occurrencePeriodEnd && Date.parse(occurrencePeriodEnd) <= Date.parse(occurrencePeriodStart)) {
+        throw new TypeError('communication_request_occurrence_period_invalid');
+    }
     return compact({
         [CommunicationRequestClaim.Identifier]: optional(input.identifier),
         [CommunicationRequestClaim.Status]: input.status,
         [CommunicationRequestClaim.Intent]: input.intent,
         [CommunicationRequestClaim.Priority]: optional(input.priority),
+        [CommunicationRequestClaim.Category]: coding(input.category),
         [CommunicationRequestClaim.Subject]: reference(input.subject, 'communication_request_subject_invalid'),
+        [CommunicationRequestClaim.About]: about?.join(','),
         [CommunicationRequestClaim.Encounter]: input.encounter ? reference(input.encounter, 'communication_request_encounter_invalid') : undefined,
         [CommunicationRequestClaim.Requester]: reference(input.requester, 'communication_request_requester_invalid'),
         [CommunicationRequestClaim.Recipient]: recipients.join(','),
         [CommunicationRequestClaim.InformationProvider]: providers?.join(','),
         [CommunicationRequestClaim.AuthoredOn]: dateTime(input.authoredOn),
-        [CommunicationRequestClaim.Occurrence]: dateTime(input.occurrence),
+        [CommunicationRequestClaim.Occurrence]: occurrence,
+        [CommunicationRequestClaim.OccurrencePeriodStart]: occurrencePeriodStart,
+        [CommunicationRequestClaim.OccurrencePeriodEnd]: occurrencePeriodEnd,
         [CommunicationRequestClaim.PayloadReference]: input.payloadReference ? reference(input.payloadReference, 'communication_request_payload_reference_invalid') : undefined,
         [CommunicationRequestClaim.PayloadAttachmentContentType]: optional(input.payloadAttachmentContentType),
         [CommunicationRequestClaim.PayloadAttachmentData]: optional(input.payloadAttachmentData),
@@ -64,10 +81,14 @@ export function communicationRequestFlatClaimsToFormData(claims) {
     return compact({
         identifier: claims[CommunicationRequestClaim.Identifier], status: claims[CommunicationRequestClaim.Status],
         intent: claims[CommunicationRequestClaim.Intent], priority: claims[CommunicationRequestClaim.Priority],
-        subject: claims[CommunicationRequestClaim.Subject], encounter: claims[CommunicationRequestClaim.Encounter],
+        category: claims[CommunicationRequestClaim.Category],
+        subject: claims[CommunicationRequestClaim.Subject], about: splitOptional(claims[CommunicationRequestClaim.About]),
+        encounter: claims[CommunicationRequestClaim.Encounter],
         requester: claims[CommunicationRequestClaim.Requester], recipients: split(claims[CommunicationRequestClaim.Recipient]),
         informationProviders: splitOptional(claims[CommunicationRequestClaim.InformationProvider]),
         authoredOn: claims[CommunicationRequestClaim.AuthoredOn], occurrence: claims[CommunicationRequestClaim.Occurrence],
+        occurrencePeriodStart: claims[CommunicationRequestClaim.OccurrencePeriodStart],
+        occurrencePeriodEnd: claims[CommunicationRequestClaim.OccurrencePeriodEnd],
         payloadReference: claims[CommunicationRequestClaim.PayloadReference],
         payloadAttachmentContentType: claims[CommunicationRequestClaim.PayloadAttachmentContentType],
         payloadAttachmentData: claims[CommunicationRequestClaim.PayloadAttachmentData],
@@ -75,12 +96,15 @@ export function communicationRequestFlatClaimsToFormData(claims) {
     });
 }
 function referenceSchema() { return Object.freeze({ type: 'string', pattern: '^[A-Za-z][A-Za-z0-9]+/[A-Za-z0-9.-]{1,64}$' }); }
+function codingSchema() { return Object.freeze({ type: 'string', pattern: '^https?://[^|,]+\\|[^|,]+$' }); }
 function dateTimeSchema() { return Object.freeze({ type: 'string', format: 'date-time' }); }
 function optional(value) { const text = String(value ?? '').trim(); return text || undefined; }
 function dateTime(value) { const text = optional(value); if (text && Number.isNaN(Date.parse(text)))
     throw new TypeError('communication_request_datetime_invalid'); return text; }
 function reference(value, error) { const text = optional(value); if (!text || !/^[A-Za-z][A-Za-z0-9]+\/[A-Za-z0-9.-]{1,64}$/u.test(text))
     throw new TypeError(error); return text; }
+function coding(value) { const text = optional(value); if (text && !/^https?:\/\/[^|,]+\|[^|,]+$/u.test(text))
+    throw new TypeError('communication_request_category_invalid'); return text; }
 function references(values, error) { if (!Array.isArray(values) || !values.length)
     throw new TypeError(error); const result = [...new Set(values.map(value => reference(value, error)))]; if (result.length !== values.length)
     throw new TypeError(error); return result; }

package/dist/fhir-search-parameters.d.ts

@@ -8,7 +8,7 @@ export type FhirSearchParameter = Readonly<{
     system?: string;
     unit?: string;
 }>;
-/** Parses one typed FHIR query value without the lossy integer coercion of the retired UHC helper. */
+/** Parses one typed FHIR query value without lossy integer coercion. */
 export declare function parseFhirSearchParameter(input: Readonly<{
     name: string;
     type: FhirSearchParameterType;

package/dist/fhir-search-parameters.js

@@ -1,5 +1,5 @@
 const PREFIX = /^(eq|ne|gt|lt|ge|le|sa|eb|ap)/;
-/** Parses one typed FHIR query value without the lossy integer coercion of the retired UHC helper. */
+/** Parses one typed FHIR query value without lossy integer coercion. */
 export function parseFhirSearchParameter(input) {
     const name = required(input.name, 'fhir_search_name_required');
     const raw = required(input.value, 'fhir_search_value_required');

package/dist/imaging-types.d.ts

@@ -1,4 +1,4 @@
-/** Type-only DICOMDIR tree contract recovered from the retired UHC package. */
+/** Type-only DICOMDIR tree contract. */
 export interface DicomDirectoryNode {
     id: string;
     uid: string;

package/dist/search-models/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Resource-specific search models recovered from the original UHC package.
+ * Resource-specific FHIR search models.
  * Runtime parsing and serialization use `fhir-search-parameters`; these are
  * compile-time compatibility surfaces, not a second query implementation.
  */

package/dist/search-models/index.js

@@ -1,5 +1,5 @@
 /**
- * Resource-specific search models recovered from the original UHC package.
+ * Resource-specific FHIR search models.
  * Runtime parsing and serialization use `fhir-search-parameters`; these are
  * compile-time compatibility surfaces, not a second query implementation.
  */

package/docs/CARE_EMERGENCY_ALERT_CONTRACTS.md

@@ -1,7 +1,7 @@
 # Care, emergency and population-alert FHIR contracts
 
-This package owns only the product-neutral FHIR representation used by the
-three SOSChain journeys that are first proven in VetChain and PetChain.
+This package owns only the product-neutral FHIR representation used by three
+care and emergency journeys.
 Authorization, controller discovery, encryption, transport, storage and UI
 policy remain in their owning product or service layers.
 

package/docs/CLINICAL_TYPED_ACCESSOR_BOUNDARY.md

@@ -24,19 +24,14 @@ The layer split is:
 fhir-data-utils-ts
   canonical claims + R4/R5/R6 import/export
         ↓
-sos-data-utils-ts
-  product-neutral multichannel field schemas
-        ↓
-sos-sdk-core-ts / sos-sdk-node-ts
-  shared orchestration and runtime adapters
-        ↓
-vet-* / uhc-*
-  product forms, portal editors and telephone/chat dialogue
+downstream libraries
+  multichannel schemas, mutable editors, orchestration and product policy
 ```
 
-When Vet or UHC adds a visual, chat or telephone editor for one of these
-fields, it must consume the canonical claim key from this package. It must not
-maintain a second literal, converter or incompatible getter/setter model.
+When a downstream application adds a visual, chat or telephone editor for one
+of these fields, it must consume the canonical claim key from this package. It
+must not maintain a second literal, converter or incompatible getter/setter
+model.
 
 The mutable GDC Bundle API remains documented separately in
 [`gdc-common-utils-ts`](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/docs/101-CLINICAL-ENTRY-GETTERS-SETTERS.md)

package/docs/COMMUNICATION_BUNDLE_CONTRACT.md

@@ -1,9 +1,9 @@
 # Communication Bundle contract
 
 Every cross-participant clinical or administrative exchange uses the same
-two-level FHIR envelope. This is the portable contract for Vet, UHC and
-SOSChain channels; HTTP, DIDComm, encryption and recipient resolution remain
-in their owning SDK or service.
+two-level FHIR envelope. This is the portable contract for downstream
+channels; HTTP, DIDComm, encryption and recipient resolution remain in their
+owning library or service.
 
 ```text
 outer Bundle (type=batch)
@@ -45,10 +45,9 @@ The validator fails closed when the outer resource is not a batch Bundle, an out
 batch entry lacks its request, the Communication has anything other than one
 FHIR Bundle attachment, or the inner Bundle violates its declared type.
 
-`sos-sdk-core` owns the high-level Bundle and Communication editor/reader used
-by SOS, Vet and UHC. `sos-data-utils` owns its cross-sector input contracts and
-fixtures. The historical `gdc-*` editors remain compatibility surfaces until
-their consumers migrate; this package neither imports nor wraps them.
+Downstream libraries own high-level Bundle and Communication editors/readers,
+cross-sector input contracts, fixtures, transport and product policy. This
+package neither imports nor wraps those consumer surfaces.
 
 At the GW persistence boundary, the validated native resources are projected
 to independent `resource.meta.claims` rows. Direct flat-claim CRUD is an

package/package.json

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

package/docs/UHC_FHIR_UTILS_MIGRATION.md

@@ -1,181 +0,0 @@
-# UHC FHIR utilities migration
-
-`uhc-fhir-utils-typescript` is an archaeological source, not a dependency of
-this package. Its useful behavior must be recovered behind neutral, typed and
-version-explicit contracts. Its product branding, obsolete security choices
-and transport assumptions must not be copied.
-
-The wider historical lineage began with early helpers in
-`uhc-helpers-typescript`, was then split and improved across
-`uhc-common-models-typescript`, `uhc-common-utils-typescript`,
-`data-utils-typescript` and the crypto utilities, and later contributed to
-`gdc-common-utils-ts`. For SHC and DGC, the later split packages are the
-preferred behavioural and type evidence; the early helper remains UI-flow
-evidence only.
-
-## Migration rules
-
-1. Add the smallest failing contract test here before porting behavior.
-2. Use official FHIR R4/R5/R6 structures at import/export boundaries and flat
-   claims as the version-neutral representation between those boundaries.
-3. Copy no raw claim, terminology, identifier or profile literal into a
-   consumer. Define it once in its owning neutral or sector data package.
-4. Preserve historical inputs with explicit read adapters. New writers emit
-   only the current canonical representation.
-5. Do not change `gdc-*` while those repositories are frozen. They are
-   read-only compatibility evidence until every consumer uses this package.
-
-## Reuse, rewrite or retire
-
-| Old area | Decision | Current destination or gate |
-| --- | --- | --- |
-| `Bundle` and `Composition` traversal | Rewrite from tests | Neutral graph and explicit R4/R5/R6 adapters; preserve author, attester and section boundaries |
-| `gdc-common-utils-ts` Communication attached-Bundle editor/reader | Preserve as read-only migration evidence | Neutral validation/projection tools live here; the replacement high-level editor/reader belongs to `sos-sdk-core`, with shared input contracts in `sos-data-utils` |
-| `CodeableConcept`, `Identifier`, `Reference`, `Quantity` | Rewrite and reuse behavior | Small typed value modules with round-trip tests |
-| `Observation` and resource parameter models | Rewrite | Canonical claim catalogs plus version-specific projection adapters |
-| `Parameters` conversion | Rewrite | A typed FHIR Parameters module; never a transport-specific envelope |
-| Anonymization field inventory | Test input only | A separately reviewed policy contract; old field lists do not become policy automatically |
-| ATC, LOINC, SNOMED and EMA JSON | Validate before reuse | Terminology service fixtures, never authoritative embedded catalogs |
-| DICOM parsing | Extract later | Separate imaging package; do not add `dicom-parser` to the neutral core |
-| ImagingStudy metadata | Rewrite | Neutral flat claims and R4 projection for subject, encounter, modality, procedure and protected endpoint references; DICOM bytes remain outside |
-| SHA-1 attachment hashing | Retire | No compatibility writer; historical read/verification belongs in a versioned adapter |
-| `MessageHeader` transport conventions | Retire | Transport is outside the FHIR data contract |
-| UHC-branded templates and defaults | Retire or move downstream | Product policy belongs in UHC packages, not here |
-| Babel/Yarn/Jest build plumbing and broad `any` models | Retire | Node 24, TypeScript strict mode and `node:test` |
-
-## Completed source inventory
-
-| Source | Migrated here | Deliberately remains outside |
-| --- | --- | --- |
-| `gdc-common-utils-ts` interoperable claims | All product-neutral claim catalogs, specs and claim helpers, including Consent and the complete SOS Task surface | Schema.org/Gaia-X mapping and runtime policy |
-| `gdc-common-utils-ts` converters | Every product-neutral R4/R5 converter present there; Observation component writing was corrected to use a resource graph | Network, persistence and authorization orchestration |
-| `uhc-fhir-utils-typescript` models | ATC/FHIR/LOINC/SNOMED model types, all resource search parameter enums and template interfaces, strict replacement FHIR primitives | Embedded terminology JSON is not authoritative data |
-| `uhc-fhir-utils-typescript` helpers | Coding/token, Identifier, Reference, Quantity, telecom, RelatedPerson search projection and non-mutating Bundle traversal/classification/reference lookup | Message transport, SHA-1 writers, COVID-era product presets and mutation-heavy manager facades |
-| Later UHC data/common packages | SHC and EU DGC QR prefix classification plus repository-safe examples | Signature verification, issuer trust, credential import and authorization remain separate future contracts |
-| `uhc-fhir-utils-typescript` imaging | DICOMDIR structural types only | Byte parsing and pixel extraction require a separately versioned imaging package |
-| `sos-data-utils-ts` | Cross-sector terminology contract and fixtures, Immunization graph and reminder planning | SOS authorization, repository and emergency policy |
-| `vet-data-utils-ts` | Product-neutral FHIR R5 Group and ResearchStudy contracts/search projections | Animal identity, veterinary sections, species, insurance, payment and other Vet policy |
-| Provider catalogs | R4 HealthcareService claims/converter, geocoded Location claims, one-department professional Group normalization and reviewed C80-to-LOINC candidate mappings | Schema.org images/logo storage, marketplace sector policy, endpoint authorization and communication routing |
-| UHC/Vet SDKs | No transport client was copied | SMART clients, Oracle clients, BFF calls and product workflows remain SDK responsibilities |
-
-The frozen `gdc-*` implementation remains compatibility evidence. New Vet,
-UHC and SOS code uses the replacement high-level API in `sos-sdk-core`, which
-composes the neutral tools exported here. Neither shared replacement package
-imports `gdc-*`. DIDComm wrapping, post-quantum encryption, endpoint selection
-and delivery retries remain in the SDK/service layer.
-
-The migration surface is executable rather than documentary only:
-
-- every migrated claim family has a named catalog and shared list helpers;
-- every migrated product-neutral converter participates in the converter
-  round-trip matrix, with rich optional-field fixtures for complex resources;
-- Encounter retains its originating Appointment and ImagingStudy retains
-  searchable metadata without embedding DICOM object bytes;
-- FHIR primitives, typed searches, Bundle traversal and fallback conversion
-  have strict success and rejection tests;
-- Communication exchange is authored and read only as outer batch Bundle to
-  Communication to inner document/batch/collection Bundle, with files modeled
-  as inner DocumentReference resources;
-- Immunization graphs and reminders live once under `src/builders/`; the former
-  root modules are deprecated re-export shims;
-- Group and ResearchStudy expose named claim constants, preserve member/party
-  correlation as separate rows and reject authorization-shaped data;
-- Organization departments remain distinct from offered HealthcareServices;
-  every independently schedulable service keeps its own stable identity and
-  Location references, while professional Group ownership remains explicit;
-- `buildServiceScheduleFlatGraph(...)` and the R5 Schedule/Slot adapters keep
-  per-service planning horizons and slot intervals shared between Vet and UHC;
-- schedulable child Locations preserve `partOf`, while Schedule actors can
-  combine the service with Location, Device and PractitionerRole capacity;
-  and
-- `npm run check` enforces minimum line, function and branch coverage across
-  converters, builders and core FHIR modules.
-
-This inventory is a boundary decision, not permission to leave another copy in
-new code. Consumers must move to this package bottom-up after its immutable
-release. Existing packages may retain compatibility re-exports only during
-that promotion.
-
-## Observation and component contract
-
-FHIR blood pressure is one native `Observation` with systolic and diastolic
-entries in `Observation.component[]`. Canonical flat storage is instead a
-resource graph: the primary Observation owns `Observation.has-member`, and
-each referenced reduced Observation owns its identifier, subject, category,
-date, component code, numeric value and unit. Reduced entries deliberately
-carry no `Observation.status`, so normal top-level listings ignore them while
-component-level indexes can query their ordinary Observation claims.
-
-The R4/R5 export adapter resolves the primary entry's members and reconstructs
-one native `Observation.component[]`; it does not export three independent
-native Observations. Component entries do not use `is-contained`,
-`contained-parent-reference` or `contained-reference-list`.
-
-Diagnostic laboratory authoring is owned here by
-`buildDiagnosticReportFlatGraph(...)`: `DiagnosticReport.code` identifies the
-report/panel, independent Observation entries carry atomic results, and
-independent DocumentReference entries carry PDF/image evidence. Sector roles,
-confirmation, ledger eligibility, consent and research policy remain outside
-this package.
-
-Aligned JSON arrays and the older comma-separated `Observation.component-*`
-claims are accepted only by the migration reader. No current writer emits
-either representation.
-
-The historical `Observation.bp-systolic-number` and
-`Observation.bp-diastolic-number` fields are accepted only when reading data
-that has no component graph or historical component claims. New writers and
-generic component indexes never emit them. This prevents a new custom claim
-family for every assessment scale.
-
-## Consumer promotion sequence
-
-1. Release this package, pin the immutable version in the lowest downstream
-   package, and run that consumer's complete local matrix.
-2. Remove the corresponding frozen dependency only after no consumer imports
-   that family from it.
-3. Migrate imaging/DICOM byte parsing and terminology payloads as separate changes because
-   they have different dependencies, security rules and release gates.
-
-## Ownership map for new work
-
-| Change | Owning surface |
-| --- | --- |
-| Add or rename a flat storage key | `src/claims/<resource>-claims.ts` |
-| Convert a native R4/R5 resource | `src/converters/convert-<resource>.ts` |
-| Author several correlated resources | `src/builders/` |
-| Preserve an obsolete input | Explicit read-only compatibility adapter |
-| Add transport, SMART or persistence behavior | Owning SDK/service, never this package |
-| Add sector terminology or policy | SOS, Vet or UHC data package |
-| Configure an R5 SubscriptionTopic/Subscription | Native builder and official search catalog in `subscription-r5`; registration remains in the owning service |
-| Persist or deliver a subscription event | GW/BFF transport and storage, never this package |
-
-Converters and builders import catalog symbols. Tests may spell native FHIR
-wire fields, but do not duplicate flat-claim paths except when proving that a
-malformed or invented path is rejected.
-
-## Schema-driven editor boundary
-
-`clinicalArtifactFhirR4ToFlat(...)` and
-`clinicalArtifactEditorClaimsFromFhirR4(...)` are import/read adapters. They
-turn a native FHIR R4 clinical resource into canonical flat claims and never
-own a portal form, authorization or transport decision.
-
-The cross-channel JSON Schema and the `BundleEditor`/`BundleReader` round trip
-belong to `sos-data-utils-ts`. A shared React component consumes both layers:
-FHIR conversion for native imports, then the SOS JSON Schema to select and
-validate editable values and create the claims-first changes Bundle. Portals
-must not add resource-specific claim mappers between those shared layers.
-
-## Subscription notification boundary
-
-FHIR R5 `SubscriptionTopic` and `Subscription` are native configuration
-resources, not flat clinical persistence. This package owns their strict typed
-builders, the official R5 resource-specific SearchParameter catalogs and the
-parser for `Bundle[type=subscription-notification]`. It also owns the minimal
-claims-first terminal Task `Communication` shape so producers and receivers do
-not duplicate claim paths.
-
-HTTP delivery, authentication, durable outbox/inbox storage and browser or
-email/push fan-out remain in GW, DataConv and the product BFFs. The neutral
-package contains no HTTP client and no gateway policy.