This wiki has undergone a migration to Confluence found Here
<meta name="googlebot" content="noindex">

FHIR Governance

From HL7Wiki
Jump to navigation Jump to search

FHIR (formerly RFH) Governance/process considerations

This document proposes a set of candidate governance processes and rules for FHIR constructs. The intention is to start the conversation around how governance and QA management could be done for FHIR. None of these rules or governance processes has been approved in any way. Comments & edits are welcome.

Changing Resource Wire Formats

Because requirements will evolve, changes to a resource wire format are unavoidable. To minimize rework by implementers, certain principles need to be followed:


  1. Wire formats should only be changed if there’s a need to convey new data elements.
  2. When changes are required, x-paths to elements in the prior version must be retained. If not, the resource name must be changed with the old resource being deprecated.

Processes and Guidelines

  1. QA should be undertaken for all wire formats to ensure that tag names are spelled correctly (ideally by automated process that “splits” lower-camel-case names and validates the terms against a spell checker).
  2. Repeating elements should be named as singular
  3. Names should:
    1. align with common domain terminology
    2. be short but descriptive
    3. in US English
    4. avoid abbreviations
    5. be expressed as a singular
    6. end with a noun
    7. include prefix adjectives only when necessary to clearly exclude other concepts
    8. be unique in context
    9. be consistent with names of equivalent concepts in other resources where clinical/domain familiarity will not be adversely affected
  4. Nesting of structures should be minimized to reduce issues with changing hierarchies
  5. Ordering of different elements should not be significant. I.e. We shouldn’t encounter a situation where someone might say “A should come before B” and have rules they could point to that would necessitate such a re-ordering.
  6. If an existing element must be “moved” into a new more complex structure to allow conveying of new data elements in an intelligent manner, there are three possibilities:
    1. Retain the existing data structure and add the new data structure and expect both to be populated with redundant data
    2. Capture the new data elements in an “extension” tied to the previously existing data element(s)
    3. Create a new version of the resource (adding a version number or something to the existing resource name.)
  7. Features added to a resource definition that affect the semantic interpretation of elements in previous versions of the specification will be handled in one of two ways:
    1. Require the newly added element with a “must support” indicator on the wire. Applications that cannot process a “must support” element must reject or fail the processing of instances containing such an element.
      1. The new element must be a direct sibling of the element that is a parent element of all other elements whose semantics are affected
        1. Issue: This works for elements defined in the resource, however it's harder to account for with extensions, particularly extensions we don't know about. How do we deal with "must understand" there
    2. Create a new version of the resource (adding a version number or something to the existing resource name.)
  8. The decision to create a new version of the resource rather than following one of the alternative approaches will only be made where the complexity of maintaining full wire format compatibility with the prior version is felt to outweigh the complexity of migrating to a new wire format version.
  9. If a previous resource wire format is deprecated and a new one is created, transforms shall be published as part of the new resource version to allow transformation between the old and new version.
    1. Compliant systems should be designed to support use of such transforms at runtime should they eventually be needed for supported resources.
    2. The definition for the deprecated resource shall be updated to contain a reference to the definition of the new resource.

Changing Resource Semantic Ontologies

Just as resource wire formats can evolve, resource ontologies will also evolve. Due to the need of the ontology to support most resource extensions and the constraints associated with aligning with one or more underlying reference models, changes will tend to be more frequent and more “severe” in terms of altering existing navigation paths. While the percentage of implementers that will rely on the ontology layer is not high (likely in the 10-25% range), those who do rely on this layer will still need a means to manage these changes and operate across different versions.


  1. Elements constructed against older versions of a resource ontology must be automatically expressible using new versions of the resource ontology and vice versa. This includes spanning “versions” of the underlying resource.

Processes and Guidelines

  1. Ontologies will be verified for logical consistency as part of the QA process
  2. When refactoring of an ontology is required, the new structure will be created in parallel with the old structure and equivalencies asserted between new and old elements where equivalencies exist.
  3. When a new version of a resource is created, equivalency assertions will be made from the “complex” representations in the old ontology to equivalent structures in the new ontology.

Ontology requirements

  • Lloyd: Grahame, I'm not sure this describes the ontology as covered above. Based on the principles, I would say "Ontology" corresponds to the RIM mappings and maybe RDF expression. The stuff below doesn't really hold.

Each data element within the ontology will include the following definitional elements:

  • Descriptive label (English, ideally unique, user intuitive, domain agnostic)
  • Code
  • Synonym codes (includes GUIDs from local extensions as well as superseded codes, should that ever be necessary)
  • Synonym labels (Other names, potentially including non-English translations)
  • Definition (English, following good practices, including examples) Need to support translations to other languages at some point.
  • Additional notes (todo, comments, usage notes)
  • Value Domain
  • Owning concept (for nested structures)
  • RIM path and constraints (identifies the path from the owning concept to this element with additional constraints as needed)
  • Terminology mappings (SNOMED, LOINC, etc.)

Defining Resources

One of the key challenges with FHIR is the governance process for managing resource creation and maintenance. This section proposes processes and guidelines for doing this.

Who can define resources

Technically anyone can create resources, however only HL7 International and (in limited circumstances agreed by HL7 International), HL7 affiliates and other approved SDOs can create resources that can be referenced in HL7 Specifications. At the HL7 International level, the decision around the creation of new resources is managed via project request to the FHIR Governance Board.

