FHIR Guide to Designing Resources

Introduction

This section provides guidance in the design of resources, profiles and extensions. It does not answer technical "how to" questions, but rather provides guidance for work groups and other authors in the design decisions they make. For technical instructions on how to define resources and the meaning of various resource and extension properties, refer to FHIR Guide to Authoring Resources.

Design guidance is provided in the form of questions with associated answers. In many cases, the guidance provided is non-binding advice. However, in some cases the answers reflect formally approved methodology which is expected to either be followed or have an exception granted and may be reviewed as part of QA processes. These are clearly marked as "Rule". All rules and many guidelines will also have additional content that provides information on *why* the rule or guideline is in place, referencing the principles and precepts associated with FHIR.

This page is subject to ongoing change as HL7 gains experience in FHIR development and implementation. Feel free to add new questions, guidance on existing questions, etc. This page is curated and managed by the Modelling and Methodology committee who has authority for formal approval the creation and modification of "Rules". If a change is desired to a rule, please add a comment rather than changing the rule directly. The guidelines used to evaluate methodology guidelines can be found in FHIR Methodology Process.

In some cases, methodology questions may also be of interest to implementers. These topics are marked with a "**" and may be migrated into the FHIR specification directly

Todo: Move more content across from Authoring FHIR Resources

Resource Guidance

Creating Resources

When should a new resource be created?

• See FHIR Resource Considerations

Creating resource elements

What if an element qualifies for core based on commonality, but is known to be bad practice?

In some cases, clinical systems will capture information in ways that is known to be flawed or not in keeping with best healthcare practices. In these circumstances, aligning with the 80% means perpetuating a business practice that is known to be problematic. In these circumstances, a Work Group may choose to instead support the more "current"/"best practice" approach to data representation. The primary considerations for making this call is whether it's a reasonable imposition to expect at least 80% of systems to support the new approach in a realistic adoption period (5-10 years). Factors affecting this include how easy or hard it is to migrate from old approach to new, how much added complexity is caused by the new approach and how much benefit to practice and patient care is provided by the change. If the work group agrees to make the change, they should note the exception to the 80% criteria and their justification in the Notes column. Serious consideration should also be given to an extension or set of extensions that support the "old" approach as well.

Are there design patterns for common semantic scenarios?

Yes. Refer to FHIR Design Patterns

Resource element content

How should resource elements be named?

Element names should:

• be lowerCamelCase
• be U.S. English (spelled correctly!)
• be expressed as a noun, with a preceding adjective where necessary to clarify the semantics
• use the "most broadly recognized" industry term for the object that is unlikely to be mistaken for a different element.
• use abbreviations only where extremely well understood by the entire target market. Only the first letter of an abbreviation should be upper-case
• use different names for different elements within the hierarchy unless the semantic is the same in different context. (E.g. using “.name” for “sponsor.name” and “contact.name” is ok if the meaning of “name” is consistent for both sponsor and name.)
• be concise (differentiation of semantics through the name is only necessary with other elements in the resource. Full semantic description is in the definitions.)
• be consistent with naming of similar elements in other resources unless driven by common use of different terminology in industry
• presume no familiarity with other standards (v2, v3, CDA, etc.)
• not include terms whose purpose is to identify the data type of the element

Purpose is to give maximum insight for the unfamiliar developer to "what is this element". Also used for searching. Name length impacts instance size and code readability, so there's a trade-off between semantic precision and ease-of-use.

What order should elements appear in?

Elements should be ordered roughly in terms of importance, with related concepts grouped together.

Resource element types

What are the criteria for selecting an appropriate data type?

General considerations

• What level of discrete data do most systems capture for this element?

I.e. Don't select a complex data type if most systems only capture a string or simple date

• When possible use an existing data type rather than creating your own custom structure within a resource to accomplish the same end. It's important to balance the careful tuning of elements to requirements with the ability to leverage commonly re-used structures.
• If all properties of a data type aren't appropriate/relevant for a use-case, consider profiling the data type in a re-usable way and then referencing the data type with its profile.

Coded vs. non-coded

Codes should be used when computer systems are expected to make decisions on the basis of the data or when the information will be subject to statistical analysis. Examples include decision support, business rule validation, enhanced querying, etc. There is no value to using codes if the data is only for human consumption and there is no need to categorize by the element.

Choice of coding data type

There are 4 data types that support transmission of coded data: code, Choice, Coding and CodeableConcept. Each is intended for use in specific circumstances:

code should only be used when the following conditions are met:

• The code represents a core structural element of the resource
• The element will be bound to a code list that is complete (non-extensible) and required (everyone must use it)
• The element is intended for computing purposes, not human display
• Ideally, the bound codes are human-friendly, expressed in English. I.e. The semantics are evident from looking at the code

This type allows for no translations, display names or original text so it is inappropriate for elements targeted to humans or elements that might need different codes in different implementation environments

Choice should be used when the set of codes bound to the element will vary from instance to instance. I.e. Even within a single Profile, the set of codes available will vary. This generally occurs with surveys and similar situations where the set of codes will vary from question to question.

Choice carries the value set with it. This overhead is only appropriate in circumstances where the value set can't be known from context.

