Local Build (LMA-W510)

6.10 Resource ObservationDefinition - Content

The formal description of a single piece of information that can be gathered and reported.

6.10.1 Scope and Usage

This resource covers two major use-cases:

  1. Definitions of types of observations that may be performed, sometimes referred to as "observation master files"
  2. Definitions of "common data elements" that may be used in questionnaires and profiles and potentially mapped to elements in other resources and profiles

The purpose of the first use-case is to allow systems to identify what types of lab orders, diagnostic reports and other types of observations may be requested or performed within a particular organization or other context. An ordering practitioner can query for a list of observation definitions by category name or other criteria and identify which, within a set of similar tests, they wish to be performed.

The focus of the second use-case is standardizing data capture and reporting. By defining standard names, data capture constraints, questions and other characteristics, the data gathered within and across organizations via questionnairs, as part of clinical studies, etc. can be made more consistent. When designing clinical studies, constructing questionnaires, building profiles or performing other tasks that involve determining what data will be captured or exchanged and how, designers can query to find pre-defined data element definitions they can leverage or map to. By encouraging consistency around data element definitions, data types, value sets, string lengths and other constraints, data becomes more easily exchangeable and comparible across systems. This benefits interoperability and clinical research.

The scope covers base capabilities of the ISO 11179 Metadata Registries specification which defines CDEs. It also covers observation definitions by ontologies such as LOINC. The term "observation" is interpretted in its broadest sense as "any element that might be thought of as the 'value' in a name-value pair". So it includes such concepts as patient gender, practitioner address and other data elements that would not typically be captured using the Observation resource.

6.10.2 Boundaries and Relationships

This resource has significant overlap with Profile and Questionnaire.

Profile also defines data elements, however it does so only in the context of constraints or extensions on FHIR resources. As well, Profile typically identifies a number of data elements together in context. ObservationDefinition defines only a single data element and it does so in a manner that is not directly tied to FHIR. Defined data elements might be the value of an Observation, the answer to a question in a Questionnaire, captured as an element in some other resource (Patient, FamilyHistory, etc.) or even used outside FHIR entirely in a CDA document or HL7 v2 specification. Authors of Profiles may leverage (and reference) ObservationDefinitions when defining the data elements with the Profile. (For implementability reasons, the data constraints should still be explictly exposed within the Profile rather than being included "by reference" to the ObservationDefinition.)

Questionnaire can be used to both define questionnaires that can be filled out as well as to capture questionnaire responses. When used for the first purpose, Questionnaire also defines data elements. However, it does so only in the context of a particular questionnaire design. ObservationDefinition is focused on defining data elements independent of use. A single ObservationDefinition might be referenced in numerous Questionnaires, or even potentially in multiple places within a single Questionnaire. This reference might either be implicit or may be explicit through an extension. (For implementability reasons, the data constraints should still be explictly exposed within the Questionnaire rather than being included "by reference" to the ObservationDefinition.)

Note: Extensions on ObservationDefinition that define the characteristics of a data element will typically also be applicable to Profile's ElementDefinition and Questionnaire's Question data element as both are also used to define the characteristics of a data element.

Ballot Issue: Should a shared structure be used in Profile, Questionnaire and ObservationDefinition to capture constraints on data elements, or is it acceptable for them to containue to be maintained in a separate, but "similar" manner?

ObservationDefinition differs from Observation in that it describes what kind of observations can occur, while Observation focuses on a specific observation of a specific subject at a particular time that has occurred.

6.10.3 Resource Content

