NCPI FHIR Implementation Guide - Local Development build (v0.2.0). See the Directory of published versions
Resource Profile: NCPI Data Dictionary Harmony
| Official URL: https://nih-ncpi.github.io/ncpi-fhir-ig/StructureDefinition/study-data-dictionary-harmony | Version: 0.2.0 | |||
| Draft as of 2022-12-09 | Computable Name: StudyDataDictionaryHarmony | |||
Based on the FHIR resource type, ConceptMap, the StudyDataDictionaryHarmony resource provides insight into the transformations made during the ETL from source data into FHIR allowing clients to use the $translate function to discover all of the public codes that were mapped from one of the study’s actual vocabulary.
Key Guidelines for Usage
The mechanics of the ConceptMap, upon which the StudyDataDictionaryHarmony is based is simple. A single vocabulary (ValueSet) is required for each the source and the target and for each code in the source an element is created which identifies the target codes. Clients can query these ConceptMap resources via the $translate operation.
There will be a single StudyDataDictionaryHarmony resource for a study where all codes that are mapped to one or more public ontologies are captured along with their target mappings. This represents the documentation describing the transformations performed on the FHIR resources in use.
Usage:
- Examples for this Resource Profile: ConceptMap/example-study-data-dictionary-conceptmap-1
Formal Views of Profile Content
Description of Profiles, Differentials, Snapshots and how the different presentations work.
This structure is derived from ConceptMap
| Name | Flags | Card. | Type | Description & Constraints |
|---|---|---|---|---|
  ConceptMap | 0..* | ConceptMap | A map from one set of concepts to one or more other concepts | |
| Documentation for this format | ||||
| Name | Flags | Card. | Type | Description & Constraints |
|---|---|---|---|---|
| ConceptMap | C | 0..* | ConceptMap | A map from one set of concepts to one or more other concepts |
  implicitRules | ?!Σ | 0..1 | uri | A set of rules under which this content was created |
 modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored |
 status | ?!Σ | 1..1 | code | draft | active | retired | unknown Binding: PublicationStatus (required): The lifecycle status of an artifact. |
| Documentation for this format | ||||
Terminology Bindings
| Path | Conformance | ValueSet |
| ConceptMap.status | required | PublicationStatus |
Constraints
| Id | Grade | Path(s) | Details | Requirements |
| cmd-0 | warning | ConceptMap | Name should be usable as an identifier for the module by machine processing applications such as code generation : name.matches('[A-Z]([A-Za-z0-9_]){0,254}') | |
| dom-2 | error | ConceptMap | If the resource is contained in another resource, it SHALL NOT contain nested Resources : contained.contained.empty() | |
| dom-3 | error | ConceptMap | If the resource is contained in another resource, it SHALL be referred to from elsewhere in the resource or SHALL refer to the containing resource : contained.where((('#'+id in (%resource.descendants().reference | %resource.descendants().as(canonical) | %resource.descendants().as(uri) | %resource.descendants().as(url))) or descendants().where(reference = '#').exists() or descendants().where(as(canonical) = '#').exists() or descendants().where(as(canonical) = '#').exists()).not()).trace('unmatched', id).empty() | |
| dom-4 | error | ConceptMap | If a resource is contained in another resource, it SHALL NOT have a meta.versionId or a meta.lastUpdated : contained.meta.versionId.empty() and contained.meta.lastUpdated.empty() | |
| dom-5 | error | ConceptMap | If a resource is contained in another resource, it SHALL NOT have a security label : contained.meta.security.empty() | |
| dom-6 | best practice | ConceptMap | A resource should have narrative for robust management : text.`div`.exists() | |
| ele-1 | error | **ALL** elements | All FHIR elements must have a @value or children : hasValue() or (children().count() > id.count()) | |
| ext-1 | error | **ALL** extensions | Must have either extensions or value[x], not both : extension.exists() != value.exists() |
| Name | Flags | Card. | Type | Description & Constraints | ||||
|---|---|---|---|---|---|---|---|---|
| ConceptMap | C | 0..* | ConceptMap | A map from one set of concepts to one or more other concepts | ||||
| id | Σ | 0..1 | id | Logical id of this artifact | ||||
 meta | Σ | 0..1 | Meta | Metadata about the resource | ||||
| implicitRules | ?!Σ | 0..1 | uri | A set of rules under which this content was created | ||||
| language | 0..1 | code | Language of the resource content Binding: CommonLanguages (preferred): A human language.
| |||||
| text | 0..1 | Narrative | Text summary of the resource, for human interpretation | |||||
| contained | 0..* | Resource | Contained, inline Resources | |||||
 extension | 0..* | Extension | Additional content defined by implementations | |||||
| modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored | ||||
| url | Σ | 0..1 | uri | Canonical identifier for this concept map, represented as a URI (globally unique) | ||||
| identifier | Σ | 0..1 | Identifier | Additional identifier for the concept map | ||||
| version | Σ | 0..1 | string | Business version of the concept map | ||||
| name | ΣC | 0..1 | string | Name for this concept map (computer friendly) | ||||
| title | Σ | 0..1 | string | Name for this concept map (human friendly) | ||||
| status | ?!Σ | 1..1 | code | draft | active | retired | unknown Binding: PublicationStatus (required): The lifecycle status of an artifact. | ||||
| experimental | Σ | 0..1 | boolean | For testing purposes, not real usage | ||||
| date | Σ | 0..1 | dateTime | Date last changed | ||||
| publisher | Σ | 0..1 | string | Name of the publisher (organization or individual) | ||||
| contact | Σ | 0..* | ContactDetail | Contact details for the publisher | ||||
| description | 0..1 | markdown | Natural language description of the concept map | |||||
| useContext | Σ | 0..* | UsageContext | The context that the content is intended to support | ||||
| jurisdiction | Σ | 0..* | CodeableConcept | Intended jurisdiction for concept map (if applicable) Binding: Jurisdiction ValueSet (extensible): Countries and regions within which this artifact is targeted for use. | ||||
| purpose | 0..1 | markdown | Why this concept map is defined | |||||
| copyright | 0..1 | markdown | Use and/or publishing restrictions | |||||
  source[x] | Σ | 0..1 | The source value set that contains the concepts that are being mapped | |||||
 sourceUri | uri | |||||||
 sourceCanonical | canonical(ValueSet) | |||||||
| target[x] | Σ | 0..1 | The target value set which provides context for the mappings | |||||
| targetUri | uri | |||||||
| targetCanonical | canonical(ValueSet) | |||||||
 group | 0..* | BackboneElement | Same source and target systems | |||||
 id | 0..1 | string | Unique id for inter-element referencing | |||||
| extension | 0..* | Extension | Additional content defined by implementations | |||||
| modifierExtension | ?!Σ | 0..* | Extension | Extensions that cannot be ignored even if unrecognized | ||||
| source | 0..1 | uri | Source system where concepts to be mapped are defined | |||||
| sourceVersion | 0..1 | string | Specific version of the code system | |||||
| target | 0..1 | uri | Target system that the concepts are to be mapped to | |||||
| targetVersion | 0..1 | string | Specific version of the code system | |||||
| element | 1..* | BackboneElement | Mappings for a concept from the source set | |||||
| id | 0..1 | string | Unique id for inter-element referencing | |||||
| extension | 0..* | Extension | Additional content defined by implementations | |||||
| modifierExtension | ?!Σ | 0..* | Extension | Extensions that cannot be ignored even if unrecognized | ||||
| code | 0..1 | code | Identifies element being mapped | |||||
| display | 0..1 | string | Display for the code | |||||
| target | C | 0..* | BackboneElement | Concept in target system for element | ||||
| id | 0..1 | string | Unique id for inter-element referencing | |||||
| extension | 0..* | Extension | Additional content defined by implementations | |||||
| modifierExtension | ?!Σ | 0..* | Extension | Extensions that cannot be ignored even if unrecognized | ||||
| code | 0..1 | code | Code that identifies the target element | |||||
| display | 0..1 | string | Display for the code | |||||
| equivalence | ?! | 1..1 | code | relatedto | equivalent | equal | wider | subsumes | narrower | specializes | inexact | unmatched | disjoint Binding: ConceptMapEquivalence (required): The degree of equivalence between concepts. | ||||
| comment | C | 0..1 | string | Description of status/issues in mapping | ||||
| dependsOn | 0..* | BackboneElement | Other elements required for this mapping (from context) | |||||
| id | 0..1 | string | Unique id for inter-element referencing | |||||
| extension | 0..* | Extension | Additional content defined by implementations | |||||
| modifierExtension | ?!Σ | 0..* | Extension | Extensions that cannot be ignored even if unrecognized | ||||
| property | 1..1 | uri | Reference to property mapping depends on | |||||
| system | 0..1 | canonical(CodeSystem) | Code System (if necessary) | |||||
| value | 1..1 | string | Value of the referenced element | |||||
| display | 0..1 | string | Display for the code (if value is a code) | |||||
 product | 0..* | See dependsOn (ConceptMap) | Other concepts that this mapping also produces | |||||
| unmapped | C | 0..1 | BackboneElement | What to do when there is no mapping for the source concept | ||||
| id | 0..1 | string | Unique id for inter-element referencing | |||||
| extension | 0..* | Extension | Additional content defined by implementations | |||||
| modifierExtension | ?!Σ | 0..* | Extension | Extensions that cannot be ignored even if unrecognized | ||||
| mode | 1..1 | code | provided | fixed | other-map Binding: ConceptMapGroupUnmappedMode (required): Defines which action to take if there is no match in the group. | |||||
| code | 0..1 | code | Fixed code when mode = fixed | |||||
| display | 0..1 | string | Display for the code | |||||
| url | 0..1 | canonical(ConceptMap) | canonical reference to an additional ConceptMap to use for mapping if the source concept is unmapped | |||||
| Documentation for this format | ||||||||
Terminology Bindings
| Path | Conformance | ValueSet | ||||
| ConceptMap.language | preferred | CommonLanguages
| ||||
| ConceptMap.status | required | PublicationStatus | ||||
| ConceptMap.jurisdiction | extensible | Jurisdiction ValueSet | ||||
| ConceptMap.group.element.target.equivalence | required | ConceptMapEquivalence | ||||
| ConceptMap.group.unmapped.mode | required | ConceptMapGroupUnmappedMode |
Constraints
| Id | Grade | Path(s) | Details | Requirements |
| cmd-1 | error | ConceptMap.group.element.target | If the map is narrower or inexact, there SHALL be some comments : comment.exists() or equivalence.empty() or ((equivalence != 'narrower') and (equivalence != 'inexact')) | |
| cmd-2 | error | ConceptMap.group.unmapped | If the mode is 'fixed', a code must be provided : (mode = 'fixed') implies code.exists() | |
| cmd-3 | error | ConceptMap.group.unmapped | If the mode is 'other-map', a url must be provided : (mode = 'other-map') implies url.exists() | |
| ele-1 | error | **ALL** elements | All FHIR elements must have a @value or children : hasValue() or (children().count() > id.count()) | |
| ext-1 | error | **ALL** extensions | Must have either extensions or value[x], not both : extension.exists() != value.exists() |
This structure is derived from ConceptMap
Differential View
This structure is derived from ConceptMap
| Name | Flags | Card. | Type | Description & Constraints |
|---|---|---|---|---|
| ConceptMap | 0..* | ConceptMap | A map from one set of concepts to one or more other concepts | |
| Documentation for this format | ||||
Key Elements View
| Name | Flags | Card. | Type | Description & Constraints |
|---|---|---|---|---|
| ConceptMap | C | 0..* | ConceptMap | A map from one set of concepts to one or more other concepts |
| implicitRules | ?!Σ | 0..1 | uri | A set of rules under which this content was created |
| modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored |
| status | ?!Σ | 1..1 | code | draft | active | retired | unknown Binding: PublicationStatus (required): The lifecycle status of an artifact. |
| Documentation for this format | ||||
Terminology Bindings
| Path | Conformance | ValueSet |
| ConceptMap.status | required | PublicationStatus |
Constraints
| Id | Grade | Path(s) | Details | Requirements |
| cmd-0 | warning | ConceptMap | Name should be usable as an identifier for the module by machine processing applications such as code generation : name.matches('[A-Z]([A-Za-z0-9_]){0,254}') | |
| dom-2 | error | ConceptMap | If the resource is contained in another resource, it SHALL NOT contain nested Resources : contained.contained.empty() | |
| dom-3 | error | ConceptMap | If the resource is contained in another resource, it SHALL be referred to from elsewhere in the resource or SHALL refer to the containing resource : contained.where((('#'+id in (%resource.descendants().reference | %resource.descendants().as(canonical) | %resource.descendants().as(uri) | %resource.descendants().as(url))) or descendants().where(reference = '#').exists() or descendants().where(as(canonical) = '#').exists() or descendants().where(as(canonical) = '#').exists()).not()).trace('unmatched', id).empty() | |
| dom-4 | error | ConceptMap | If a resource is contained in another resource, it SHALL NOT have a meta.versionId or a meta.lastUpdated : contained.meta.versionId.empty() and contained.meta.lastUpdated.empty() | |
| dom-5 | error | ConceptMap | If a resource is contained in another resource, it SHALL NOT have a security label : contained.meta.security.empty() | |
| dom-6 | best practice | ConceptMap | A resource should have narrative for robust management : text.`div`.exists() | |
| ele-1 | error | **ALL** elements | All FHIR elements must have a @value or children : hasValue() or (children().count() > id.count()) | |
| ext-1 | error | **ALL** extensions | Must have either extensions or value[x], not both : extension.exists() != value.exists() |
Snapshot View
| Name | Flags | Card. | Type | Description & Constraints | ||||
|---|---|---|---|---|---|---|---|---|
| ConceptMap | C | 0..* | ConceptMap | A map from one set of concepts to one or more other concepts | ||||
| id | Σ | 0..1 | id | Logical id of this artifact | ||||
| meta | Σ | 0..1 | Meta | Metadata about the resource | ||||
| implicitRules | ?!Σ | 0..1 | uri | A set of rules under which this content was created | ||||
| language | 0..1 | code | Language of the resource content Binding: CommonLanguages (preferred): A human language.
| |||||
| text | 0..1 | Narrative | Text summary of the resource, for human interpretation | |||||
| contained | 0..* | Resource | Contained, inline Resources | |||||
| extension | 0..* | Extension | Additional content defined by implementations | |||||
| modifierExtension | ?! | 0..* | Extension | Extensions that cannot be ignored | ||||
| url | Σ | 0..1 | uri | Canonical identifier for this concept map, represented as a URI (globally unique) | ||||
| identifier | Σ | 0..1 | Identifier | Additional identifier for the concept map | ||||
| version | Σ | 0..1 | string | Business version of the concept map | ||||
| name | ΣC | 0..1 | string | Name for this concept map (computer friendly) | ||||
| title | Σ | 0..1 | string | Name for this concept map (human friendly) | ||||
| status | ?!Σ | 1..1 | code | draft | active | retired | unknown Binding: PublicationStatus (required): The lifecycle status of an artifact. | ||||
| experimental | Σ | 0..1 | boolean | For testing purposes, not real usage | ||||
| date | Σ | 0..1 | dateTime | Date last changed | ||||
| publisher | Σ | 0..1 | string | Name of the publisher (organization or individual) | ||||
| contact | Σ | 0..* | ContactDetail | Contact details for the publisher | ||||
| description | 0..1 | markdown | Natural language description of the concept map | |||||
| useContext | Σ | 0..* | UsageContext | The context that the content is intended to support | ||||
| jurisdiction | Σ | 0..* | CodeableConcept | Intended jurisdiction for concept map (if applicable) Binding: Jurisdiction ValueSet (extensible): Countries and regions within which this artifact is targeted for use. | ||||
| purpose | 0..1 | markdown | Why this concept map is defined | |||||
| copyright | 0..1 | markdown | Use and/or publishing restrictions | |||||
| source[x] | Σ | 0..1 | The source value set that contains the concepts that are being mapped | |||||
| sourceUri | uri | |||||||
| sourceCanonical | canonical(ValueSet) | |||||||
| target[x] | Σ | 0..1 | The target value set which provides context for the mappings | |||||
| targetUri | uri | |||||||
| targetCanonical | canonical(ValueSet) | |||||||
| group | 0..* | BackboneElement | Same source and target systems | |||||
| id | 0..1 | string | Unique id for inter-element referencing | |||||
| extension | 0..* | Extension | Additional content defined by implementations | |||||
| modifierExtension | ?!Σ | 0..* | Extension | Extensions that cannot be ignored even if unrecognized | ||||
| source | 0..1 | uri | Source system where concepts to be mapped are defined | |||||
| sourceVersion | 0..1 | string | Specific version of the code system | |||||
| target | 0..1 | uri | Target system that the concepts are to be mapped to | |||||
| targetVersion | 0..1 | string | Specific version of the code system | |||||
| element | 1..* | BackboneElement | Mappings for a concept from the source set | |||||
| id | 0..1 | string | Unique id for inter-element referencing | |||||
| extension | 0..* | Extension | Additional content defined by implementations | |||||
| modifierExtension | ?!Σ | 0..* | Extension | Extensions that cannot be ignored even if unrecognized | ||||
| code | 0..1 | code | Identifies element being mapped | |||||
| display | 0..1 | string | Display for the code | |||||
| target | C | 0..* | BackboneElement | Concept in target system for element | ||||
| id | 0..1 | string | Unique id for inter-element referencing | |||||
| extension | 0..* | Extension | Additional content defined by implementations | |||||
| modifierExtension | ?!Σ | 0..* | Extension | Extensions that cannot be ignored even if unrecognized | ||||
| code | 0..1 | code | Code that identifies the target element | |||||
| display | 0..1 | string | Display for the code | |||||
| equivalence | ?! | 1..1 | code | relatedto | equivalent | equal | wider | subsumes | narrower | specializes | inexact | unmatched | disjoint Binding: ConceptMapEquivalence (required): The degree of equivalence between concepts. | ||||
| comment | C | 0..1 | string | Description of status/issues in mapping | ||||
| dependsOn | 0..* | BackboneElement | Other elements required for this mapping (from context) | |||||
| id | 0..1 | string | Unique id for inter-element referencing | |||||
| extension | 0..* | Extension | Additional content defined by implementations | |||||
| modifierExtension | ?!Σ | 0..* | Extension | Extensions that cannot be ignored even if unrecognized | ||||
| property | 1..1 | uri | Reference to property mapping depends on | |||||
| system | 0..1 | canonical(CodeSystem) | Code System (if necessary) | |||||
| value | 1..1 | string | Value of the referenced element | |||||
| display | 0..1 | string | Display for the code (if value is a code) | |||||
| product | 0..* | See dependsOn (ConceptMap) | Other concepts that this mapping also produces | |||||
| unmapped | C | 0..1 | BackboneElement | What to do when there is no mapping for the source concept | ||||
| id | 0..1 | string | Unique id for inter-element referencing | |||||
| extension | 0..* | Extension | Additional content defined by implementations | |||||
| modifierExtension | ?!Σ | 0..* | Extension | Extensions that cannot be ignored even if unrecognized | ||||
| mode | 1..1 | code | provided | fixed | other-map Binding: ConceptMapGroupUnmappedMode (required): Defines which action to take if there is no match in the group. | |||||
| code | 0..1 | code | Fixed code when mode = fixed | |||||
| display | 0..1 | string | Display for the code | |||||
| url | 0..1 | canonical(ConceptMap) | canonical reference to an additional ConceptMap to use for mapping if the source concept is unmapped | |||||
| Documentation for this format | ||||||||
Terminology Bindings
| Path | Conformance | ValueSet | ||||
| ConceptMap.language | preferred | CommonLanguages
| ||||
| ConceptMap.status | required | PublicationStatus | ||||
| ConceptMap.jurisdiction | extensible | Jurisdiction ValueSet | ||||
| ConceptMap.group.element.target.equivalence | required | ConceptMapEquivalence | ||||
| ConceptMap.group.unmapped.mode | required | ConceptMapGroupUnmappedMode |
Constraints
| Id | Grade | Path(s) | Details | Requirements |
| cmd-1 | error | ConceptMap.group.element.target | If the map is narrower or inexact, there SHALL be some comments : comment.exists() or equivalence.empty() or ((equivalence != 'narrower') and (equivalence != 'inexact')) | |
| cmd-2 | error | ConceptMap.group.unmapped | If the mode is 'fixed', a code must be provided : (mode = 'fixed') implies code.exists() | |
| cmd-3 | error | ConceptMap.group.unmapped | If the mode is 'other-map', a url must be provided : (mode = 'other-map') implies url.exists() | |
| ele-1 | error | **ALL** elements | All FHIR elements must have a @value or children : hasValue() or (children().count() > id.count()) | |
| ext-1 | error | **ALL** extensions | Must have either extensions or value[x], not both : extension.exists() != value.exists() |
This structure is derived from ConceptMap
Other representations of profile: CSV, Excel, Schematron