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

FHIR Guide to Designing Resources

From HL7Wiki
Jump to navigation Jump to search



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.

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?

How should resources be named?

Creating resource elements

When does an element qualify for inclusion in core?

When faced with multiple alternative expressions mechanisms, which do we choose?

Where within the nesting structure should an element be added?

When do we create additional "levels" within a resource?

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 “” and “” 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.

What if an element is known by different names in different contexts?

When should an element have a minimum cardinality of 1?

When should an element repeat?

When should the default UML layout be overridden?

Should the order of repeating elements matter?**

When should elements be marked as 'Must Understand'?

What combinations of cardinality and 'Must Understand' are allowed?

Resource element types

What are the criteria for selecting an appropriate data type?

When should an element reference a base data type vs. a profiled data type?

When should content be expressed inline rather than referencing another resource vs. both?

How can a "choice" of elements be expressed?

When should a resource have multiple elements rather than a single element with a choice of types?

When referencing resources, when should a list of allowed resources be enumerated and when should it be left open to Any?


How should bindings be names?

When should a list of codes be referenced vs. a concept domain?

When should an enumeration be supplied vs. references to external codes?

What are the criteria for choosing Binding Strength?

Descriptive Content

What makes for a good Short Name?

What are the criteria for a good Definition?

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


What mappings should be created?

How precise should a mapping be?


What rules should be expressed as invariants?

What should the context be for an invariant?

Can invariants reference elements inside another resource or data type?

How should invariants be named?

Do I need to specify OCL or XPath?

What are the criteria for the English expression of an XPath?

When should an invariant be linked to specific elements?


What events should be created for a resource?

When should an event have multiple request or response resources?

What should go into an even description?

When should an event have follow-ups?

What should go into event description vs. notes?


What search parameters should be included in a resource?

How should search parameters be named?

What should go into a search description?

How should the type of a search parameter be determined?

When should a repeating parameter be handled as union vs. intersection?


How many examples should be created?

How realistic should examples be?

What should examples cover?

Additional documentation

What content should go into the introduction and notes section?

When should content be in the introduction and when in notes?

Where should content go that doesn't easily fit in either place?

Profile Guidance


Extension Guidance