NCPI FHIR Implementation Guide v2 - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
Resource Profile: NCPI File
| Official URL: https://nih-ncpi.github.io/ncpi-fhir-ig-2/StructureDefinition/ncpi-file | Version: 0.1.0 | |||
| Draft as of 2025-03-24 | Computable Name: NcpiFile | |||
Information about a file related to a research participant
Key Guidelines
The NCPI File profile is based on the standard resource type, DocumentReference and is intended to represent the files associated with a participant in a research study.
Added Profile Restrictions
In order to ensure that our resources are interoperable across studies, we have employed a number of restrictions that should make consuming Patient resources more consistent.
-
participantID should be a globally unique identifier associated with the patient. This practice is intended to make constructing queries for the same patient compatible across different servers (such as QA vs PROD) but also to make the resource URLs more meaningful.
-
fileExternalID should have all appropriate Identifiers with a meaningful system/value pair. Such identifiers may include DbGAP accession IDs, global and external IDs, etc.
-
format and relatedFile.type should use EDAM terminology (i.e., codes) when available. Other file type code systems are allowed if a suitable EDAM code does not exist.
Recommended Practices
Providing as much information about a file and file metatdata will help individuals using this IG to understand the details and limits of information conveyed about a file.
FHIR Mappings
The following fields from the shared data model are to be mapped to the NCPI File as shown below:
| Logical Model Property | Cardinality | NCPI FHIR Mapping | Usage Guidance | Notes |
| participantID | 1..1 | identifier.value | The participant(s) for whom this file contains data | |
| fileExternalID | 0..1 | subject | A related identifier of this file | |
| format | 1..1 | extension[file-format].valueCodeableConcept.coding | The file format used | |
| location | 1..* | content | List of locations where this data can be accessed | |
| location.uri | 1..1 | content.attachment.url | The URI at which this data can be accessed | |
| location.accessPolicy | 0..* | content.extension[location-access].valueReference | If present, only those under the specific Access Policy can access the file in this location. | |
| fileSize | 1..1 | extension[file-size].valueQuantity.value, extension[file-size].valueQuantity.unit | The size of the file, e.g., in bytes. | |
| hash | 0..* | extension[hash] | Provides a list of hashes for confirming file transfers | |
| hash.type | 0..1 | extension[hash-type].valueCode | Algorithm used to calculate the hash (and size, where applicable) | |
| hash.value | 1..1 | extension[hash-value].valueString | Value of hashing the file | |
| contentVersion | 0..1 | extension[content-version].valueString | Version of the file content | |
| description | 0..1 | description | A description of the file | |
| type | 1..1 | type | The type of data contained in this file. Should be as detailed as possible, e.g., Whole Exome Variant Calls. |
Usage:
- Derived from this Resource Profile: NCPI DRS File
- Examples for this Resource Profile: DocumentReference/GF-6BAD9S7D and DocumentReference/GSS123456-01-010-SG-2
Formal Views of Profile Content
Description of Profiles, Differentials, Snapshots and how the different presentations work.
| Name | Flags | Card. | Type | Description & Constraints |
|---|---|---|---|---|
  DocumentReference |
0..* | DocumentReference | A reference to a document dom-2: If the resource is contained in another resource, it SHALL NOT contain nested Resources dom-3: 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 dom-4: If a resource is contained in another resource, it SHALL NOT have a meta.versionId or a meta.lastUpdated dom-5: If a resource is contained in another resource, it SHALL NOT have a security label dom-6: A resource should have narrative for robust management | |
  implicitRules |
?!Σ | 0..1 | uri | A set of rules under which this content was created ele-1: All FHIR elements must have a @value or children |
  Slices for extension |
2..* | Extension | Extension Slice: Unordered, Open by value:url ele-1: All FHIR elements must have a @value or children ext-1: Must have either extensions or value[x], not both | |
   extension:file-format |
