De-identifying FHIR

The @cosyte/deid/fhir adapter is the FHIR R4 binding of the de-identification core. It locates PHI structurally in a parsed FHIR resource (a name under a Patient is the patient's name because the FHIR spec says so, never because a string "looked like" a name), applies the configured policy, and returns a transformed resource model plus the core's value-free manifest.

@cosyte/fhir is an optional peer dependency. Install it alongside @cosyte/deid to use this subpath; a consumer who only de-identifies FHIR pays for nothing else, and the core stays third-party-dependency-free. The adapter reaches FHIR data only through @cosyte/fhir's exported model (FhirComplex / FhirList / FhirPrimitive, getProperty, resourceType, the node constructors) and its parseResource / serializeResource codec: it never imports a third-party JSON substrate.

npm install @cosyte/deid @cosyte/fhir

Quickstart

import { parseResource, serializeResource } from "@cosyte/fhir";
import { deidentifyFhir } from "@cosyte/deid/fhir";
import { createDeidContext } from "@cosyte/deid";

const context = createDeidContext({ key: process.env.DEID_KEY! });
const { resource } = parseResource(json);
const { document, manifest } = deidentifyFhir(resource, { context });

serializeResource(document); // spec-clean, de-identified FHIR JSON
manifest; // value-free audit: category + locus + disposition, never a value

A convenience wrapper parses, de-identifies, and re-serializes in one call:

import { deidentifyFhirJson } from "@cosyte/deid/fhir";
import { createDeidContext } from "@cosyte/deid";

const { json, manifest } = deidentifyFhirJson(input, {
  context: createDeidContext({ key: process.env.DEID_KEY! }),
});

A keyed transform (identifier pseudonymization) requires a context; calling without one when the resource needs it is a fatal DEID_NO_KEY: the engine never falls back to an unkeyed surrogate.

What is located, and how it is transformed

FHIR is a graph of typed resources, so the locus map splits by resource role. A name / address / telecom is PHI inside a person resource; the same datatype in Location or Organization is facility/administrative data and is left to the clinical-retain path: the FHIR analogue of the C-CDA adapter sweeping only the header participations, never the clinical body.

Scope	Loci	Transform
Person resources: Patient / RelatedPerson / Practitioner / Person (+ nested Patient.contact, a relative)	name, telecom, photo, address, birthDate, deceasedDateTime	name/telecom/photo removed; address → safe 3-digit ZIP (or 000 for a restricted prefix), finer geography dropped; dates → year
Every resource (the universal PHI vectors)	identifier, PHI-bearing dates, narrative text.div, extension / modifierExtension values, Reference.display	identifier → consistent surrogate by system (keyed HMAC; a US-SSN system removed); dates → year; narrative div / extension values / reference labels blocked
Contained resources & Bundle entries	each nested resource	walked: the resource role is re-derived at every resourceType, so a contained RelatedPerson or a Bundled Patient is de-identified too
Clinical resources: Observation, Condition, Encounter, …	codes, values, units, statuses, reference ranges, reference wiring	retained untouched (the over-scrub guard)

An identifier's Safe Harbor category is read from its system URI: the US-SSN system (http://hl7.org/fhir/sid/us-ssn or its OID form) routes to removed, every other identifier to a consistent surrogate with the system retained. A Reference.display (usually a person's name) is blocked, while a Coding.display (a coded term such as Sodium) is retained: the two are distinguished structurally, not by the property name.

Dates are detected by value shape: any primitive whose whole value is a real calendar date (YYYY-MM, YYYY-MM-DD, or a full instant) with a valid month/day is generalized to its year, wherever it sits, so a date in an unexpected element is caught too. A bare four-digit year is already Safe-Harbor-safe and is left as-is; a clinical code that merely looks date-ish (2951-2, 1234-56) is not mistaken for a date, so it survives.

Fail closed

• A bare unrecognized string at a person resource's top level is blocked: a positive allow-list of recognized coded/administrative elements governs the person sweep, so a vendor <Patient>-level field cannot ride through in the clear (an open-ended allow-list can never satisfy Safe Harbor's open-ended category (R)).
• A display that is not on a Coding is a Reference person-label and is blocked, including a display-only ({ display }) or type+display reference that names no reference/identifier target. A Coding is identified positively (a code/system sibling), so Coding.display (a coded term) is retained; every other display fails closed.
• Every extension value is dropped: a complex valueAddress / valueHumanName / valueIdentifier, a modifierExtension, a deeply nested extension, and a primitive-level _-sibling extension alike. Extensions are the FHIR leak frontier; the url skeleton is kept, the payload is not.
• Free-text prose is blocked by default: the note element (Annotation.text + author), a Communication/message contentString, and an uncoded valueString (the FHIR analogue of an HL7 OBX-5 typed ST, which the sibling HL7 adapter also fails closed on; a structured valueQuantity / valueCodeableConcept / valueDateTime result is retained).
• The narrative text.div is blocked at any depth (resource-, section-, entry-level).

The two guarantees

• No leak. Every seeded PHI sentinel across the person resources, the universal vectors, the nested contact relative, and a contained resource is gone from the serialized output. An unmapped element or extension that could carry PHI is blocked, never passed through in the clear.
• No over-scrub. Clinical resources (observation and medication codes, values, units, result statuses, reference ranges, coded displays) are retained, and reference wiring (Reference.reference pointers) is preserved, so linkage survives identifier pseudonymization.

Known limitations (this release)

• Extension values are block-only: there is no profile-aware retention, so a us-core-* demographic extension is dropped rather than kept.
• Reference wiring and resource logical ids are preserved structurally; coordinated pseudonymization of resource ids across a corpus (so the same patient links across documents) is not performed.
• Free-text prose loci (note, contentString, uncoded valueString) fail closed by default; a semantic (NLP) narrative scrub, contentAttachment binary content, and person names embedded in non-person resources (Organization.contact.name, Location.address) remain out of scope.

The honesty line is unchanged: the output is "Safe-Harbor-transformed per the configured policy," never "de-identified" and never "HIPAA-compliant."