# NDH PractitionerRole - National Directory of Healthcare Providers & Services (NDH) Implementation Guide v2.0.0-current

* [**Table of Contents**](toc.md)
* [**Artifacts Summary**](artifacts.md)
* **NDH PractitionerRole**

## Resource Profile: NDH PractitionerRole 

| | | |
| :--- | :--- | :--- |
| *Official URL*:http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-PractitionerRole | *Version*:2.0.0-current | |
| * Standards status: *[Trial-use](http://hl7.org/fhir/R4/versions.html#std-process) | [Maturity Level](http://hl7.org/fhir/versions.html#maturity): 4 | *Computable Name*:NdhPractitionerRole |

 
PractitionerRole typically describes details about a provider. When the provider is a practitioner, there may be a relationship to an organization. A provider renders services at a location. Practitioner participation in healthcare provider insurance networks may be direct or through their role at an organization. PractitionerRole involves either the actual or potential (hence the optionality on Practitioner) of an individual to play this role on behalf of or under the auspices of an organization. The absence of a Practitioner resource does not imply that the Organization itself is playing the role of a Practitioner, instead it implies that role has been established by the Organization and MAY apply that to a specific Practitioner. 

**Usages:**

* Refer to this Profile: [NDH Via Intermediary](StructureDefinition-base-ext-via-intermediary.md), [NDH Group](StructureDefinition-ndh-Group.md) and [NDH Verification](StructureDefinition-ndh-Verification.md)
* Examples for this Profile: [PractitionerRole/HansSoloRole](PractitionerRole-HansSoloRole.md), [PractitionerRole/HansSoloRole2](PractitionerRole-HansSoloRole2.md), [PractitionerRole/JoeSmithHospitalRole](PractitionerRole-JoeSmithHospitalRole.md), [PractitionerRole/JoeSmithRole2](PractitionerRole-JoeSmithRole2.md)... Show 3 more, [PractitionerRole/PractitionerOneNetwork1Role](PractitionerRole-PractitionerOneNetwork1Role.md), [PractitionerRole/PractitionerOneNetwork2Role](PractitionerRole-PractitionerOneNetwork2Role.md) and [PractitionerRole/PractitionerTwoNetwork1LeftAfterSixMonthRole](PractitionerRole-PractitionerTwoNetwork1LeftAfterSixMonthRole.md)
* CapabilityStatements using this Profile: [NDH Server Capability Statement](CapabilityStatement-ndh-server.md)

You can also check for [usages in the FHIR IG Statistics](https://packages2.fhir.org/xig/hl7.fhir.us.ndh|current/StructureDefinition/ndh-PractitionerRole)

### Formal Views of Profile Content

 [Description of Profiles, Differentials, Snapshots and how the different presentations work](http://build.fhir.org/ig/FHIR/ig-guidance/readingIgs.html#structure-definitions). 

 

Other representations of profile: [CSV](StructureDefinition-ndh-PractitionerRole.csv), [Excel](StructureDefinition-ndh-PractitionerRole.xlsx), [Schematron](StructureDefinition-ndh-PractitionerRole.sch) 

### Notes:

### Search Parameters

#### Search Parameter defined by the NDH IG

| | | |
| :--- | :--- | :--- |
| [location](SearchParameter-practitionerrole-location.md) | reference | `GET [base]/PractitionerRole?location.address-state=FL` |
| [network](SearchParameter-practitionerrole-network.md) | reference | `GET [base]/PractitionerRole?network.type=ntwk$network.name=Florida Blue` |
| [new-patient](SearchParameter-practitionerrole-new-patient.md) | token | `GET [base]/PractitionerRole?new-patient=newpt` |
| [new-patient-from-network](SearchParameter-practitionerrole-new-patient-from-network.md) | reference | `GET [base]/PractitionerRole?new-patient-from-network=newpt` |
| [organization](SearchParameter-practitionerrole-organization.md) | reference | `GET [base]/PractitionerRole?organization.name=Florida Blue` |
| [verification-status](SearchParameter-verification-status.md) | token | `GET [base]/PractitionerRole?verification-status=complete` |

#### Search Parameter defined by FHIR Search Parameter Registry and used by the NDH IG

Since there is no direct individual url for each Search Parameter defined by FHIR Serach Parameter Registry, we have provided the following links for you to access more information about them.

* [Search Parameter Registry](https://hl7.org/fhir/R4/searchparameter-registry.html)
* [PractitionerRole Search Parameter from Registry](https://hl7.org/fhir/R4/practitionerrole.html#search)

| | | |
| :--- | :--- | :--- |
| active | token | `GET [base]/PractitionerRole?active=true` |
| endpoint | reference | `GET [base]/PractitionerRole?endpoint.status=active` |
| identifier | token | `GET [base]/PractitionerRole?identifier=1234567` |
| practitioner | reference | `GET [base]/PractitionerRole?practitoner.name=Joe Smith` |
| role | token | `GET [base]/PractitionerRole?role=att` |
| service | reference | `GET [base]/PractitionerRole?service.address-state=FL` |
| specialty | token | `GET [base]/PractitionerRole?specialty=103TF0000X` |

#### _include Search Parameter

| | |
| :--- | :--- |
| PractitionerRole:endpoint | `GET [base]/PractitionerRole?_include=PractitionerRole:endpoint` |
| PractitionerRole:location | `GET [base]/PractitionerRole?_include=PractitionerRole:location` |
| PractitionerRole:network | `GET [base]/PractitionerRole?_include=PractitionerRole:network` |
| PractitionerRole:new-patient-from-network | `GET [base]/PractitionerRole?_include= PractitionerRole:new-patient-from-network` |
| PractitionerRole:organization | `GET [base]/PractitionerRole?_include=PractitionerRole:organization` |
| PractitionerRole:practitioner | `GET [base]/PractitionerRole?_include=PractitionerRole:practitioner` |
| PractitionerRole:service | `GET [base]/PractitionerRole?_include=PractitionerRole:service` |

#### _revinclude Search Parameter

None

#### Special Search Parameters

The search parameters outlined above are straightforward for basic scenarios but have limitations in handling complex combination queries. To enhance these capabilities, employing the special search parameters [_filter](https://hl7.org/fhir/R5/search_filter.html#3.2.3) is recommended.

#### The reason the cardinality of PractitionerRole.network is 0..1

The network cardinality sets to 0..1 is to meet the requirements of linking PractitionerRole with a specific time period. The duration a practitioner spends in a network often differs across networks, and it's unusual for these periods to coincide. When a Practitioner is incorporated into a new network, the relevant time frame adheres to that specific network's agreement or contract with the practitioner. The same principle applies when the practitioner departs from the network.

### How resource ownership functions when multiple entities can provide information for the same resource

Assuming that the Practitioner "owns" the practitionerRole, the practitioner must attest to the information related to their participation in a specific network. If there is no existing network declaration associated with that practitionerRole, the practitioner should update the practitionerRole accordingly. However, if a network declaration already exists for that role, the practitioner should create a new practitionerRole and include the network information in this role. This process is also applicable to other individuals who have ownership responsibilities for the practitionerRole.

#### PractitionerRole.availabeTime and PractitionerRole.notAvailable

Given that both 'availableTime' and 'notAvailable' time are optional elements, they can be excluded for intricate or often changing schedules. These fundamental elements are designed for use where providers have fairly stable schedules (such as clinic schedules that need to be communicated clearly as part of the directory resources), as opposed to an on-call practitioner's schedule.

#### PractitionerRole, Location, Address

The address for a practitionerRole should be located on the Location reference. There is no address on the practitionerRole base resource since the location reference of practitionerRole has an address that should be used by the practitioner as part of their role. Each practitionerRole can support multiple locations. If two practitioners work at the same facility and each of them has their own non-service delivery locations, in addition to the common service delivery location. The guidance descripted in the diagram below:



## Resource Content

```json
{
  "resourceType" : "StructureDefinition",
  "id" : "ndh-PractitionerRole",
  "extension" : [{
    "url" : "http://hl7.org/fhir/StructureDefinition/structuredefinition-wg",
    "valueCode" : "pa"
  },
  {
    "url" : "http://hl7.org/fhir/StructureDefinition/structuredefinition-fmm",
    "valueInteger" : 4,
    "_valueInteger" : {
      "extension" : [{
        "url" : "http://hl7.org/fhir/StructureDefinition/structuredefinition-conformance-derivedFrom",
        "valueCanonical" : "http://hl7.org/fhir/us/ndh/ImplementationGuide/hl7.fhir.us.ndh"
      }]
    }
  },
  {
    "url" : "http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status",
    "valueCode" : "trial-use",
    "_valueCode" : {
      "extension" : [{
        "url" : "http://hl7.org/fhir/StructureDefinition/structuredefinition-conformance-derivedFrom",
        "valueCanonical" : "http://hl7.org/fhir/us/ndh/ImplementationGuide/hl7.fhir.us.ndh"
      }]
    }
  }],
  "url" : "http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-PractitionerRole",
  "version" : "2.0.0-current",
  "name" : "NdhPractitionerRole",
  "title" : "NDH PractitionerRole",
  "status" : "active",
  "date" : "2026-03-23T21:58:05+00:00",
  "publisher" : "HL7 International / Patient Administration",
  "contact" : [{
    "name" : "HL7 International / Patient Administration",
    "telecom" : [{
      "system" : "url",
      "value" : "http://www.hl7.org/Special/committees/pafm"
    },
    {
      "system" : "email",
      "value" : "pafm@lists.hl7.org"
    }]
  }],
  "description" : "PractitionerRole typically describes details about a provider. When the provider is a practitioner, there may be a relationship to an organization. \nA provider renders services at a location. Practitioner participation in healthcare provider insurance networks may be direct or through their role at an organization. \nPractitionerRole involves either the actual or potential (hence the optionality on Practitioner) of an individual to play this role on behalf of or under the auspices of \nan organization. The absence of a Practitioner resource does not imply that the Organization itself is playing the role of a Practitioner, instead it implies that role \nhas been established by the Organization and MAY apply that to a specific Practitioner.",
  "jurisdiction" : [{
    "coding" : [{
      "system" : "urn:iso:std:iso:3166",
      "code" : "US",
      "display" : "United States of America"
    }]
  }],
  "fhirVersion" : "4.0.1",
  "mapping" : [{
    "identity" : "ndh-to-plannet-practitionerrole",
    "uri" : "http://hl7.org/fhir/us/davinci-pdex-plan-net",
    "name" : "NDH to Plan-Net PractitionerRole Mapping",
    "comment" : "Maps NDH PractitionerRole profile to the Plan-Net PractitionerRole profile, noting elements not present in Plan-Net."
  },
  {
    "identity" : "v2",
    "uri" : "http://hl7.org/v2",
    "name" : "HL7 v2 Mapping"
  },
  {
    "identity" : "rim",
    "uri" : "http://hl7.org/v3",
    "name" : "RIM Mapping"
  },
  {
    "identity" : "servd",
    "uri" : "http://www.omg.org/spec/ServD/1.0/",
    "name" : "ServD"
  },
  {
    "identity" : "w5",
    "uri" : "http://hl7.org/fhir/fivews",
    "name" : "FiveWs Pattern Mapping"
  }],
  "kind" : "resource",
  "abstract" : false,
  "type" : "PractitionerRole",
  "baseDefinition" : "http://hl7.org/fhir/us/core/StructureDefinition/us-core-practitionerrole|6.1.0",
  "derivation" : "constraint",
  "differential" : {
    "element" : [{
      "id" : "PractitionerRole",
      "path" : "PractitionerRole",
      "constraint" : [{
        "key" : "practitioner-or-organization-or-healthcareservice-or-location",
        "severity" : "error",
        "human" : "If NdhPractitionerRole.practitioner is absent  ( NdhPractitionerRole.organization, NdhPractitionerRole.healthcareservice, NdhPractitionerRole.location) \nmust be present",
        "expression" : "practitioner.exists() or (organization.exists() or healthcareService.exists() or location.exists())",
        "source" : "http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-PractitionerRole"
      }],
      "mapping" : [{
        "identity" : "ndh-to-plannet-practitionerrole",
        "map" : "PractitionerRole",
        "comment" : "Top-level mapping from NDH to Plan-Net"
      }]
    },
    {
      "id" : "PractitionerRole.meta.lastUpdated",
      "path" : "PractitionerRole.meta.lastUpdated",
      "min" : 1,
      "mapping" : [{
        "identity" : "ndh-to-plannet-practitionerrole",
        "map" : "PractitionerRole.meta.lastUpdated",
        "comment" : ", is required in NDH"
      }]
    },
    {
      "id" : "PractitionerRole.extension",
      "path" : "PractitionerRole.extension",
      "slicing" : {
        "discriminator" : [{
          "type" : "value",
          "path" : "url"
        }],
        "ordered" : false,
        "rules" : "open"
      }
    },
    {
      "id" : "PractitionerRole.extension:rating",
      "path" : "PractitionerRole.extension",
      "sliceName" : "rating",
      "min" : 0,
      "max" : "*",
      "type" : [{
        "code" : "Extension",
        "profile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/base-ext-rating"]
      }],
      "mapping" : [{
        "identity" : "ndh-to-plannet-practitionerrole",
        "map" : "Not in Plan-Net",
        "comment" : ", NDH-specific"
      }]
    },
    {
      "id" : "PractitionerRole.extension:newpatients",
      "path" : "PractitionerRole.extension",
      "sliceName" : "newpatients",
      "short" : "New Patients",
      "min" : 0,
      "max" : "*",
      "type" : [{
        "code" : "Extension",
        "profile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/base-ext-newpatients"]
      }]
    },
    {
      "id" : "PractitionerRole.extension:network",
      "path" : "PractitionerRole.extension",
      "sliceName" : "network",
      "short" : "NetworkReference",
      "min" : 0,
      "max" : "1",
      "type" : [{
        "code" : "Extension",
        "profile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/base-ext-network-reference"]
      }],
      "mapping" : [{
        "identity" : "ndh-to-plannet-practitionerrole",
        "map" : "PractitionerRole.network",
        "comment" : ", using NDH Network Profile"
      }]
    },
    {
      "id" : "PractitionerRole.extension:qualification",
      "path" : "PractitionerRole.extension",
      "sliceName" : "qualification",
      "short" : "Qualification",
      "min" : 0,
      "max" : "*",
      "type" : [{
        "code" : "Extension",
        "profile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/base-ext-qualification"]
      }]
    },
    {
      "id" : "PractitionerRole.extension:verification-status",
      "path" : "PractitionerRole.extension",
      "sliceName" : "verification-status",
      "min" : 0,
      "max" : "1",
      "type" : [{
        "code" : "Extension",
        "profile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/base-ext-verification-status"]
      }],
      "mapping" : [{
        "identity" : "ndh-to-plannet-practitionerrole",
        "map" : "Not in Plan-Net",
        "comment" : ", NDH-specific"
      }]
    },
    {
      "id" : "PractitionerRole.identifier",
      "path" : "PractitionerRole.identifier",
      "mustSupport" : true,
      "mapping" : [{
        "identity" : "ndh-to-plannet-practitionerrole",
        "map" : "PractitionerRole.identifier"
      }]
    },
    {
      "id" : "PractitionerRole.identifier.extension:identifier-status",
      "path" : "PractitionerRole.identifier.extension",
      "sliceName" : "identifier-status",
      "min" : 0,
      "max" : "1",
      "type" : [{
        "code" : "Extension",
        "profile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/base-ext-identifier-status"]
      }],
      "mapping" : [{
        "identity" : "ndh-to-plannet-practitionerrole",
        "map" : "Not in Plan-Net",
        "comment" : ", NDH-specific"
      }]
    },
    {
      "id" : "PractitionerRole.identifier.assigner",
      "path" : "PractitionerRole.identifier.assigner",
      "type" : [{
        "code" : "Reference",
        "targetProfile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-Organization"]
      }]
    },
    {
      "id" : "PractitionerRole.active",
      "path" : "PractitionerRole.active",
      "min" : 1,
      "patternBoolean" : true
    },
    {
      "id" : "PractitionerRole.practitioner",
      "path" : "PractitionerRole.practitioner",
      "type" : [{
        "code" : "Reference",
        "targetProfile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-Practitioner"]
      }]
    },
    {
      "id" : "PractitionerRole.organization",
      "path" : "PractitionerRole.organization",
      "short" : "Organization where the role is available",
      "definition" : "The organization where this role is available",
      "comment" : "Some relationships (represented as PractitionerRoles) that may exist between practitioners and organizations include:\n - A practitioner may act as a pediatrician when associated with an organization that runs a family clinic.  PractitionerRole.organization would represent the family clinic.\n - The same practitioner may act as a physician when providing physicals for an athletics department at a school.  PractitionerRole.organization would represent the school.\n - A practitioner may perform coumadin anticoagulation services for a clinic run by a health system.   PractitionerRole.organization would represent the coumadin clinic.\n - A practitioner may act as an inpatient pharmacist reviewing and dispensing medications.  PractitionerRole.organization would represent the hospital pharmacy.\n - A practitioner may perform medication management and adherence services for an internal medicine clinic.  PractitionerRole.organization would represent the internal medicine clinic.\n - A practitioner is part of a payer's network such as a preferred provider organization (PPO), or health maintenance organizations (HMO)).  \nPractitionerRole.organization would represent the payer's network.\nEach of the examples above, would be represented as different PractitionerRole instances, each with a different values for PractitionerRole.organization.",
      "type" : [{
        "code" : "Reference",
        "targetProfile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-Organization"]
      }]
    },
    {
      "id" : "PractitionerRole.code",
      "path" : "PractitionerRole.code",
      "slicing" : {
        "discriminator" : [{
          "type" : "value",
          "path" : "$this"
        }],
        "description" : "NDH PractitionerRole Code",
        "ordered" : false,
        "rules" : "open"
      }
    },
    {
      "id" : "PractitionerRole.code:NDHPractitionerRoleCode",
      "path" : "PractitionerRole.code",
      "sliceName" : "NDHPractitionerRoleCode",
      "short" : "NDH PractitionerRole Code",
      "min" : 0,
      "max" : "*",
      "binding" : {
        "strength" : "required",
        "valueSet" : "http://hl7.org/fhir/us/ndh/ValueSet/PractitionerRoleVS"
      }
    },
    {
      "id" : "PractitionerRole.specialty",
      "path" : "PractitionerRole.specialty",
      "binding" : {
        "extension" : [{
          "extension" : [{
            "url" : "key",
            "valueId" : "NDH-PractitionerRole-specialty"
          },
          {
            "url" : "purpose",
            "valueCode" : "extensible"
          },
          {
            "url" : "valueSet",
            "valueCanonical" : "http://hl7.org/fhir/us/ndh/ValueSet/IndividualQualificationsVS"
          },
          {
            "url" : "documentation",
            "valueMarkdown" : "The specialty(ies) of the practitioner role, which may be defined by the organization or provided by the practitioner directly.  This is not intended to represent certifications or licenses, but rather areas of focus or concentration for a particular role.  For example, a practitioner may have a role as a physician with a specialty in cardiology, and another role as a physician with a specialty in pediatrics."
          },
          {
            "url" : "shortDoco",
            "valueString" : "The specialty(ies) of the practitioner role."
          }],
          "url" : "http://hl7.org/fhir/tools/StructureDefinition/additional-binding"
        }],
        "strength" : "extensible",
        "valueSet" : "http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.114222.4.11.1066|20240606"
      }
    },
    {
      "id" : "PractitionerRole.location",
      "path" : "PractitionerRole.location",
      "type" : [{
        "code" : "Reference",
        "targetProfile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-Location"]
      }]
    },
    {
      "id" : "PractitionerRole.healthcareService",
      "path" : "PractitionerRole.healthcareService",
      "type" : [{
        "code" : "Reference",
        "targetProfile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-HealthcareService"]
      }],
      "mustSupport" : true,
      "mapping" : [{
        "identity" : "ndh-to-plannet-practitionerrole",
        "map" : "PractitionerRole.healthcareService",
        "comment" : ", using NDH HealthcareService Profile"
      }]
    },
    {
      "id" : "PractitionerRole.telecom.extension:contactpoint-availabletime",
      "path" : "PractitionerRole.telecom.extension",
      "sliceName" : "contactpoint-availabletime",
      "min" : 0,
      "max" : "*",
      "type" : [{
        "code" : "Extension",
        "profile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/base-ext-contactpoint-availabletime"]
      }]
    },
    {
      "id" : "PractitionerRole.telecom.extension:via-intermediary",
      "path" : "PractitionerRole.telecom.extension",
      "sliceName" : "via-intermediary",
      "short" : "Via Intermediary",
      "min" : 0,
      "max" : "1",
      "type" : [{
        "code" : "Extension",
        "profile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/base-ext-via-intermediary"]
      }]
    },
    {
      "id" : "PractitionerRole.endpoint",
      "path" : "PractitionerRole.endpoint",
      "type" : [{
        "code" : "Reference",
        "targetProfile" : ["http://hl7.org/fhir/us/ndh/StructureDefinition/ndh-Endpoint"]
      }],
      "mapping" : [{
        "identity" : "ndh-to-plannet-practitionerrole",
        "map" : "PractitionerRole.endpoint",
        "comment" : ", using NDH Endpoint Profile"
      }]
    }]
  }
}

```
