FHIR Practitioner and PractitionerRole resource modeling for provider directories
domain: hl7.org · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
In-depth guide
FHIR Bulk Data $export gotchas — the full failure-mode walkthrough related to hl7.org, checked against official docs, with linked verified routes.
Steps
Model individual provider identity in the Practitioner resource: include identifier (NPI with system http://hl7.org/fhir/sid/us-npi), name, birthDate, gender, qualification (license, board certification, DEA) with issuer organization reference, and communication languages.
Model the provider's role at a specific organization in PractitionerRole: link to Practitioner and Organization resources, populate specialty using NUCC taxonomy codes (system http://nucc.org/provider-taxonomy), and set period for effective/end dates.
For Plan-Net directory profiles, extend PractitionerRole with plan-net-specific extensions: network reference, newPatients acceptance flag, and availableTime; these are required for CMS payer directory compliance.
Validate resources against US Core v7+ Practitioner and PractitionerRole profiles; must-support fields include Practitioner.identifier (NPI), Practitioner.name, PractitionerRole.practitioner, PractitionerRole.organization, and PractitionerRole.code.
Support the required search parameters: for PractitionerRole, support practitioner.identifier and practitioner.name chained searches; implement _include for PractitionerRole:practitioner and PractitionerRole:organization to enable single-request fetching.
Handle the one-to-many relationship: one Practitioner resource per individual; create separate PractitionerRole resources for each distinct organization/location/specialty combination the provider holds.
Known gotchas
The Practitioner resource holds identity data (who the person is); PractitionerRole holds context data (what they do, where, in what role) — placing specialty or network in Practitioner instead of PractitionerRole is a common modeling error.
US Core requires that if PractitionerRole is supported, the server must be able to return the associated Practitioner via _include — not implementing _include causes US Core conformance failures.
NUCC taxonomy codes go in PractitionerRole.specialty, not PractitionerRole.code; the code element uses a different value set (HL7 provider role codes) — confusing the two elements produces directories that fail FHIR validation.
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?