Affiliates wishing to create resource definitions are encouraged to first propose the resource at the HL7 International level and only proceed with local definition where there is either no interest or insufficient bandwidth to construct the resource. The potential for eventually migrating affiliate resource definitions to the international level should be kept in mind.

In addition, some resource definitions could potentially be created by other SDOs. The management of such relationships and the assignment of official HL7 status to resource definitions maintained by other SDOs and vice versa will need to be coordinated through inter-organizational agreements. In addition, the maintenance of HL7-authored resource definitions may be assisted through contributions from other SDOs both on a formal and informal basis.

In cases where resources intended for use in official HL7 standards are created by groups other than HL7 International, coordination is required to ensure resource names are constructed in a way that avoids name collisions.

When are new resources defined?

Within HL7, acceptance of a proposed resource will be based on a number of criteria, including the following:

Does the resource represent a well understood and “important” concept in the business of healthcare?

Resources should be the key things that healthcare information communications deal with. They should be labeled with terms that will be easily recognized by domain experts and should ideally be consistent in nature across national and care boundaries. (Note that care should be taken in naming resources to ensure that the resource will be easily recognized by the business community and unlikely to be confused for other meanings of the same label. E.g. is “Application” a software system or an enrollment request?)

Is there a requirement for standardization of the content represented by the resource?

Creation of a resource entails a significant development and maintenance effort on the HL7 organization. This effort should only be taken in circumstances where there is expected to be sufficient uptake of specifications using the resource to justify that effort.

Does the proposed resource overlap with content of existing resources?

Overlap can occur in several ways:

  • Concepts can exist at different levels of generalization (e.g. Outbreak/Public Health Case/Observation/Act; Person/LivingSubject/Entity)
  • Concepts can represent different business perspectives/restrictions of a general area (e.g. chemistry, pathology, microbiology and genetic views of lab results)
  • Concepts can be shared at different levels of detail (e.g. medication summary vs. full medication detail)
  • Concepts can reference other concepts (e.g. Patient referencing the provider or organization they’re a patient of)

As a general rule, overlap is not permitted. If a given piece of information would be expected to be communicated in one resource, it should not be present in another.

Is the proposed resource appropriately sized?

Resources are intended to be created for healthcare concepts that have a descent “heft” to them. At the same time, resources should not be gigantic constructs that include everything and the kitchen sink too. For example, a resource for “names” would be considered too fine-grained. On the other hand, a resource intended to contain the full structure of a clinical trial without references to other resources would be much too large. From a numbers perspective a range of 20 data elements to around 100 data elements is probably about right. However, this is a guideline that is flexible based on other criteria.

Is it reasonable to expect the objects represented by the resource to be maintained with distinct, reliable, unique identifiers?

To be manipulated or referenced, resources must be identified. While the identifiers used to link and manipulate resources will be internal “technical” identifiers not intended for human display or data-entry. However, almost all resources will also have corresponding “business” identifiers intended for human use and exposure. If a concept doesn’t naturally have a concept of having an identifier, it may not be a good candidate for being a distinct resource.

Is the proposed resource one that makes sense to perform CRUD operations on as a single unit?

Resource objects are expected to be manipulated independently. It should make sense to create, query, update and delete them on their own, independent of other resources. Many of them will tend to have their own independent state machines. Concepts with tight coupling to other resources might not be candidates to be resources themselves.

Is the content of the resource coherent?

Definitions of resources referencing or containing data from numerous different domains are susceptible to change and unneccessarily require knowledge of all domains referenced. They will be hard to document and implement. Like in any good design, we must strive for high cohesion and low coupling.



How do we minimize the need for distinct resource definitions?

To ensure the FHIR process is manageable, there’s a need to control the number of resources created. This means ensuring that resource definitions are created in a manner that is reusable, scalable and extensible. Resource construction guidelines that affect reusability, scalability and extensibility include:

  1. Ensure that the base resource definition enforces requirements that would reasonably be expected of the simplest of systems.
  2. Include additional features that would reasonably be expected of most systems. (If 80% or more of systems that support the resource are reasonably expected to support the element, it should be part of the resource definition.)
  3. Do not include (in the wire format) features that would be used by a very small percentage of systems or only used in limited environments (e.g. only one country, only clients of a single government agency)
  4. However, ensure that “rare” requirements have an adequate representation in the ontology so they can be easily represented as extensions.
  5. Resources should be constructed, named and populated an international and domain-agnostic manner. I.e. Requirements of all participating countries should be considered and requirements that are shared by multiple countries should be represented in a generic manner.
  6. Resource names and property names should include a synonym list that makes is easy to discover domain-specific and country-specific terms.

How are resources vetted and approved?

Resources will generally be assigned to a single Work Group. Discussion on the content, names, mappings, etc. will be made by that workgroup. Changes to resources will be approved as a single release subject to normative ballot and published as part of a normative edition on an annual basis.

Defining Extensions

A key premise of FHIR is that it tries to do simple things simply. This means that the core structure can’t handle every potential use-case or esoteric requirement as part of a resource’s wire format. For requirements not handled by the wire format, the extension mechanism is used. Extensions should be used in the following circumstances:

  • Data elements that are likely to be used in fewer than 80% of implementations of a given resource
  • Data elements that are specific to a particular country or narrow domain

Defining Profiles/Templates


Governance structures