R6 Ballot (2nd Draft)

Publish-box (todo)

8.20 Resource Substance - Content

Biomedical Research and Regulation icon

Work Group

Maturity Level: 2

Trial Use

Security Category: Business

Compartments: No defined compartments

A homogeneous material with a definite composition.

8.20.1 Scope and Usage

This is a base resource that represents raw materials used to represent a packaged or measured amount of a known substance (e.g. bottle, jar, packet, drum) that is not in a consumable form nor associated directly with a patient. For example, the materials used for a medication that are not yet in an administrable form.

The resource can be used to represent either a kind of a substance - e.g. a formulation commonly used for treating patients (a "definitional" use of Substance), or it can be used to describe a particular package of a known substance (an "instance" use of Substance).

The composition of the material can be specified in terms of a mix of other materials, including with precise amounts if required.

A Substance may be identifiable as precise as the specific container it is stored in, while more commonly it would be based on a combination of lot number, quantity, and package type.

8.20.2 Boundaries and Relationships

A medication is a substance that is packaged and used as an administered medication. The medication resource uses the substance resource to represent the actual ingredients of a medication. This resource can represent an instance of a substance or a definition (type, kind) of one. See also the SubstanceDefinition resource, which is purely definitional.

A SubstanceDefinition describes the common characteristics of the substance, including those needed for regulatory agencies.

A NutritionProduct distinguishes from a Substance in that a nutrition product is primary consumable purpose is for its nutritional effect.

A BiologicallyDerivedProduct distinguishes from a Substance in that a BiologicallyDerivedProduct has its origins in a biological entity and needs to carry the source’s characteristics to enable matching and compatibility with the biological target to which it will be transfused or implanted, as well as traceability to the source.

8.20.3 References to this Resource

Structure

Name	Flags	Card.	Type	Description & Constraints
Substance	TU		DomainResource	A homogeneous material with a definite composition Elements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
identifier	Σ	0..*	Identifier	Unique identifier
instance	?!Σ	1..1	boolean	Is this an instance of a substance or a kind of one
status	?!Σ	0..1	code	active \| inactive \| entered-in-error Binding: FHIRSubstanceStatus (Required)
category	Σ	0..*	CodeableConcept	What class/type of substance this is Binding: Substance Category Codes (Extensible)
code	Σ	1..1	CodeableReference(SubstanceDefinition)	What substance this is Binding: Substance Code (Example)
description	Σ	0..1	markdown	Textual description of the substance, comments
expiry	Σ	0..1	dateTime	When no longer valid to use
quantity	Σ	0..1	SimpleQuantity	Amount of substance in the package
ingredient	Σ	0..*	BackboneElement	Composition information about the substance
quantity	Σ	0..1	Ratio	Optional amount (concentration)
substance[x]	Σ	1..1		A component of the substance Binding: Substance Code (Example)
substanceCodeableConcept			CodeableConcept
substanceReference			Reference(Substance)
Documentation for this format

See the Extensions for this resource

UML Diagram (Legend)

XML Template

<Substance xmlns="http://hl7.org/fhir"> 
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <identifier><!-- 0..* Identifier Unique identifier --></identifier>
 <instance value="[boolean]"/><!-- 1..1 Is this an instance of a substance or a kind of one -->
 <status value="[code]"/><!-- 0..1 active | inactive | entered-in-error -->
 <category><!-- 0..* CodeableConcept What class/type of substance this is --></category>
 <code><!-- 1..1 CodeableReference(SubstanceDefinition) What substance this is --></code>
 <description value="[markdown]"/><!-- 0..1 Textual description of the substance, comments -->
 <expiry value="[dateTime]"/><!-- 0..1 When no longer valid to use -->
 <quantity><!-- 0..1 Quantity(SimpleQuantity) Amount of substance in the package --></quantity>
 <ingredient>  <!-- 0..* Composition information about the substance -->
  <quantity><!-- 0..1 Ratio Optional amount (concentration) --></quantity>
  <substance[x]><!-- 1..1 CodeableConcept|Reference(Substance) A component of the substance --></substance[x]>
 </ingredient>
</Substance>

JSON Template

{
  "resourceType" : "Substance",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "identifier" : [{ Identifier }], // Unique identifier
  "instance" : <boolean>, // R!  Is this an instance of a substance or a kind of one
  "status" : "<code>", // active | inactive | entered-in-error
  "category" : [{ CodeableConcept }], // What class/type of substance this is
  "code" : { CodeableReference(SubstanceDefinition) }, // R!  What substance this is
  "description" : "<markdown>", // Textual description of the substance, comments
  "expiry" : "<dateTime>", // When no longer valid to use
  "quantity" : { Quantity(SimpleQuantity) }, // Amount of substance in the package
  "ingredient" : [{ // Composition information about the substance
    "quantity" : { Ratio }, // Optional amount (concentration)
    // substance[x]: A component of the substance. One of these 2:
    "substanceCodeableConcept" : { CodeableConcept },
    "substanceReference" : { Reference(Substance) }
  }]
}

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .


