Snapshot 3: Connectathon 32 Base

This page is part of the FHIR Specification (v5.0.0-snapshot3: R5 Snapshot #3, to support Connectathon 32). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3 R2

8.17 Resource Substance - Content

Biomedical Research and Regulation icon Work GroupMaturity Level: 2 Trial UseSecurity Category: Business Compartments: Not linked to any defined compartments

A homogeneous material with a definite composition.

8.17.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.17.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.17.3 References to this Resource

8.17.4 Resource Content

Structure

Name iconFlags iconCard. iconType iconDescription & Constraints icondoco icon
.. Substance TUDomainResourceA homogeneous material with a definite composition

Elements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
... identifier Σ0..*IdentifierUnique identifier

... instance ?!Σ1..1booleanIs this an instance of a substance or a kind of one
... status ?!Σ0..1codeactive | inactive | entered-in-error
FHIRSubstanceStatus (Required)
... code Σ1..1CodeableReference(SubstanceDefinition)What substance this is
Substance Code (Example)
... description Σ0..1stringTextual description of the substance, comments
... expiry Σ0..1dateTimeWhen no longer valid to use
... quantity Σ0..1SimpleQuantityAmount of substance in the package
... ingredient Σ0..*BackboneElementComposition information about the substance

.... quantity Σ0..1RatioOptional amount (concentration)
.... substance[x] Σ1..1A component of the substance
Substance Code (Example)
..... substanceCodeableConceptCodeableConcept
..... substanceReferenceReference(Substance)

doco Documentation for this format icon

See the Extensions for this resource

UML Diagram (Legend)

Substance (DomainResource)Unique identifier for the substance. For an instance, an identifier associated with the package/container (usually a label affixed directly)identifier : Identifier [0..*]A boolean to indicate if this an instance of a substance or a kind of one (a definition) (this element modifies the meaning of other elements)instance : boolean [1..1]A code to indicate if the substance is actively used (this element modifies the meaning of other elements)status : code [0..1] « null (Strength=Required)FHIRSubstanceStatus! »A code that classifies the general type of substance. This is used for searching, sorting and display purposescategory : CodeableConcept [0..*] « null (Strength=Extensible)SubstanceCategoryCodes+ »A code (or set of codes) that identify this substancecode : CodeableReference [1..1] « SubstanceDefinition; null (Strength=Example)SubstanceCode?? »A description of the substance - its appearance, handling requirements, and other usage notesdescription : string [0..1]When the substance is no longer valid to use. For some substances, a single arbitrary date is used for expiryexpiry : dateTime [0..1]The amount of the substancequantity : Quantity(SimpleQuantity) [0..1]IngredientThe amount of the ingredient in the substance - a concentration ratioquantity : Ratio [0..1]Another substance that is a component of this substancesubstance[x] : DataType [1..1] « CodeableConcept|Reference(Substance); null (Strength=Example) SubstanceCode?? »A substance can be composed of other substancesingredient[0..*]

XML Template

<Substance xmlns="http://hl7.org/fhir"> doco
 <!-- 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="[string]"/><!-- 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>

Turtle Template

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


[ 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:Substance.identifier [ Identifier ], ... ; # 0..* Unique identifier
  fhir:Substance.instance [ boolean ]; # 1..1 Is this an instance of a substance or a kind of one
  fhir:Substance.status [ code ]; # 0..1 active | inactive | entered-in-error
  fhir:Substance.category [ CodeableConcept ], ... ; # 0..* What class/type of substance this is
  fhir:Substance.code [ CodeableReference(SubstanceDefinition) ]; # 1..1 What substance this is
  fhir:Substance.description [ string ]; # 0..1 Textual description of the substance, comments
  fhir:Substance.expiry [ dateTime ]; # 0..1 When no longer valid to use
  fhir:Substance.quantity [ Quantity(SimpleQuantity) ]; # 0..1 Amount of substance in the package
  fhir:Substance.ingredient [ # 0..* Composition information about the substance
    fhir:Substance.ingredient.quantity [ Ratio ]; # 0..1 Optional amount (concentration)
    # Substance.ingredient.substance[x] : 1..1 A component of the substance. One of these 2
      fhir:Substance.ingredient.substanceCodeableConcept [ CodeableConcept ]
      fhir:Substance.ingredient.substanceReference [ Reference(Substance) ]
  ], ...;
]

Changes since R4

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
  • Now marked as Modifier
Substance.code
  • Type changed from CodeableConcept to CodeableReference
  • Type changed from CodeableConcept to CodeableReference
Substance.expiry
  • Added Element
Substance.quantity
  • Added Element
Substance.instance.identifier
  • deleted
Substance.instance.expiry
  • deleted
Substance.instance.quantity
  • deleted

See the Full Difference for further information

This analysis is available as XML or JSON.

See R3 <--> R4 Conversion Maps (status = 6 tests that all execute ok. All tests pass round-trip testing and 1 r3 resources are invalid (0 errors).)

Structure

Name iconFlags iconCard. iconType iconDescription & Constraints icondoco icon
.. Substance TUDomainResourceA homogeneous material with a definite composition

Elements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
... identifier Σ0..*IdentifierUnique identifier

... instance ?!Σ1..1booleanIs this an instance of a substance or a kind of one
... status ?!Σ0..1codeactive | inactive | entered-in-error
FHIRSubstanceStatus (Required)
... code Σ1..1CodeableReference(SubstanceDefinition)What substance this is
Substance Code (Example)
... description Σ0..1stringTextual description of the substance, comments
... expiry Σ0..1dateTimeWhen no longer valid to use
... quantity Σ0..1SimpleQuantityAmount of substance in the package
... ingredient Σ0..*BackboneElementComposition information about the substance

.... quantity Σ0..1RatioOptional amount (concentration)
.... substance[x] Σ1..1A component of the substance
Substance Code (Example)
..... substanceCodeableConceptCodeableConcept
..... substanceReferenceReference(Substance)

doco Documentation for this format icon

See the Extensions for this resource

UML Diagram (Legend)

Substance (DomainResource)Unique identifier for the substance. For an instance, an identifier associated with the package/container (usually a label affixed directly)identifier : Identifier [0..*]A boolean to indicate if this an instance of a substance or a kind of one (a definition) (this element modifies the meaning of other elements)instance : boolean [1..1]A code to indicate if the substance is actively used (this element modifies the meaning of other elements)status : code [0..1] « null (Strength=Required)FHIRSubstanceStatus! »A code that classifies the general type of substance. This is used for searching, sorting and display purposescategory : CodeableConcept [0..*] « null (Strength=Extensible)SubstanceCategoryCodes+ »A code (or set of codes) that identify this substancecode : CodeableReference [1..1] « SubstanceDefinition; null (Strength=Example)SubstanceCode?? »A description of the substance - its appearance, handling requirements, and other usage notesdescription : string [0..1]When the substance is no longer valid to use. For some substances, a single arbitrary date is used for expiryexpiry : dateTime [0..1]The amount of the substancequantity : Quantity(SimpleQuantity) [0..1]IngredientThe amount of the ingredient in the substance - a concentration ratioquantity : Ratio [0..1]Another substance that is a component of this substancesubstance[x] : DataType [1..1] « CodeableConcept|Reference(Substance); null (Strength=Example) SubstanceCode?? »A substance can be composed of other substancesingredient[0..*]

XML Template

<Substance xmlns="http://hl7.org/fhir"> doco
 <!-- 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="[string]"/><!-- 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>

Turtle Template

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


[ 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:Substance.identifier [ Identifier ], ... ; # 0..* Unique identifier
  fhir:Substance.instance [ boolean ]; # 1..1 Is this an instance of a substance or a kind of one
  fhir:Substance.status [ code ]; # 0..1 active | inactive | entered-in-error
  fhir:Substance.category [ CodeableConcept ], ... ; # 0..* What class/type of substance this is
  fhir:Substance.code [ CodeableReference(SubstanceDefinition) ]; # 1..1 What substance this is
  fhir:Substance.description [ string ]; # 0..1 Textual description of the substance, comments
  fhir:Substance.expiry [ dateTime ]; # 0..1 When no longer valid to use
  fhir:Substance.quantity [ Quantity(SimpleQuantity) ]; # 0..1 Amount of substance in the package
  fhir:Substance.ingredient [ # 0..* Composition information about the substance
    fhir:Substance.ingredient.quantity [ Ratio ]; # 0..1 Optional amount (concentration)
    # Substance.ingredient.substance[x] : 1..1 A component of the substance. One of these 2
      fhir:Substance.ingredient.substanceCodeableConcept [ CodeableConcept ]
      fhir:Substance.ingredient.substanceReference [ Reference(Substance) ]
  ], ...;
]

Changes since Release 4

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
  • Now marked as Modifier
Substance.code
  • Type changed from CodeableConcept to CodeableReference
  • Type changed from CodeableConcept to CodeableReference
Substance.expiry
  • Added Element
Substance.quantity
  • Added Element
Substance.instance.identifier
  • deleted
Substance.instance.expiry
  • deleted
Substance.instance.quantity
  • deleted

See the Full Difference for further information

This analysis is available as XML or JSON.

See R3 <--> R4 Conversion Maps (status = 6 tests that all execute ok. All tests pass round-trip testing and 1 r3 resources are invalid (0 errors).)

 

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

8.17.4.1 Terminology Bindings

PathDefinitionTypeReference
Substance.status

A code to indicate if the substance is actively used.

RequiredFHIRSubstanceStatus
Substance.category

Substance category codes

ExtensibleSubstanceCategoryCodes
Substance.code

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

ExampleSubstanceCode
Substance.ingredient.substance[x]

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

ExampleSubstanceCode

8.17.5 Search Parameters

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

NameTypeDescriptionExpressionIn Common
categorytokenThe category of the substanceSubstance.category
codetokenThe code of the substance or ingredientSubstance.code.concept | (Substance.ingredient.substance as CodeableConcept)
code-referencereferenceA reference to the defining substanceSubstance.code.reference
expirydateExpiry date of package or container of substanceSubstance.expiry
identifiertokenUnique identifier for the substanceSubstance.identifier
quantityquantityAmount of substance in the packageSubstance.quantity
statustokenactive | inactive | entered-in-errorSubstance.status
substance-referencereferenceA component of the substance(Substance.ingredient.substance as Reference)
(Substance)