R4 Ballot #2 (Mixed Normative/Trial use)

This page is part of the FHIR Specification (v3.5.0: R4 Ballot #2). 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

Orders and Observations

Work Group

Maturity Level: 2

Trial Use

Compartments: Not linked to any defined compartments

A homogeneous material with a definite composition.

8.17.1 Scope and Usage

This resource allows for a material to be represented. The resource can be used to represent either a kind of a substance - e.g. a formulation commonly used for treating patients, or it can be used to describe a particular package of a known substance (e.g. bottle, jar, packet).

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

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 is referenced by ActivityDefinition, AdverseEvent, BiologicallyDerivedProduct, CarePlan, ChargeItem, ChargeItemDefinition, Contract, Group, Medication, MedicationKnowledge, MedicinalProductClinicals, MedicinalProductContraindication, MedicinalProductIndication, Procedure, Specimen, SpecimenDefinition, itself, SupplyDelivery and SupplyRequest

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
status	?!Σ	0..1	code	active \| inactive \| entered-in-error FHIRSubstanceStatus (Required)
category	Σ	0..*	CodeableConcept	What class/type of substance this is Substance Category Codes (Extensible)
code	Σ	1..1	CodeableConcept	What substance this is Substance Code (Example)
description	Σ	0..1	string	Textual description of the substance, comments
instance	Σ	0..*	BackboneElement	If this describes a specific package/container of the substance
identifier	Σ	0..1	Identifier	Identifier of the package/container
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 Substance Code (Example)
substanceCodeableConcept			CodeableConcept
substanceReference			Reference(Substance)
Documentation for this format

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>
 <status value="[code]"/><!-- 0..1 active | inactive | entered-in-error -->
 <category><!-- 0..* CodeableConcept What class/type of substance this is --></category>
 <code><!-- 1..1 CodeableConcept What substance this is --></code>
 <description value="[string]"/><!-- 0..1 Textual description of the substance, comments -->
 <instance>  <!-- 0..* If this describes a specific package/container of the substance -->
  <identifier><!-- 0..1 Identifier Identifier of the package/container --></identifier>
  <expiry value="[dateTime]"/><!-- 0..1 When no longer valid to use -->
  <quantity><!-- 0..1 Quantity(SimpleQuantity) Amount of substance in the package --></quantity>
 </instance>
 <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
  "status" : "<code>", // active | inactive | entered-in-error
  "category" : [{ CodeableConcept }], // What class/type of substance this is
  "code" : { CodeableConcept }, // R!  What substance this is
  "description" : "<string>", // Textual description of the substance, comments
  "instance" : [{ // If this describes a specific package/container of the substance
    "identifier" : { Identifier }, // Identifier of the package/container
    "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:Substance.identifier [ Identifier ], ... ; # 0..* Unique identifier
  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 [ CodeableConcept ]; # 1..1 What substance this is
  fhir:Substance.description [ string ]; # 0..1 Textual description of the substance, comments
  fhir:Substance.instance [ # 0..* If this describes a specific package/container of the substance
    fhir:Substance.instance.identifier [ Identifier ]; # 0..1 Identifier of the package/container
    fhir:Substance.instance.expiry [ dateTime ]; # 0..1 When no longer valid to use
    fhir:Substance.instance.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 R3

Substance

Substance.status

Now marked as Modifier

Substance.ingredient.substance[x]

Remove Reference(Substance), Add Reference(Substance)

See the Full Difference for further information

This analysis is available as XML or JSON.

See R3 <--> R4 Conversion Maps (status = 6 tests of which 1 fail to execute. 5 fail round-trip testing and 5 r3 resources are invalid (0 errors).)

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
status	?!Σ	0..1	code	active \| inactive \| entered-in-error FHIRSubstanceStatus (Required)
category	Σ	0..*	CodeableConcept	What class/type of substance this is Substance Category Codes (Extensible)
code	Σ	1..1	CodeableConcept	What substance this is Substance Code (Example)
description	Σ	0..1	string	Textual description of the substance, comments
instance	Σ	0..*	BackboneElement	If this describes a specific package/container of the substance
identifier	Σ	0..1	Identifier	Identifier of the package/container
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 Substance Code (Example)
substanceCodeableConcept			CodeableConcept
substanceReference			Reference(Substance)
Documentation for this format

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>
 <status value="[code]"/><!-- 0..1 active | inactive | entered-in-error -->
 <category><!-- 0..* CodeableConcept What class/type of substance this is --></category>
 <code><!-- 1..1 CodeableConcept What substance this is --></code>
 <description value="[string]"/><!-- 0..1 Textual description of the substance, comments -->
 <instance>  <!-- 0..* If this describes a specific package/container of the substance -->
  <identifier><!-- 0..1 Identifier Identifier of the package/container --></identifier>
  <expiry value="[dateTime]"/><!-- 0..1 When no longer valid to use -->
  <quantity><!-- 0..1 Quantity(SimpleQuantity) Amount of substance in the package --></quantity>
 </instance>
 <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
  "status" : "<code>", // active | inactive | entered-in-error
  "category" : [{ CodeableConcept }], // What class/type of substance this is
  "code" : { CodeableConcept }, // R!  What substance this is
  "description" : "<string>", // Textual description of the substance, comments
  "instance" : [{ // If this describes a specific package/container of the substance
    "identifier" : { Identifier }, // Identifier of the package/container
    "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:Substance.identifier [ Identifier ], ... ; # 0..* Unique identifier
  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 [ CodeableConcept ]; # 1..1 What substance this is
  fhir:Substance.description [ string ]; # 0..1 Textual description of the substance, comments
  fhir:Substance.instance [ # 0..* If this describes a specific package/container of the substance
    fhir:Substance.instance.identifier [ Identifier ]; # 0..1 Identifier of the package/container
    fhir:Substance.instance.expiry [ dateTime ]; # 0..1 When no longer valid to use
    fhir:Substance.instance.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 3

Substance

Substance.status

Now marked as Modifier

Substance.ingredient.substance[x]

Remove Reference(Substance), Add Reference(Substance)

See the Full Difference for further information

This analysis is available as XML or JSON.

See R3 <--> R4 Conversion Maps (status = 6 tests of which 1 fail to execute. 5 fail round-trip testing and 5 r3 resources are invalid (0 errors).)

See the Profiles & Extensions and the alternate definitions: Master Definition XML + JSON, XML Schema/Schematron + JSON Schema, ShEx (for Turtle) + see the extensions & the dependency analysis

8.17.3.1 Terminology Bindings

Path	Definition	Type	Reference
Substance.status	A code to indicate if the substance is actively used.	Required	FHIRSubstanceStatus
Substance.category	Category or classification of substance.	Extensible	SubstanceCategoryCodes
Substance.code	Substance codes.	Example	SubstanceCode
Substance.ingredient.substance[x]	Substance Ingredient codes.	Example	SubstanceCode

Path

Definition

Type

Reference

Substance.status

A code to indicate if the substance is actively used.

Required

FHIRSubstanceStatus

Substance.category

Category or classification of substance.

Extensible

SubstanceCategoryCodes

Substance.code

Substance codes.

Example

SubstanceCode

Substance.ingredient.substance[x]

Substance Ingredient codes.

Example

SubstanceCode

8.17.4 Search Parameters

Search parameters for 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 \| (Substance.ingredient.substance as CodeableConcept)
container-identifier	token	Identifier of the package/container	Substance.instance.identifier
expiry	date	Expiry date of package or container of substance	Substance.instance.expiry
identifier	token	Unique identifier for the substance	Substance.identifier
quantity	quantity	Amount of substance in the package	Substance.instance.quantity
status	token	active \| inactive \| entered-in-error	Substance.status
substance-reference	reference	A component of the substance	(Substance.ingredient.substance as Reference) (Substance)