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.

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

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.

Profile Guidance

Todo

Extension Guidance

Todo