ObservationDefinition (Resource)The identifier that is used to identify this observation definition when it is referenced in a Profile, Questionnaire or an instance (should be globally unique OID, UUID, or URI)identifier : string 0..1The identifier that is used to identify this version of the observation definition when it is referenced in a Profile, Questionnaire or instance. This is an arbitrary value managed by the definition author manuallyversion : string 0..1Details of the individual or organization who accepts responsibility for publishing the observation definitionpublisher : string 0..1Contact details to assist a user in finding and communicating with the publishertelecom : Contact 0..*A set of terms from external terminologies that may be used to assist with indexing and searching of data element definitionscategory : Coding 0..*A code assigned to the data eleent within a particular terminologycode : Coding 0..*The status of the observation definition (this element modifies the meaning of other elements)status : code 1..1 <<The lifecycle status of a Resource Observation DefinitionResourceObservationDefinitionStatus>>The date that this version of the observation definition was publisheddate : dateTime 0..1The term used by humans to refer to the data element. Should ideally be unique within the context in which the data element is expected to be usedname : string 0..1Provides a complete explanation of the meaning of the data element for human readabilityformal : string 0..1Comments about the use of the element, including notes about how to use the data properly, exceptions to proper use, etccomments : string 0..1Explains why this element is needed and why it's been constrained as it hasrequirements : string 0..1Identifies additional names by which this element might also be knownsynonym : string 0..*An example value for this elementexample[x] : * 0..1Indicates the shortest length that SHALL be supported by conformant instances without truncationmaxLength : integer 0..1TypeRefThe FHIR data type or resource name that is the type for this elementcode : code 1..1 <<The type of an element - one of the FHIR data typesDataType>>Identifies a profile that SHALL hold for resources or datatypes referenced as the type of this element. Can be a local reference - to another structure in this profile, or a reference to a structure in another profileprofile : uri 0..1ConstraintUsed to label the constraint in OCL or in short displays incapable of displaying the full human descriptionname : string 0..1Identifies the impact constraint violation has on the conformance of the instanceseverity : code 1..1 <<SHALL applications comply with this constraint?ConstraintSeverity>>Text that can be used to describe the constraint in messages identifying that the constraint has been violatedhuman : string 1..1XPath expression of constraintxpath : string 1..1BindingA descriptive name for this - can be useful for generating implementation artifactsname : string 1..1If true, then conformant systems may use additional codes or (where the data type permits) text alone to convey concepts not covered by the set of codes identified in the binding. If false, then conformant systems are constrained to the provided codes aloneisExtensible : boolean 1..1Indicates the degree of conformance expectations associated with this bindingconformance : code 0..1 <<Binding conformance for applicationsBindingConformance>>Describes the intended use of this particular set of codesdescription : string 0..1Points to the value set or external definition that identifies the set of codes to be usedreference[x] : uri|Resource(ValueSet) 0..1MappingA URI that identifies the specification that this mapping is expressed touri : uri 0..1A name for the specification that is being mapped toname : string 0..1Comments about this mapping, including version notes, issues, scope limitations, and other important notes for usagecomments : string 0..1Expresses what part of the target specification corresponds to this elementmap : string 1..1The data type or resource that the value of this element is permitted to betype1..1Formal constraints such as co-occurrence and other constraints that can be computationally evaluated within the context of an instance of the data elementconstraint0..*Binds to a value set if this element is coded (code, Coding, CodeableConcept)binding0..1Identifies a concept from an external specification that roughly corresponds to this elementmapping0..* 
<ObservationDefinition xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: extension, modifierExtension, language, text, and contained -->
 <identifier value="[string]"/><!-- 0..1 Logical id to reference this profile § -->
 <version value="[string]"/><!-- 0..1 Logical id for this version of the profile § -->
 <publisher value="[string]"/><!-- 0..1 Name of the publisher (Organization or individual) § -->
 <telecom><!-- 0..* Contact Contact information of the publisher § --></telecom>
 <category><!-- 0..* Coding Assist with indexing and finding § --></category>
 <code><!-- 0..* Coding Identifying concept § --></code>
 <status value="[code]"/><!-- 1..1 draft | active | retired § -->
 <date value="[dateTime]"/><!-- 0..1 Date for this version of the observation definition § -->
 <name value="[string]"/><!-- 0..1 Descriptive label for this element definition § -->
 <formal value="[string]"/><!-- 0..1 Full formal definition in human language -->
 <comments value="[string]"/><!-- 0..1 Comments about the use of this element -->
 <requirements value="[string]"/><!-- 0..1 Why is this needed? -->
 <synonym value="[string]"/><!-- 0..* Other names -->
 <type>  <!-- 1..1 Data type and Profile for this element -->
  <code value="[code]"/><!-- 1..1 Name of Data type or Resource -->
  <profile value="[uri]"/><!-- 0..1 Profile.structure to apply -->
 </type>
 <example[x]><!-- 0..1 * Example value: [as defined for type] --></example[x]>
 <maxLength value="[integer]"/><!-- 0..1 Length for strings -->
 <constraint>  <!-- 0..* Condition that must evaluate to true -->
  <name value="[string]"/><!-- 0..1 Short human label -->
  <severity value="[code]"/><!-- 1..1 error | warning -->
  <human value="[string]"/><!-- 1..1 Human description of constraint -->
  <xpath value="[string]"/><!-- 1..1 XPath expression of constraint -->
 </constraint>
 <binding>  <!-- 0..1 ValueSet details if this is coded -->
  <name value="[string]"/><!-- 1..1 Descriptive Name -->
  <isExtensible value="[boolean]"/><!-- ?? 1..1 Can additional codes be used? -->
  <conformance value="[code]"/><!-- ?? 0..1 required | preferred | example -->
  <description value="[string]"/><!-- ?? 0..1 Human explanation of the value set -->
  <reference[x]><!-- ?? 0..1 uri|Resource(ValueSet) Source of value set --></reference[x]>
 </binding>
 <mapping>  <!-- 0..* Map element to another set of definitions -->
  <uri value="[uri]"/><!-- ?? 0..1 Identifies what this mapping refers to -->
  <name value="[string]"/><!-- ?? 0..1 Names what this mapping refers to -->
  <comments value="[string]"/><!-- 0..1 Versions, Issues, Scope limitations etc -->
  <map value="[string]"/><!-- 1..1 Details of the mapping -->
 </mapping>
