What Your FHIR Profile Does Not Say

A FHIR profile is not a technical document — it’s a contract between source and target system. What the contract doesn’t fix gets lost in the first mapping.

A profile is a commitment

Whoever writes a profile makes a commitment: this is what our delivery looks like. Cardinalities, data types, bound value sets, slices, invariants — each is a clause in the contract the target system may rely on. That is what profiles are for, and it is what they are good at.

The silent assumption is: whatever is not in the profile is unimportant. It is wrong. Whatever is not in the profile is unregulated — and about unregulated matters, the implementation decides at mapping time.

Four gaps the contract often leaves open

Four things are rarely written into profiles and are therefore lost regularly. They are not outliers but patterns — the four canonical loss patterns.

• How precise does the code have to be? A profile binds a value set, but rarely fixes which precision must survive. If a precise source concept is mapped onto a coarser target concept, the result is valid — and less precise than the source.
• How precise does the time have to be? dateTime permits the day and permits the second. A course from 08:12 to 11:47 becomes an all-day entry, and no constraint prevents that as long as none demands otherwise.
• Which qualifying attributes are mandatory? Unit, status, negation. “No known allergy” is a statement; a missing entry is not. Where 0..1 stands, both are permitted.
• Which references must hold? A finding without its order reference remains a valid finding. It just no longer answers the question it belonged to.

Why this only shows up at mapping time — or not at all

As long as source and target system are looked after by the same people, shared understanding carries the gap. At the first mapping across an organizational boundary it no longer does. Whoever maps reads the profile and follows it; everything not written in it they decide at their own discretion — usually plausibly, usually undocumented, invisible to the other side.

The validator then confirms that the result complies with the rules. It does. It is a guardian of structure, not of meaning — that is what it is built for, and there it is reliable. The second level of inspection has to come from somewhere else.

What belongs in the contract

A profile does not get better by containing more constraints. It gets better when it answers the four questions above — and answers them where they belong: as a fixed statement in the profile, not as a footnote in the implementation guide and not as a verbal agreement expected to outlive the project.

Part of that is the most honest step: naming explicitly what is deliberately left open. A contract with a declared gap is better than one with a silent gap — a declared gap is one somebody can close.