1..1 | CodeableConcept | The file format used (EDAM is preferred) URL: https://nih-ncpi.github.io/ncpi-fhir-ig-2/StructureDefinition/file-format Binding: http://edamontology.org (extensible) ele-1: All FHIR elements must have a @value or children unless an empty Parameters resource ext-1: Must have either extensions or value[x], not both | |
| extension:location-access |
0..* | Reference() | If present, only those under the specific Access Policy can access the file in this location. URL: https://nih-ncpi.github.io/ncpi-fhir-ig-2/StructureDefinition/location-access ele-1: All FHIR elements must have a @value or children unless an empty Parameters resource ext-1: Must have either extensions or value[x], not both | |
| extension:file-size |
1..1 | Quantity | Indicate the size of the file in reference URL: https://nih-ncpi.github.io/ncpi-fhir-ig-2/StructureDefinition/file-size ele-1: All FHIR elements must have a @value or children unless an empty Parameters resource ext-1: Must have either extensions or value[x], not both | |
| extension:hash |
0..* | (Complex) | Provides a list of hashes for confirming file transfers URL: https://nih-ncpi.github.io/ncpi-fhir-ig-2/StructureDefinition/hash-extension ele-1: All FHIR elements must have a @value or children unless an empty Parameters resource ext-1: Must have either extensions or value[x], not both | |
 extension:content-version |
0..1 | string | The version of the content in the file URL: https://nih-ncpi.github.io/ncpi-fhir-ig-2/StructureDefinition/content-version ele-1: All FHIR elements must have a @value or children unless an empty Parameters resource ext-1: Must have either extensions or value[x], not both | |
 modifierExtension |
?! | 0..* | Extension | Extensions that cannot be ignored ele-1: All FHIR elements must have a @value or children ext-1: Must have either extensions or value[x], not both |
 identifier |
Σ | 1..* | Identifier | A related external file ID ele-1: All FHIR elements must have a @value or children |
| status |
?!Σ | 1..1 | code | current | superseded | entered-in-error Binding: DocumentReferenceStatus (required): The status of the document reference. ele-1: All FHIR elements must have a @value or children |
| type |
Σ | 0..1 | CodeableConcept | The type of data contained in this file. Binding: Enumerations for the EDAM ontology (extensible) ele-1: All FHIR elements must have a @value or children |
 subject |
Σ | 1..1 | Reference(Patient | Practitioner | Group | Device) | The participant(s) for whom this file contains data (i.e., ParticipantID) ele-1: All FHIR elements must have a @value or children |
| description |
Σ | 0..1 | string | A description of the file ele-1: All FHIR elements must have a @value or children |
 content |
Σ | 1..* | BackboneElement | Document referenced ele-1: All FHIR elements must have a @value or children unless an empty Parameters resource |
 modifierExtension |
?!Σ | 0..* | Extension | Extensions that cannot be ignored even if unrecognized ele-1: All FHIR elements must have a @value or children ext-1: Must have either extensions or value[x], not both |
| attachment |
Σ | 1..1 | Attachment | Where to access the document ele-1: All FHIR elements must have a @value or children |
 url |
Σ | 1..1 | url | The URI at which this data can be accessed ele-1: All FHIR elements must have a @value or children Example General: http://www.acme.com/logo-small.png |
| Documentation for this format | ||||
Terminology Bindings
| Path | Conformance | ValueSet | URI |
| DocumentReference.status | required | DocumentReferenceStatushttp://hl7.org/fhir/ValueSet/document-reference-status|4.3.0from the FHIR Standard | |
| DocumentReference.type | extensible | EDAMOntologyTerms (a valid code from http://edamontology.org)https://nih-ncpi.github.io/ncpi-fhir-ig-2/ValueSet/edam-ontology-termsfrom this IG |
Constraints
| Id | Grade | Path(s) | Details | Requirements |
| dom-2 | error | DocumentReference | If the resource is contained in another resource, it SHALL NOT contain nested Resources : contained.contained.empty() | |
| dom-3 | error | DocumentReference | 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.exists() and ('#'+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(uri) = '#').exists()).not()).trace('unmatched', id).empty() | |
| dom-4 | error | DocumentReference | 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 | DocumentReference | If a resource is contained in another resource, it SHALL NOT have a security label : contained.meta.security.empty() | |
| dom-6 | best practice | DocumentReference | 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() |
Other representations of profile: CSV, Excel, Schematron