Provider registries in FHIR

So we’ve had some interest in New Zealand concerning Provider registries – locations where the details of providers and the services they provide can be maintained and discovered. There are a lot of potential uses for such a registry, but the two that we’ve been discussing are locating targets for referrals, and locating providers by specialty as part of Care Pathways.

Typical query use cases could include:

  • Find a Provider by name (or other personal detail)
  • Find a Provider by specialty – eg a physiotherapist
  • Locate a Service provided by a facility like a hospital

There are lots more of course, but these will get us started.

So looking at FHIR, there are a number of resources that we’re going to need.

(Note that we’ll use the STU3 candidate version from January this year as this is the version currently on the public HAPI3 server which we’ll use for this. There are a number of differences planned for the final release of STU3 – most notably the removal of role information from the Practitioner resource – but these won’t affect this discussion.)

Here are the resources of interest (the links are to the current build – I’ll update them to the final STU3 version once that is released):

The Practitioner resource represents a person involved in the delivery of healthcare – a doctor, nurse, physio, receptionist – pretty much any human (or animal for that matter). This is a human Provider.

The PractitionerRole resource. This represents the role/s that a Practitioner can be in – details of the role, where they perform it, the times they are available and so forth. This is a new resource and was split off from the Practitioner specifically to support this kind of use. (See Brian Postlethwaites blog for more discussion on this point, and why the change was made which was driven by practical experience at Connectathons). Note that a single Practitioner can have multiple roles

The HealthcareService describes an actual service (rather than a person) that is provided by some organization. For example a Cardiology outpatient clinic at a hospital, or a primary care service. This is a service Provider.

The Organization represents the grouping of people or companies that are delivering care. It’s a rather abstract thing that isn’t the actual place where care is delivered (that’s the location) – rather the entity that organizes the care (hence the name I guess)

The Location is the actual place where care is delivered – the physical hospital or Primary Care/ambulatory care clinic.

Note that the term ‘Provider’ applies both to people (Practitioners) and services (HealthcareService). We’ll use the specific FHIR term in the following discussion.

Here’s an image of how the resources inter-relate:


This was generated using the Scenario Builder in clinFHIR. I set the Conformance and Data server to the public HAPI3  server and added a single instance of each resource type to the scenario. Then, I set the various references between resources, added some data to them and saved the lot to the Data server so I could check the queries. There are references to other resources of course, and the diagram does not indicate the multiplicity of the references – but it’s easy for you to do this yourself if you want to experiment further.

As you can see there are 2 main resources that pull everything together – the PractitionerRole (which lets us find individual Practitioners) and the HealthcareService, which is about Services rather than people.

Let’s think about what queries we’ll need to meet our Use Cases.

Before we do this, just a reminder that each resource type has a number of search parameters defined in the specification. A server is not obliged to support all of them (it indicates which ones using the CapabilityStatement resource), and can support others (which it documents using the SearchParameter resource)

Find a Practitioner by name

To start with, let’s assume we know the Practitioners name, and just want their personal details (like phone number or email). In this case we’re just querying the Practitioner resource. Here’s a sample query we could use:

It will return all the Practitioners whose name is Welby. Simple. And, of course, we could use any of the defined search parameters that are supported by the registry.

Note that this query will not return any role based information (this is one place where the final STU3 version will differ from the candidate version that we are using) – see the link to Brians post above for more information on why this was done.

Find a Practitioner with a given specialty

Moving on, let’s think how we can find Practitioners by specialty.

Because the specialty is associated with the PractitionerRole and not the Practitioner, our query will be on PractitionerRole. (Note that a single Practitioner can have multiple PractitionerRoles of course). Here’s a query that will return the Practitioner roles for cardiology (where 394579002 is the SNOMED term for cardiology).