[ a fhir:Substance;
  fhir:nodeRole fhir:treeRoot; # if this is the parser root

  # from Resource: .id, .meta, .implicitRules, and .language
  # from DomainResource: .text, .contained, .extension, and .modifierExtension
  fhir:identifier  ( [ Identifier ] ... ) ; # 0..* Unique identifier
  fhir:instance [ boolean ] ; # 1..1 Is this an instance of a substance or a kind of one
  fhir:status [ code ] ; # 0..1 active | inactive | entered-in-error
  fhir:category  ( [ CodeableConcept ] ... ) ; # 0..* What class/type of substance this is
  fhir:code [ CodeableReference(SubstanceDefinition) ] ; # 1..1 What substance this is
  fhir:description [ markdown ] ; # 0..1 Textual description of the substance, comments
  fhir:expiry [ dateTime ] ; # 0..1 When no longer valid to use
  fhir:quantity [ Quantity(SimpleQuantity) ] ; # 0..1 Amount of substance in the package
  fhir:ingredient ( [ # 0..* Composition information about the substance
    fhir:quantity [ Ratio ] ; # 0..1 Optional amount (concentration)
    # substance[x] : 1..1 A component of the substance. One of these 2
      fhir:substance [  a fhir:CodeableConcept ; CodeableConcept ]
      fhir:substance [  a fhir:Reference ; Reference(Substance) ]
  ] ... ) ;
]

Changes from both R4 and R4B

Substance

Substance.instance

Min Cardinality changed from 0 to 1
Max Cardinality changed from * to 1
Type changed from BackboneElement to boolean
Now marked as Modifier

Substance.code

Type changed from CodeableConcept to CodeableReference

Substance.description

Type changed from string to markdown

Substance.expiry

Moved from Substance.instance to Substance

Substance.quantity

Moved from Substance.instance to Substance

Substance.instance.identifier

Deleted (-> Substance.instance.identifier)

See the Full Difference for further information

This analysis is available for R4 as XML or JSON and for R4B as XML or JSON.

Structure

Name	Flags	Card.	Type	Description & Constraints
Substance	TU		DomainResource	A homogeneous material with a definite composition Elements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
identifier	Σ	0..*	Identifier	Unique identifier
instance	?!Σ	1..1	boolean	Is this an instance of a substance or a kind of one
status	?!Σ	0..1	code	active \| inactive \| entered-in-error Binding: FHIRSubstanceStatus (Required)
category	Σ	0..*	CodeableConcept	What class/type of substance this is Binding: Substance Category Codes (Extensible)
code	Σ	1..1	CodeableReference(SubstanceDefinition)	What substance this is Binding: Substance Code (Example)
description	Σ	0..1	markdown	Textual description of the substance, comments
expiry	Σ	0..1	dateTime	When no longer valid to use
quantity	Σ	0..1	SimpleQuantity	Amount of substance in the package
ingredient	Σ	0..*	BackboneElement	Composition information about the substance
quantity	Σ	0..1	Ratio	Optional amount (concentration)
substance[x]	Σ	1..1		A component of the substance Binding: Substance Code (Example)
substanceCodeableConcept			CodeableConcept
substanceReference			Reference(Substance)
Documentation for this format

See the Extensions for this resource

UML Diagram (Legend)

XML Template

<Substance xmlns="http://hl7.org/fhir"> 
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <identifier><!-- 0..* Identifier Unique identifier --></identifier>
 <instance value="[boolean]"/><!-- 1..1 Is this an instance of a substance or a kind of one -->
 <status value="[code]"/><!-- 0..1 active | inactive | entered-in-error -->
 <category><!-- 0..* CodeableConcept What class/type of substance this is --></category>
 <code><!-- 1..1 CodeableReference(SubstanceDefinition) What substance this is --></code>
 <description value="[markdown]"/><!-- 0..1 Textual description of the substance, comments -->
 <expiry value="[dateTime]"/><!-- 0..1 When no longer valid to use -->
 <quantity><!-- 0..1 Quantity(SimpleQuantity) Amount of substance in the package --></quantity>
 <ingredient>  <!-- 0..* Composition information about the substance -->
  <quantity><!-- 0..1 Ratio Optional amount (concentration) --></quantity>
  <substance[x]><!-- 1..1 CodeableConcept|Reference(Substance) A component of the substance --></substance[x]>
 </ingredient>
</Substance>

JSON Template