CodeableConcept is the datatype for use in the vast majority of situations involving coded data. It supports multiple translations which allows common instances to be used in situations where different recipients might require different codes. It also allows for migration between code systems over time. Finally, it supports conveying a textual representation of the concept which is important for situations where no appropriate code exists or where the recipient doesn't recognize the code system or wishes to see the full detail of the original concept, not necessarily what was expressible by the selected code.

Coding is used in very limited circumstances, primarily in extensions where there's a need for finer control over the use of translations and text than is provided by the CodeableConcept. Work Groups considering using this type within a resource or within an HL7-defined extension are encouraged to discuss this with either the Vocabulary or Modelling and Methodology Work Groups.

Because this type doesn't support translations or text, it is likely to produce interoperability issues unless used very carefully

Choice of Identifier datatypes

There are 4 data types that can potentially be used to identify things: id, uri and its specializations (oid, sid and uuid), Identifier and HumanId. Each is intended for use in specific circumstances:

id is intended for use within the data types themselves and for "internal" identifiers to FHIR such as referencing another resource. An id is generally not globally unique so it is generally also only useful within a context. Direct use may be appropriate in extensions where a greater degree of control is needed than that offered by the standard data types. For example, specifying a "version" that is expected to be scoped by a companion Identifier element. Work Groups considering using this type within a resource or within an HL7-defined extension are encouraged to discuss this with the MnM Work Group.

uri is also generally intended for use within the data types, though it may appear as an element when communicating network addresses and the complexity of the Contact datatype is inappropriate (see below). Using URIs or one of the specializations for identifiers is only appropriate if a Work Group is 100% confident that all implementers currently and in the future will use a bare URI/OID/UUID/etc. for the identifier rather than the more typical "system + id" approach supported by the Identifier and HumanId types.

Identifier is intended for use in communicating identifiers not generally expected to be seen by humans or at least where the context of the identifier is implicit in the element. Examples might be order numbers, insurance identifiers, etc. The type, effective period, assigner and other metadata should either be irrelevant, implicit in the context or communicated via sibling data elements. In most circumstances, elements with a type of Identifier should have a maximum cardinality of 1. (If multiple repetitions are present, then the context information of the identifier is likely to be ambiguous, at least for human display purposes.)

HumanId is intended for identifiers expected to be displayed to humans where the information about the "kind" of identifier may vary. Frequently HumanId elements will be allowed to repeat.

The HumanId conveys the most information about the identifier and is therefore most amenable to human display.

Encoded data

There are 4 different mechanisms that can be used to convey binary and other encoded data such as images, embedded XML, PDF documents, etc.: Attachment, base64binary, uri and the Binary resource. Each is intended for use in specific circumstances:

Todo

Quantities

Range, integer, decimal, Quantity, Quantity profiles, Ratio

Timing

Schedule, Period, dateTime, date, instant

Contact

uri, Contact

Anything vs. string

Most common for HumanName and Address, but possible for others

Descriptive Content

What makes for a good Short Description?

A short description should:

• Provide an alternate expression of the meaning of the element (i.e. not a repetition of the element name)
• Should be short (<60 characters)
• May be a phrase or an enumeration of allowed codes
  • enumerations should only be provided when
    • there is a single mandatory binding
    • the semantics of the codes are clearly expressed in the code itself
    • there are a small number of codes (no more than 5-6)
  • enumerations should match the spelling and case of the code and be delimited with " | "
  • if there are too many codes to reasonably express all of them within the length limit, use a representative set and put " +" at the end
• Must be in U.S. English
• Must start with upper-case unless an enumeration
• Should use terminology the majority of implementers will find familiar

The purpose of a short description is to provide more information to the reader than is conveyed by the name of the model element while still being quick and easy to read. Starting with an upper-case helps the short description show up well in the XML

What are the criteria for a good Definition?

A good definition:

• Provides additional clarity for the selected name
• Can be easily consumed and understood by the reader. A guideline is that a definition does not exceed 1 paragraph in length though many definitions can be considered complete in a single sentence. Some difficult concepts may however require lengthy discussions but this is best left to comments and examples (see below)
• Is unambiguous
• Allows the reader to understand the definer's intent for the field
• Should be grammatically correct. The definition should be composed of complete, grammatically correct sentences.
• Is not reflexive
  • It should not rephrase the name in a statement, for example a definition for ConcernCode as "A Code value for the Concern" simply repeats the information conveyed in the name. At the very least, a definition provides synonyms for the concepts that comprise the name to allow the reader a better understanding of the definer's intent.

What goes into Definition vs. Requirements vs. Comments vs. Committee Notes?

The following contrasting sections attempt to explain and illustrate what is placed in each of the aforementioned sections:

Definition

A short concise (no more than 1 paragraph) description of the purpose of the described element. Every element will have a definition. (the WHAT)

Requirements

The reason(s) for including the element in the specification. A description of why the element is necessary (and under what conditions). May be documented using formal methodologies for business requirements or simple notes. Not all element will have a requirements discussion. (the WHY and the WHEN)

Comments

The thought processes and design ideas/constraints that went into the creation/definition of the element. The area is also suitable for detailed discussion on the element including such topics as background and use. This section can also be used to augment the definition.

Committee Notes

There could be much overlap between Comments and Committee Notes. Essentially, Comments provide additional information about the element whereas Committee Notes document the process, decisions, and recommendations of the responsible Work Group. The Committee Notes are often formal in nature.

Profile Guidance

Todo

Extension Guidance

Todo