Release 4 5 Ballot

This page is part of the FHIR Specification (v4.0.1: R4 (v5.0.0-ballot: R5 Ballot - Mixed Normative and STU see ballot notes ) in it's permanent home (it will always be available at this URL). ). 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

Biomedical Research and Regulation Implementable Technology Specifications icon Work Group Maturity Level : 0   Trial Use Normative Security Category Standards Status : Anonymous Normative Compartments : Not linked to any defined compartments

Nucleic acids are defined by three distinct elements: the base, sugar and linkage. Individual substance/moiety IDs will be created for each of these elements. The nucleotide sequence will be always entered in the 5’-3’ direction. 11.24.1 Scope and Usage This XML representation for a resource is referenced by SubstanceSpecification described using this format:


 <name xmlns="http://hl7.org/fhir" (attrA="value")>   doco
   <!-- from Resource: id, meta, implicitRules, and language -->

   <nameA><!-- ?? 1..1 type description of content  --><nameA>
   <nameB[x]><!-- 0..1 type1|type1 description  --></nameB[x]>
   <nameC> <!--  1..* -->
     <nameD><!-- 1..1 type>Relevant elements  --></nameD>
   </nameC>
 <name>

Using this format:

11.24.2 Resource Content
  • Structure UML To build a valid XML JSON Turtle R3 Diff All Structure Name Flags Card. Type Description & Constraints SubstanceNucleicAcid Σ TU DomainResource Nucleic acids are defined instance of a resource, simply replace the contents of the elements and attributes with valid content as described by three distinct elements: the base, sugar cardinality, type rules and linkage. Individual substance/moiety IDs will be created for each of these elements. The nucleotide sequence will be always entered content description found in the 5’-3’ direction Elements defined comment in Ancestors: id , meta , implicitRules , language , text , contained , extension , modifierExtension sequenceType Σ 0..1 CodeableConcept The type of the sequence shall be specified based on a controlled vocabulary numberOfSubunits Σ 0..1 integer The number of linear sequences of nucleotides linked through phosphodiester bonds shall be described. Subunits would be strands of nucleic acids each element
  • Resource and Element names are case-sensitive (though duplicates that differ only in case are tightly associated typically through Watson-Crick base pairing. NOTE: If not specified never defined)
  • Elements must always appear in the reference source, the assumption is that there order documented
  • When an element is 1 subunit areaOfHybridisation Σ 0..1 string The area of hybridisation shall be described if applicable for double stranded RNA or DNA. The number associated with allowed to repeat, the subunit followed by elements are ordered, and the number associated technical infrastructure needs to the residue shall be specified in increasing order. The underscore “” shall be used as separator as follows: “Subunitnumber Residue” oligoNucleotideType Σ 0..1 CodeableConcept (TBC) subunit Σ 0..* BackboneElement Subunits are listed able to access the items in order of decreasing length; sequences of the same length will be ordered by molecular weight; subunits that have identical sequences will be repeated multiple times subunit Σ 0..1 integer right order (see also Cardinality Rules Index for a further description of linear sequences elements with cardinality > 1)
  • A few properties are represented as attributes: values of nucleic acids primitive types in a value attribute, extension URLs in order of decreasing length. Sequences of the same length will be ordered by molecular weight. Subunits that have identical sequences will be repeated and have sequential subscripts sequence Σ 0..1 string Actual nucleotide sequence notation from 5' to 3' end using standard single letter codes. In addition to the base sequence, sugar url attribute on an extension, and type of phosphate or non-phosphate linkage should also be captured length Σ 0..1 integer The length of the sequence shall be captured sequenceAttachment Σ 0..1 Attachment (TBC) fivePrime Σ 0..1 CodeableConcept The nucleotide present at the 5’ terminal shall be specified based id property on a controlled vocabulary. Since elements (but not on resources, where the sequence resource id is represented from an element)
  • Any of the 5' XML elements may have an id attribute to serve as the 3' end, the 5’ prime nucleotide target of an internal reference . The id attribute is the letter at the first position not shown in this format
  • FHIR elements are always in the sequence. A separate representation would be redundant threePrime Σ 0..1 CodeableConcept namespace http://hl7.org/fhir icon The nucleotide present at the 3’ terminal shall be . This is usually specified based as the default namespace on a controlled vocabulary. Since the sequence root element. The only other namespace that occurs in FHIR resources is represented from the 5' XHTML namespace - XHTML is found in most resources
  • Infrastructural elements must appear prior to any other defined child elements in the 3' end, the 5’ prime nucleotide is following order:
    • First, the letter at elements from the last position base resource , in order
    • Second, the sequence. A separate representation would be redundant linkage Σ 0..* BackboneElement The linkages between sugar residues will also be captured connectivity Σ 0..1 string The entity that links the sugar residues together should also be captured for nearly all naturally occurring nucleic acid elements from the linkage is a phosphate group. For many synthetic oligonucleotides phosphorothioate linkages domain resource , in order
  • FHIR elements are often seen. Linkage connectivity is assumed to be 3’-5’. never empty. If the linkage an element is present in the resource, it SHALL have either 3’-3’ or 5’-5’ this should be specified identifier Σ 0..1 Identifier Each linkage will be registered as a fragment and have an ID name Σ 0..1 string value attribute, child elements as defined for its type, or 1 or more extensions Each linkage will
  • Attributes cannot be registered as a fragment and have empty. Either they are absent, or they are present with at least one name. A single name shall be assigned to each linkage residueSite Σ 0..1 string Residues shall be captured as described in 5.3.6.8.3 sugar Σ 0..* BackboneElement 5.3.6.8.1 Sugar ID (Mandatory) identifier Σ 0..1 Identifier The Substance ID character of the sugar or sugar-like component that make up the nucleotide name Σ 0..1 non-whitespace content
  • string Implementers SHOULD trim leading and trailing whitespace before writing and SHOULD trim leading and trailing whitespace when reading attribute values (for XML schema conformance)
  • The name of the sugar or sugar-like component lock icon ( ?? ) denotes that make up the nucleotide residueSite Σ 0..1 string an element defines or is affected by additional rules The residues that contain a given sugar will be captured. The order control its presence and/or content
  • XML comments, processing instructions and formatting are not part of given residues will the contents of a resource
  • There SHALL be captured no DTD references in FHIR resources (because of the 5‘-3‘direction consistent with the base sequences listed above Documentation for this format XXE security exploit icon UML Diagram ( Legend ) SubstanceNucleicAcid
  • XML resources SHALL be exchanged using UTF-8 encoding. Specifying the character encoding using an XML declaration ( DomainResource <?xml encoding="UTF-8" ?> ) The type of the sequence shall be specified based on a controlled vocabulary sequenceType : CodeableConcept [0..1] The number of linear sequences of nucleotides linked through phosphodiester bonds shall is optional but recommended
  • Other processing instructions SHOULD not be described. Subunits would included and SHALL NOT be strands required to properly understand and/or present the data or narrative of nucleic acids that the resource. Applications MAY preserve processing instructions when handling resources, but are tightly associated typically through Watson-Crick base pairing. NOTE: If not specified in the reference source, the assumption is that there is 1 subunit numberOfSubunits : integer [0..1] required to do so
  • The area of hybridisation shall be described if applicable MIME-type for this format is application/fhir+xml .

This page contains some JSON examples for double stranded RNA or DNA. The number associated with the subunit followed by the number associated to purposes of comparison between the residue shall be specified in increasing order. two formats. The underscore “” shall be used as separator as follows: “Subunitnumber Residue” areaOfHybridisation : string [0..1] (TBC) oligoNucleotideType : CodeableConcept [0..1] Subunit Index of linear sequences of nucleic acids in order of decreasing length. Sequences of formats page has a comparison between the same length will be ordered by molecular weight. Subunits that have identical sequences will be repeated XML and have sequential subscripts subunit : integer [0..1] JSON formats .

Actual nucleotide sequence notation from 5' to 3' end using standard single letter codes. In addition to the base sequence, sugar and type of phosphate or non-phosphate linkage should also be captured sequence : string [0..1]

An element that has a controlled vocabulary. Since the sequence is represented from the 5' to maximum cardinality of >1 (e.g. x..* in the 3' end, definitions) may occur more than once in the 5’ prime nucleotide instance. In XML, this is simply done by repeating the letter at the first position in the sequence. A separate representation would be redundant fivePrime : XML element multiple times.

So a CodeableConcept [0..1] The nucleotide present at the 3’ terminal shall be specified based on a controlled vocabulary. Since the sequence is represented from the 5' to the 3' end, the 5’ prime nucleotide is the letter at the last position in the sequence. A separate representation would be redundant threePrime : CodeableConcept [0..1] Linkage The entity that links the sugar residues together should also be captured for nearly all naturally occurring nucleic acid the linkage is a phosphate group. XML like this:


 <code>
   <coding>
     <system value="http://snomed.info/sct"/>
     <code value="104934005"/>
   </coding>
   <coding>
     <system value="http://loinc.org"/>
     <code value="2947-0"/>
   </coding>
 </code>

For many synthetic oligonucleotides phosphorothioate linkages are often seen. Linkage connectivity is assumed to be 3’-5’. If the linkage is either 3’-3’ or 5’-5’ comparison, In JSON, this should be specified connectivity : string [0..1] Each linkage will be registered as a fragment and have is done by using an ID identifier : Identifier [0..1] Each linkage will be registered as a fragment and have at least one name. A single name shall be assigned to each linkage name : string [0..1] Residues shall be captured as described in 5.3.6.8.3 residueSite : string [0..1] Sugar The Substance ID of the sugar or sugar-like component that make up array type, also using the nucleotide identifier : Identifier [0..1] singular name:


{
 "coding": [
   {
     "system" : "http://snomed.info/sct",
     "code" : "104934005"
   },
   {
     "system" : "http://loinc.org",
     "code" : "2947-0"
   }
 ]
}
The name of the sugar or sugar-like component that make up the nucleotide name : string [0..1]

FHIR elements with primitive datatypes are listed represented in order of decreasing length; sequences of the same length will be ordered by molecular weight; subunits that have identical sequences will be repeated multiple times subunit [0..*] an XML Template element with a value attribute.

< <!-- from --> <!-- from --> <</sequenceType> < < <</oligoNucleotideType> < < < < <</sequenceAttachment> <</fivePrime> <</threePrime> < < <</identifier> < < </linkage> < <</identifier> < < </sugar> </subunit> </SubstanceNucleicAcid>
 <code value="abc"/> <!-- code -->
 <date value="1972-11-30"/> <!-- dateTime -->
 <deceased value="false" /> <!-- boolean -->
 <count value="23" />  <!-- integer -->

For comparison, this is represented in JSON Template as

{ "resourceType" : "", // from // from " " " " " " " " " " " " " " " " }], " " " " }] }] }
 "code" : "abc",
 "date" : "1972-11-30",
 "deceased" : false,
 "count" : 23

Turtle Template If the value has an id attribute, or extensions, then these are represented as follows:

@prefix fhir: <http://hl7.org/fhir/> . [ a fhir:; fhir:nodeRole fhir:treeRoot; # if this is the parser root # from # from fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: ], ...; fhir: fhir: fhir: fhir: ], ...; ], ...; ]
<birthDate id="314159" value="1970-03-30" >
  <extension url="http://example.org/fhir/StructureDefinition/text">
    <valueString value="Easter 1970"/>
  </extension>
</birthDate>

Changes since R3 This resource did not exist in Release 2 This analysis is available as XML or The JSON . Structure representation is more complex:

Name Flags Card. Type Description & Constraints
  "birthDate": "1970-03-30",
  "_birthDate": {
    "id": "314159",
    "extension" : [ {
      "url" : "http://example.org/fhir/StructureDefinition/text",
      "valueString" : "Easter 1970"
    }]
  }

Complex datatypes Nucleic acids (types that contain named elements of other types) are defined by three distinct elements: the base, sugar and linkage. Individual substance/moiety IDs will be created represented using an element that containing an element for each of these elements. The nucleotide sequence will be always entered in the 5’-3’ direction Elements defined element in Ancestors: id , meta , implicitRules , language , text , contained , extension , modifierExtension sequenceType Σ 0..1 CodeableConcept The type of the sequence shall be specified based on a controlled vocabulary numberOfSubunits Σ 0..1 integer The number of linear sequences of nucleotides linked through phosphodiester bonds shall be described. Subunits would be strands of nucleic acids that datatype. Complex datatypes can have ids, which are tightly associated typically through Watson-Crick base pairing. NOTE: If not specified represented as id attributes, in the reference source, the assumption is that there is 1 subunit areaOfHybridisation Σ 0..1 string The area of hybridisation shall be same manner as described if applicable for double stranded RNA or DNA. The number associated with primitives. For example:


<Patient xmlns="http://hl7.org/fhir">
  <text>
    <status value="generated" />
    <div xmlns="http://www.w3.org/1999/xhtml"><p>...</p></div>
  </text>
  <name id="f2">
    <use value="official" />
    <given value="Karen" />
    <family id="a2" value="Van" />
  </name>
</Patient>

For comparison, this is represented in JSON as:


{
  "resourceType" : "Patient",
  "name" : [{
    "id" : "f2",
    "use" : "official" ,
    "given" : [ "Karen" ],
    "family" :  "Van",
    "_family" : {"id" : "a2"}
  }],
  "text" : {
    "status" : "generated" ,
    "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>...</p></div>"
  }
}

Things to note here are:

  • All elements are in the subunit followed by http://hl7.org/fhir namespace, except for the number associated to XHTML content
  • The XHTML content in the residue shall be specified div element which is in increasing order. The underscore “” shall be used as separator the Narrative element text is represented directly as follows: “Subunitnumber Residue” oligoNucleotideType Σ 0..1 CodeableConcept (TBC) subunit Σ 0..* BackboneElement Subunits are listed xhtml, with a root <div> element in order of decreasing length; sequences of the same length will be ordered by molecular weight; subunits that have identical sequences will be repeated multiple times subunit xhtml namespace

This specification provides schema definitions for all the same length will be ordered by molecular weight. Subunits that have identical sequences will be repeated resource and have sequential subscripts sequence Σ datatype content models it describes.

The base schema is called " fhir-base.xsd 0..1 string " and defines all the datatypes and base infrastructure types. In addition, there is a schema for each resource and a common schema fhir-all.xsd Actual nucleotide sequence notation from 5' to 3' end using standard that includes all the resource schemas. For schema processors that do not like circular includes, there is a single letter codes. schema that contains everything.

In addition to the base sequence, sugar and type of phosphate or non-phosphate linkage should w3c schema files, this specification also be captured length Σ 0..1 integer The length provides Schematron files that enforce most of the sequence shall be captured sequenceAttachment Σ 0..1 Attachment (TBC) fivePrime Σ 0..1 CodeableConcept The nucleotide present at constraints defined for the 5’ terminal shall datatypes and resources, though some are only expressible and validatable using FHIRPath . These are packaged as files for each resource.

XML that is exchanged SHALL be specified based on a controlled vocabulary. Since valid against the sequence is represented from w3c schema and Schematron, though being valid against the 5' schema and Schematron is not sufficient to be a conformant instance: this specification makes several rules that cannot be checked by either mechanism. Operational systems may choose to use schema tools to check validation, but are not required to do so. Exchanged content SHALL NOT specify the 3' end, schema or even contain the 5’ prime nucleotide is schema instance namespace in the letter at resource itself.

Given the first position way extensions work, applications reading XML resources will never encounter unknown elements. However, once an application starts trading with other applications that conform to later versions of this specification, unknown XML elements may be encountered. Applications MAY choose to ignore unknown elements to foster forwards compatibility in the sequence. A separate representation this regard, but may also choose not to - which would be redundant threePrime the normal behavior for schema generated applications.

In addition to the 3’ terminal shall be specified based on validation schema, this specification provides a controlled vocabulary. Since the sequence is represented from set of schemas suitable for code generation. These schemas describe the 5' same XML syntax, but apply less validation to create schemas that work better with code generation tooling.

Specifically, these schemas are generated without any xsd:choice elements, for code generators that don't deal with choices well. Implementers that use these schemas will need to enforce the 3' end, the 5’ prime nucleotide is the letter at the last position in correct usage of the sequence. A separate representation would be redundant linkage Σ 0..* BackboneElement The linkages between sugar residues will also be captured connectivity Σ choice elements 0..1 string without schema support.

Implementers making use of schema-driven code generation tooling need to consider how to handle the decimal datatype. The entity that links the sugar residues together should also be captured for nearly all naturally occurring nucleic acid the linkage is a phosphate group. For many synthetic oligonucleotides phosphorothioate linkages are often seen. Linkage connectivity decimal datatype is assumed defined to be 3’-5’. If precision aware - that is, that implementers need to preserve the linkage difference between "2.0" and "2.00" - this is either 3’-3’ or 5’-5’ ubiquitously considered important in handling observed data in healthcare. Both schemas map this should be specified identifier Σ 0..1 Identifier Each linkage will be registered as datatype to a fragment union of xsd:decimal and have an ID name Σ 0..1 xsd:double , but the base W3C schema decimal type icon string Each linkage will is specified not to be registered precision aware. Schema driven implementations vary as a fragment to how precision is handled. Implementers will need to determine how their generated code handles decimals/doubles and have at least one name. A single name shall be assigned consider changing the type for decimal in their schema from xsd:decimal/double to each linkage xsd:string . Specifically, implementers may wish to change:


  <xs:simpleType name="decimal-primitive">
    <xs:union memberTypes="xs:decimal xs:double"/>
  </xs:simpleType>

to this:


  <xs:simpleType name="decimal-primitive">
    <xs:restriction base="xs:string">
      <xs:pattern value="-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?"/>
    </xs:restriction>
  </xs:simpleType>

Note that most code generation frameworks ignore the pattern restriction.

residueSite

Resources and/or Bundles may be captured as described in 5.3.6.8.3 sugar Σ 0..* BackboneElement 5.3.6.8.1 Sugar ID (Mandatory) identifier Σ digitally signed (see Bundle 0..1 Identifier and Provenance The Substance ID of ).

This specification defines the sugar following method for canonicalizing FHIR resources, when represented as XML. Each XML instance or sugar-like component fragment that make up the nucleotide name Σ 0..1 string The name is part of the sugar or sugar-like component that make up collection being signed SHALL:

  • Contain no whitespace other than single spaces in attribute values and in the nucleotide residueSite Σ 0..1 string XHTML in the Narrative The residues that contain a given sugar will be captured. The order of given residues will be captured in
  • Use default namespaces for the 5‘-3‘direction consistent with FHIR and XHTML namespaces
  • Omit all comments
  • Always use the base sequences listed above Documentation Unicode character representation for this format any XML entities (e.g. &#39; instead of &quot; )
  • Include the XML processing instruction <?xml version="1.0" encoding="UTF-8"?>
  • Using the XML canonical method Canonical XML 1.1 icon UML Diagram ( Legend http://www.w3.org/2006/12/xml-c14n11 )

This canonicalization method is identified by the URI http://hl7.org/fhir/canonicalization/xml . The following additional canonicalization URIs are also defined:

SubstanceNucleicAcid
http://hl7.org/fhir/canonicalization/xml#data The narrative ( DomainResource Resource.text ) The type of is omitted prior to signing (note the sequence shall be specified based on a controlled vocabulary sequenceType : CodeableConcept [0..1] The number of linear sequences of nucleotides linked through phosphodiester bonds shall be described. Subunits would be strands of nucleic acids that are tightly associated typically through Watson-Crick base pairing. NOTE: If deletion is at Resource.text , not specified in the reference source, Resource.text.div )
http://hl7.org/fhir/canonicalization/xml#static In addition to narrative (Resource.text), the assumption is that there Resource.meta element is 1 subunit numberOfSubunits : integer [0..1] The area of hybridisation shall be described if applicable for double stranded RNA or DNA. The number associated with the subunit followed by the number associated to removed. This makes the residue shall be specified in increasing order. The underscore “” shall be used as separator signature robust as follows: “Subunitnumber Residue” areaOfHybridisation : string [0..1] (TBC) oligoNucleotideType : CodeableConcept [0..1] Subunit Index of linear sequences of nucleic acids in order of decreasing length. Sequences of the same length will be ordered by molecular weight. Subunits that have identical sequences will be repeated and have sequential subscripts subunit : integer [0..1] Actual nucleotide sequence notation content is moved from 5' server to 3' end using standard single letter codes. In addition server, or workflow and access tags are added or removed. Note that workflow and security tags may contain information important to the base sequence, sugar and type handling of phosphate or non-phosphate linkage the resource, so meta elements should also be captured sequence : string [0..1] protected from tampering by other means if unsigned.
http://hl7.org/fhir/canonicalization/xml#narrative The length of method only retains the sequence shall be captured length : integer [0..1] (TBC) sequenceAttachment : Attachment [0..1] Resource.id and Narrative ( Resource.text
http://hl7.org/fhir/canonicalization/xml#document The nucleotide present at the 5’ terminal shall be specified based on signs everything in a controlled vocabulary. Since Bundle, except for the sequence is represented from Bundle.id and Bundle.metadata on the 5' root Bundle (allows for a document to the 3' end, the 5’ prime nucleotide is the letter at the first position in the sequence. A separate representation would be redundant fivePrime : CodeableConcept [0..1] The nucleotide present at the 3’ terminal shall be specified based on a controlled vocabulary. Since the sequence is represented copied from the 5' server to server)

These canonicalization methods allow systems the 3' end, the 5’ prime nucleotide is the letter at flexibility to sign the last position in various portions of the sequence. A separate representation would be redundant threePrime : CodeableConcept [0..1] Linkage The entity resource that links the sugar residues together should also be captured matter for nearly all naturally occurring nucleic acid the linkage is a phosphate group. For many synthetic oligonucleotides phosphorothioate linkages are often seen. Linkage connectivity is assumed to be 3’-5’. If workflow the linkage is either 3’-3’ or 5’-5’ this should be specified connectivity : string [0..1] Each linkage signature serves. These canonicalization algorithms do not work for enveloped signatures. This will be registered as a fragment researched and have an ID identifier : Identifier [0..1] Each linkage will be registered as addressed in a fragment and have at least one name. A single name shall be assigned to each linkage name : string [0..1] Residues shall be captured as described future release. This specification may define additional canonicalizations in 5.3.6.8.3 residueSite : string [0..1] Sugar The Substance ID of the sugar or sugar-like component that make up the nucleotide identifier : Identifier [0..1] future, and other specifications might also define additional canonicalization methods.

The name

Implementation Note: One consequence of signing the sugar or sugar-like component that make up the nucleotide name : string [0..1] The residues document is that contain a given sugar will URLs, identifiers and internal references are frozen and cannot be captured. The order of given residues will changed. This might be captured in the 5‘-3‘direction consistent with the base sequences listed above residueSite : string [0..1] The linkages between sugar residues will a desired feature, but it may also be captured linkage [0..*] 5.3.6.8.1 Sugar ID (Mandatory) sugar cripple interoperability between closed ecosystems where re-identification [0..*] Subunits are listed in order frequently occurs. For this reason, it is recommended that systems consider carefully the impact of decreasing length; sequences any signature processes. The impact of the same length will be ordered by molecular weight; subunits that have identical sequences will be repeated multiple times subunit [0..*] XML Template < <!-- from --> <!-- from --> <</sequenceType> < < <</oligoNucleotideType> < < < < <</sequenceAttachment> <</fivePrime> <</threePrime> < < <</identifier> < < </linkage> < <</identifier> < < </sugar> </subunit> </SubstanceNucleicAcid> JSON Template { "resourceType" : "", // from // from " " " " " " " " " " " " " " " " }], " " " " }] }] } signatures on Document bundles Turtle Template and their related processes is the most well understood use of digital signatures.

@prefix fhir: <http://hl7.org/fhir/> . [ a fhir:; fhir:nodeRole fhir:treeRoot; # if this is the parser root # from # from fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: fhir: ], ...; fhir: fhir: fhir: fhir: ], ...; ], ...; ] Changes since Release 3

This resource did not exist Note that following normalization procedures in Release 2 This analysis is available as XML or JSON .   See can assign the Profiles & Extensions same normalized text to resources with slightly different meanings, since leading whitespace matters in markdown text, and the alternate definitions: Master Definition XML + JSON , XML Schema / Schematron + JSON Schema , ShEx (for Turtle ) + see the extensions & representation serializes the dependency analysis markdown datatype using attributes.