fhir-data-utils-ts 0.6.21 → 0.6.22

package/CHANGELOG.md

@@ -5,6 +5,15 @@
 - 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

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/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/package.json

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