(Note that you should really specify the system when doing a lookup on coded elements – so the more accurate query would be:

but I’ll leave that out to keep the queries more understandable.

This will return a bundle of PractitionerRole resources – useful, but we really want the names of the Practitioners. We could do separate queries for each Practitioner of course, but we could also take advantage of the _include search parameter. The following query will return the PractitionerRoles, but will also include the referenced Practitioners in the bundle as well:

and why stop at the Practitioner? Let’s get the Organization and Location as well:

This will return all the needed resources in a single query (assuming server support of course).

Find services

If we want to locate services rather than people, then a query on HealthcareService is required. There are a number of different coded elements that we could use:

  • serviceCategory
  • serviceType (eg the specialty of the service)
  • specialty

as well as other query parameters such as

  • location
  • providedBy
  • coverageArea

so the queries used are going to be very dependent on the actual implementation.

For the purposes of this post, let’s assume we’ve used the service type as the element to query on – eg Cardiology clinic or Physiotherapy service. The following query will return all the HealthcareService resources where the type is Cardiology.

Note that the ValueSet (and hence system) used for the serviceType is different to the specialty ValueSet used by Practitioner.

Of course we can use the _include search parameter to include referenced resources in the query – location and providedBy (Organization) would seem two likely candidates.

Last thoughts

So we’ve taken a – very – superficial look at how we could implement a Provider registry in FHIR. The design of a real system will be a lot more complex of course, and careful thought will need to be given on which relationship are important.

I suspect that the main issues in implementing such a registry will not be technical, but rather around governance – who has the right to update and access this information.

One thing that did stand out for me as I was preparing this post was how there are a number of coded elements with ValueSets that will need to be chosen and defined for a particular implementation – such as PractitionerRole.service or Healthcareservice.category (there are lots of others, and don’t even think about extensions!)

This is, of course, where profiling comes in to play…


BTW – if you’re interested in a ‘real’ Implementation guide for a Provider Directory, check out the Argonaut Provider Directory . (Note that this is the development version – I’ll replace with the ‘released’ version when that is ready).



About David Hay
I'm an independent contractor working with a number of Organizations in the health IT space. I'm an HL7 Fellow, Chair Emeritus of HL7 New Zealand and a co-chair of the FHIR Management Group. I have a keen interest in health IT, especially health interoperability with HL7 and the FHIR standard. I'm the author of a FHIR training and design tool - clinFHIR - which is sponsored by InterSystems Ltd.

14 Responses to Provider registries in FHIR

  1. Pingback: The FHIR EndPoint resource | Hay on FHIR

  2. John says:

    It’s all great stuff you’re posting. It’s Welby that’s making it even better. I’m now waiting for Dr. Kildare to make an appearance : )

  3. John O'Gorman says:

    Man, there are some confusing semantics and relationships, here. Why, for example, would I use the word ‘Provider’ in one context and ‘Practitioner’ in another? Also, why would FHIR include ‘Location’ in a PractionerRole concept?

    I have to look into this a bit more, but if I was creating a Provider web interface it would likely have to include some work-arounds to make these behave intuitively.

    • David Hay says:

      Well, I think that term ‘provider’ is being used at a high level as ‘some entity that provides some healthcare related thing’ – could be a specific person (Practitioner) or something like a clinic (HealthcareService). The Location in PractitionerRole would be because the role is related to where the work is being done – I may be acting as a doctor when at a hospital, but as a paramedic when working for an ambulance service (You could argue that this is covered by Organization – but I suspect that both are there to give maximum flexibility for an implementation).

      But it is a complex area – I’ll see if I can get Brian to comment (who knows a lot more then me about this stuff), and at some point I’ll build a UI in clinFHIR (maybe that could be my connectathon project) so will share my findings then.

      Thanks for the comment!

      • John O'Gorman says:

        Thanks David… I will do some more research, but this approach: – “…the role is related to where the work is being done – I may be acting as a doctor when at a hospital, but as a paramedic when working for an ambulance service” seems to suggest a possible Cartesian product involving combinations of: Person – Role – Facility – Activity and Location.

        I guess you could say that provides maximum flexibility but that it comes with a maintenance headache… Yes?

      • You are right there John, where people work and what they do is a complex area, and this is a pragmatic representation of that.
        This is essentially how the Australian National Services Directory represents the data too.

      • John O'Gorman says:

        Thanks Brian. I understand the need to be able to have a single provider work in multiple facilities.

        Maybe its the classification of Location I’m getting hung up on. ‘Alberta Children’s Hospital’ is a Physical Asset (aka facility) in Calgary. Its Location is “2888 Shaganappi Trail NW, Calgary, AB T3B 6A8”. The relationship is an intersection between the ‘Thing’ and its ‘Coordinates’. Common usage overlaps the two classes of Information (“Her operation took place at Alberta Children’s Hospital”) but I’m wondering why FHIR would do the same.

        My question is a ‘that ship has sailed’ sort of thing but as I said to David, I have to do more reading on the spec.

    • I’ll start off with your terminology question, many places/jurisdictions use the term “Provider” interchangably between both the people (practitioners) and the organizations that provide them.
      Also, as a generalized term, others have termed them Provider Directories (so much so that the IHE standard on this topic is called HPD (Healthcare Provider Directory) and includes details of Practitioners, and the places that they work.
      As for why is there a Location on the role? That’s because there are many practitioners who work at multiple places. For example an IVF specialist (Dr Babymaker) has 3 clinics in different regions, and spends mon/tue at location A, wed at location B, and thu/fri at location C.
      This allows me as a consumer to locate Dr Babymaker and when I can see him at which of the clinics he works at.

      • John O'Gorman says:

        My questions about a particular provider/practitioner would look like this:

        When I ask the question: “What is Alberta Children’s Hospital?’ I would expect to get a ‘This is What it is’ answer: ‘Alberta Children’s Hospital is the largest public hospital for sick children in the prairie provinces, and is located in Calgary, Alberta, Canada. It is operated by Alberta Health Services – Calgary Health Region.’

        When I ask the question: “Where is Alberta Children’s Hospital?’ I would expect to get a ‘This is the Location’ answer: “Alberta Children’s Hospital is located at 2888 Shaganappi Trail NW, Calgary, AB”

        When I ask the question: “What Role does Dr. Babymaker have?” I would expect a “This is Dr. Babymaker’s Role’ answer: “Dr. Babymaker is a Pediatric Surgeon.”

        When I ask ‘Where does Dr. Babymaker have privilege to practice in a given Role?’ the answer should be translated to the What (Facility) answer, with follow-on ‘Where is that?’ and ‘In What Role?’ questions.

        All of the atomic pieces (Alberta Children’t Hospital, Calgary, Alberta, 2888 Shaganappi Trail NW, Dr. Babymaker and Pediatric Surgeon need to exist separately. Does that make the ‘PractionerRole’ concept in FHIR a sort of compound node?

  4. David Hay says:

    wrt to your comment about maintenance, I think it also reflects that fact the FHIR is designed to be useful in as many different contexts as possible, using profiling to ‘lock down’ (and add elements) the specific structure for a given implementation, rather than try to come up with a single design that everyone must use.

    But this is a work in progress, and practical feedback is always welcomed! Feel free to contribute your ideas and comments through the various channels like

    • John O'Gorman says:

      This is from the FHIR spec and illustrates, I think, the problem pretty well. In-line emphasis and comments, are mine:

      5.15.2 Boundaries and Relationships

      Locations and Organizations are very closely related resources and can often be mixed/matched/confused.

      No, it’s Location and Physical Assets that are confused here…

      The Location is intended to describe the more physical structures managed/operated by an organization, whereas the Organization is intended to represent the more conceptual hierarchies, such as a ward.

      Why not just call them Physical Structures?

      A specific ward is-part of a given Physical Structure… this modelling almost guarantees maps and floor plans could not be derived from or used used by it.

      A Location is valid without an address in cases where it could be purely described by a geo-coded location in remote areas, or when recorded by a device.


      Locations with a mode = “kind” would also likely not have an address, as they are just a type of location, but could also have an address where they can be found at the address.


      Another use of location could be for describing a Jurisdiction. This jurisdiction may be considered a classified boundary which could be a combination of a physical boundary, and some other discriminator(s):

      Nation – Country wide community or Federal Government (Ministry of Health)
      Province or State (community or Government)
      Business (throughout an enterprise)
      Business scope (CDC/FDA)
      Business segment (UK Pharmacy)

      These ‘uses’ seem to be combining Place (e.g. US) and Organization (e.g. FDA) on top of Physical Asset (Atlanta Children’s Hospital) and – in the Example section — things like roads and ambulances. Why, when the objective is interoperability, would this be done this way?

  5. Pingback: Confluence: HC Projects

Leave a Reply

%d bloggers like this: