View source for FHIR Guide to Designing Resources

{{FHIR Discussion Page}}
[[Category:Active FHIR Discussion]]
=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 "<b>Rule</b>".  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

<b>Todo:</b> Move more content across from [[Authoring FHIR Resources]]


__TOC__

=Resource Guidance=

==Creating Resources==

===When should a new resource be created?===
* See [[FHIR Resource Considerations]]

===How should resources be named?===


==Creating resource elements==

===When does an element qualify for inclusion in core?===

===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 <b>may</b> 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.

===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 “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

<i>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.</i>

===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?===
'''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: [http://www.hl7.org/fhir/datatypes.htm#code code], [http://www.hl7.org/fhir/datatypes.htm#Choice Choice], [http://www.hl7.org/fhir/datatypes.htm#Coding Coding] and [http://www.hl7.org/fhir/datatypes.htm#CodeableConcept 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

<i>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</i>

'''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.

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

'''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.

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

====Choice of Identifier datatypes====
There are 4 data types that can potentially be used to identify things: [http://www.hl7.org/fhir/datatypes.htm#id id], [http://www.hl7.org/fhir/datatypes.htm#uri uri] and its specializations (oid, sid and uuid), [http://www.hl7.org/fhir/datatypes.htm#Identifier Identifier] and [http://www.hl7.org/fhir/datatypes.htm#HumanId 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.

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

====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.: [http://www.hl7.org/fhir/datatypes.htm#Attachment Attachment], [http://www.hl7.org/fhir/datatypes.htm#base64binary base64binary], [http://www.hl7.org/fhir/datatypes.htm#uri uri] and the [http://www.hl7.org/fhir/atom.htm#Binary 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


===When should multiple types be selected (i.e. a 'choice')?===

===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?===

===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?===


==Vocabulary==

===How should bindings be named?===

===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?===

===When should content (negation, uncertainty, null values) be handled in terminology vs. distinct attributes?===

===When terminology bindings aren't fixed in the core specification, how should a design accommodate the use of different terminologies that may require distinct modelling structures?===

==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

<i>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</i>
===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 elements 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.

As a side note, the name of the element is the Who and the examples provide the How, thus answering all of the essential questions on the specification of an element.

==Mappings==

===What mappings should be created?===

===How precise should a mapping be?===


==Invariants==

===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?===


==Events==

===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?===


==Search==

===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?===


==Examples==

===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=
Todo


=Extension Guidance=
Todo