{
  "resourceType" : "Substance",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "identifier" : [{ Identifier }], // Unique identifier
  "instance" : <boolean>, // R!  Is this an instance of a substance or a kind of one
  "status" : "<code>", // active | inactive | entered-in-error
  "category" : [{ CodeableConcept }], // What class/type of substance this is
  "code" : { CodeableReference(SubstanceDefinition) }, // R!  What substance this is
  "description" : "<markdown>", // Textual description of the substance, comments
  "expiry" : "<dateTime>", // When no longer valid to use
  "quantity" : { Quantity(SimpleQuantity) }, // Amount of substance in the package
  "ingredient" : [{ // Composition information about the substance
    "quantity" : { Ratio }, // Optional amount (concentration)
    // substance[x]: A component of the substance. One of these 2:
    "substanceCodeableConcept" : { CodeableConcept },
    "substanceReference" : { Reference(Substance) }
  }]
}

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .


[ a fhir:Substance;
  fhir:nodeRole fhir:treeRoot; # if this is the parser root

  # from Resource: .id, .meta, .implicitRules, and .language
  # from DomainResource: .text, .contained, .extension, and .modifierExtension
  fhir:identifier  ( [ Identifier ] ... ) ; # 0..* Unique identifier
  fhir:instance [ boolean ] ; # 1..1 Is this an instance of a substance or a kind of one
  fhir:status [ code ] ; # 0..1 active | inactive | entered-in-error
  fhir:category  ( [ CodeableConcept ] ... ) ; # 0..* What class/type of substance this is
  fhir:code [ CodeableReference(SubstanceDefinition) ] ; # 1..1 What substance this is
  fhir:description [ markdown ] ; # 0..1 Textual description of the substance, comments
  fhir:expiry [ dateTime ] ; # 0..1 When no longer valid to use
  fhir:quantity [ Quantity(SimpleQuantity) ] ; # 0..1 Amount of substance in the package
  fhir:ingredient ( [ # 0..* Composition information about the substance
    fhir:quantity [ Ratio ] ; # 0..1 Optional amount (concentration)
    # substance[x] : 1..1 A component of the substance. One of these 2
      fhir:substance [  a fhir:CodeableConcept ; CodeableConcept ]
      fhir:substance [  a fhir:Reference ; Reference(Substance) ]
  ] ... ) ;
]

Changes from both R4 and R4B

Substance

Substance.instance

Min Cardinality changed from 0 to 1
Max Cardinality changed from * to 1
Type changed from BackboneElement to boolean
Now marked as Modifier

Substance.code

Type changed from CodeableConcept to CodeableReference

Substance.description

Type changed from string to markdown

Substance.expiry

Moved from Substance.instance to Substance

Substance.quantity

Moved from Substance.instance to Substance

Substance.instance.identifier

Deleted (-> Substance.instance.identifier)

See the Full Difference for further information

This analysis is available for R4 as XML or JSON and for R4B as XML or JSON.

Additional definitions: Master Definition XML + JSON, XML Schema/Schematron + JSON Schema, ShEx (for Turtle) + see the extensions, the spreadsheet version & the dependency analysis

8.20.4.1 Terminology Bindings

Path	ValueSet	Type	Documentation
Substance.status	FHIRSubstanceStatus	Required	A code to indicate if the substance is actively used.
Substance.category	SubstanceCategoryCodes	Extensible	Substance category codes
Substance.code	SubstanceCode	Example	This value set contains concept codes for specific substances. It includes codes from SNOMED where concept is-a 105590001 (Substance (substance))
Substance.ingredient.substance[x]	SubstanceCode	Example	This value set contains concept codes for specific substances. It includes codes from SNOMED where concept is-a 105590001 (Substance (substance))

Path

ValueSet

Type

Documentation

Substance.status

FHIRSubstanceStatus

Required

A code to indicate if the substance is actively used.

Substance.category

SubstanceCategoryCodes

Extensible

Substance category codes

Substance.code

SubstanceCode

Example

This value set contains concept codes for specific substances. It includes codes from SNOMED icon where concept is-a 105590001 (Substance (substance))

Substance.ingredient.substance[x]

SubstanceCode

Example

This value set contains concept codes for specific substances. It includes codes from SNOMED icon where concept is-a 105590001 (Substance (substance))

8.20.5 Search Parameters

Search parameters for this resource. See also the full list of search parameters for this resource, and check the Extensions registry for search parameters on extensions related to this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.

Name	Type	Description	Expression	In Common
category	token	The category of the substance	Substance.category
code	token	The code of the substance or ingredient	Substance.code.concept \| (Substance.ingredient.substance.ofType(CodeableConcept))
code-reference	reference	A reference to the defining substance	Substance.code.reference
expiry	date	Expiry date of package or container of substance	Substance.expiry
identifier	token	Unique identifier for the substance	Substance.identifier
quantity	quantity	Amount of substance in the package	Substance.quantity
status	token	active \| inactive \| entered-in-error	Substance.status
substance-reference	reference	A component of the substance	(Substance.ingredient.substance.ofType(Reference)) (Substance)