</ObservationDefinition>

Alternate definitions: Schema/Schematron, Resource Profile

6.10.3.1 Terminology Bindings

PathDefinitionTypeReference
ObservationDefinition.status The lifecycle status of a Resource Observation DefinitionFixedhttp://hl7.org/fhir/resource-observation-def-status
ObservationDefinition.type.code The type of an element - one of the FHIR data typesIncompletehttp://hl7.org/fhir/data-types
ObservationDefinition.constraint.severity SHALL applications comply with this constraint?Fixedhttp://hl7.org/fhir/constraint-severity
ObservationDefinition.binding.conformance Binding conformance for applicationsFixedhttp://hl7.org/fhir/binding-conformance

6.10.3.2 Constraints

  • Inv-7: Binding can only be present for coded elements (xpath: not(exists(f:binding)) or f:type/f:code/@value=('code','Coding','CodeableConcept','Quantity'))
  • Inv-25: Constraint names must be unique. (xpath: count(f:constraint[f:name]) = count(distinct-values(f:constraint/f:name/@value)))
  • Inv-3: On ObservationDefinition.binding: provide either a reference or a description (or both) (xpath on f:ObservationDefinition/f:binding: (exists(f:referenceUri) or exists(f:referenceResource)) or exists(f:description))
  • Inv-14: On ObservationDefinition.binding: Example value sets are always extensible (xpath on f:ObservationDefinition/f:binding: not(f:conformance/value='example' and f:isExtensible.value='false'))
  • Inv-13: On ObservationDefinition.binding.reference[x]: uri SHALL start with http:// or https:// (xpath on f:ObservationDefinition/f:binding/f:reference[x]: starts-with(@value, 'http:') or starts-with(@value, 'https:'))
  • Inv-26: On ObservationDefinition.mapping: Must have at a name or a uri (or both) (xpath on f:ObservationDefinition/f:mapping: exists(f:uri) or exists(f:name))

6.10.3.3 ISO 11179

TODO: explain 11179 conformance

6.10.4 Search Parameters

Search parameters for this resource. The standard parameters also apply. See Searching for more information about searching in REST, messaging, and services.

NameTypeDescriptionPaths
_idtokenThe logical resource id associated with the resource (must be supported by all servers)
_languagetokenThe stated language of the resource
categorytokenA category assigned to the observation definition (server may choose to do subsumption)ObservationDefinition.category
codetokenA code for the observation definition (server may choose to do subsumption)ObservationDefinition.code
datedateThe observation definition publication dateObservationDefinition.date
descriptionstringText search in the description of the observation definitionObservationDefinition.formal
identifiertokenThe identifier of the observation definitionObservationDefinition.identifier
namestringName of the observation definitionObservationDefinition.name
publisherstringName of the publisher of the observation definitionObservationDefinition.publisher
statustokenThe current status of the observation definitionObservationDefinition.status
versiontokenThe version identifier of the observation definitionObservationDefinition.version