NCPI FHIR Implementation Guide v2
0.2.0 - ci-build

NCPI FHIR Implementation Guide v2 - Local Development build (v0.2.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Resource Profile: Family Relationship

Official URL: https://nih-ncpi.github.io/ncpi-fhir-ig-2/StructureDefinition/ncpi-family-relationship Version: 0.2.0
Draft as of 2025-12-03 Computable Name: NcpiFamilyRelationship

A relationship between individuals in a pedigree or family.

We chose the direction of the relationship to match PED files (plink Harvard Medical School definition, Broad Institute definition), which go from the individual to the mother and father.

Key Guidelines

Family Relationships describe the relationship between two Participants. The core use case is to present biological parentage of a participant to support family / pedigree analyses. In this spirit, platforms should seek to provide minimally the information in a PED file:

  • If known, a Participant should have a Family Relationship to their biological mother and father.
  • Twins and other multiples are also a high-priority item for reporting.

Further extended relationships can be made available using Family Relationship, but may not be as widely supported as they are harder to interpret.

To ensure an unambiguous representation of family relationships, we recommend that the following guidelines be followed:

  • For each parent-child relationship, create a FamilyRelationship resource with the child as the patient and the parent as the relative.
  • For all identical-sibling relationships, create two FamilyRelationship resources. That is, if three participants are triplets, create six FamilyRelationship resources. One with the patient as the first participant and the relative as the second participant, and one with the patient as the second participant and the relative as the first participant, one with the patient as the second participant and the relative as the third participant, and so on.
  • For other genetic relationships, (like grandparents), create FamilyRelationship resources for each parent-child relationship.
  • For non-genetic relationships, such as a spouse, an adoptive parent, or a surrogate mother, create one FamilyRelationship with each participant as the patient and the other as the relative. So, "spouse" would require two FamilyRelationship resources. Prefer non-gendered and sexless codes for the relationship because gender and sex are properties of the individual. For example, prefer "spouse" over "husband" or "wife."
  • It is acceptable to create several FamilyRelationship resources for the same patient and relative pair. For example, two participants may be spouses but also third cousins. That would require four FamilyRelationship resources.

Relationship to other implementation guides

GA4GH Family Relationships

GA4GH Family Relationships are defined in the GA4GH Family Relationships specification.

This FamilyRelationship resource is almost compatible with the GA4GH Family Relationships specification. However, we cannot include it in the profile because the GA4GH specification restricts relationships to the codes defined in that standard. Unfortunately, that set of codes does not meet our use cases or interoperability requirements. If the binding had been extensible, we could have inherited from the GA4GH Family Relationships profile and encouraged the use of better codes. However, software written for that profile might be able to read our FamilyRelationship resources as long as it does not rely on the "required" binding.

FHIR Mappings

The following fields from the shared data model map into the NCPI Participant as shown below:

Logical Model Property [NCPI Family Relationship][n_overview] Instantiation
subject patient
target extension[relative]
relationship relationship

Usages:

You can also check for usages in the FHIR IG Statistics

Formal Views of Profile Content

Description of Profiles, Differentials, Snapshots and how the different presentations work.

NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. FamilyMemberHistory C 0..* FamilyMemberHistory Information about patient's relatives, relevant for patient
Constraints: fhs-1, fhs-2
... implicitRules ?!Σ 0..1 uri A set of rules under which this content was created
... Slices for extension 1..* Extension Extension
Slice: Unordered, Open by value:url
.... extension:relative S 1..1 Reference(Patient) The participant in the relationship who plays the role named by the relationship.
URL: http://hl7.org/fhir/StructureDefinition/familymemberhistory-patient-record
... modifierExtension ?! 0..* Extension Extensions that cannot be ignored
... patient SΣ 1..1 Reference(Patient) The participant we are describing.
... relationship SΣ 1..1 CodeableConcept The role the relative fills with respect to the patient for this relationship.
Binding: Biological Relationship Codes (extensible)

doco Documentation for this format

Terminology Bindings

Path Status Usage ValueSet Version Source
FamilyMemberHistory.​status Base required FamilyHistoryStatus 📍4.0.1 FHIR Std.
FamilyMemberHistory.​relationship Base extensible Biological Relationship Codes 📦0.2.0 This IG
FamilyMemberHistory.​condition.code Base example Condition/Problem/Diagnosis Codes 📍4.0.1 FHIR Std.

Constraints

Id Grade Path(s) Description Expression
dom-2 error FamilyMemberHistory If the resource is contained in another resource, it SHALL NOT contain nested Resources contained.contained.empty()
dom-3 error FamilyMemberHistory 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 FamilyMemberHistory 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 FamilyMemberHistory If a resource is contained in another resource, it SHALL NOT have a security label contained.meta.security.empty()
dom-6 best practice FamilyMemberHistory 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()
fhs-1 error FamilyMemberHistory Can have age[x] or born[x], but not both age.empty() or born.empty()
fhs-2 error FamilyMemberHistory Can only have estimatedAge if age[x] is present age.exists() or estimatedAge.empty()

This structure is derived from FamilyMemberHistory

NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. FamilyMemberHistory 0..* FamilyMemberHistory Information about patient's relatives, relevant for patient
... Slices for extension 1..* Extension Extension
Slice: Unordered, Open by value:url
.... extension:relative S 1..1 Reference(Patient) The participant in the relationship who plays the role named by the relationship.
URL: http://hl7.org/fhir/StructureDefinition/familymemberhistory-patient-record
... patient S 1..1 Reference(Patient) The participant we are describing.
... name 0..0 The family member described
... sex 0..0 male | female | other | unknown
... born[x] 0..0 (approximate) date of birth
... age[x] 0..0 (approximate) age
... estimatedAge 0..0 Age is estimated?
... deceased[x] 0..0 Dead? How old/when?
... reasonCode 0..0 Why was family member history performed?
... reasonReference 0..0 Why was family member history performed?
... condition 0..0 Condition that the related person had

doco Documentation for this format

Terminology Bindings (Differential)

Path Status Usage ValueSet Version Source
FamilyMemberHistory.​relationship Base extensible Biological Relationship Codes 📦0.2.0 This IG
NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. FamilyMemberHistory C 0..* FamilyMemberHistory Information about patient's relatives, relevant for patient
Constraints: fhs-1, fhs-2
... 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
... text 0..1 Narrative Text summary of the resource, for human interpretation
This profile does not constrain the narrative in regard to content, language, or traceability to data elements
... contained 0..* Resource Contained, inline Resources
... Slices for extension 1..* Extension Extension
Slice: Unordered, Open by value:url
.... extension:relative S 1..1 Reference(Patient) The participant in the relationship who plays the role named by the relationship.
URL: http://hl7.org/fhir/StructureDefinition/familymemberhistory-patient-record
... modifierExtension ?! 0..* Extension Extensions that cannot be ignored
... identifier Σ 0..* Identifier External Id(s) for this record
... instantiatesCanonical Σ 0..* canonical(PlanDefinition | Questionnaire | ActivityDefinition | Measure | OperationDefinition) Instantiates FHIR protocol or definition
... instantiatesUri Σ 0..* uri Instantiates external protocol or definition
... status ?!Σ 1..1 code partial | completed | entered-in-error | health-unknown
Binding: FamilyHistoryStatus (required): A code that identifies the status of the family history record.
... dataAbsentReason Σ 0..1 CodeableConcept subject-unknown | withheld | unable-to-obtain | deferred
Binding: FamilyHistoryAbsentReason (example): Codes describing the reason why a family member's history is not available.
... patient SΣ 1..1 Reference(Patient) The participant we are describing.
... date Σ 0..1 dateTime When history was recorded or last updated
... relationship SΣ 1..1 CodeableConcept The role the relative fills with respect to the patient for this relationship.
Binding: Biological Relationship Codes (extensible)
... note 0..* Annotation General note about related person

doco Documentation for this format

Terminology Bindings

Path Status Usage ValueSet Version Source
FamilyMemberHistory.​language Base preferred Common Languages 📍4.0.1 FHIR Std.
FamilyMemberHistory.​status Base required FamilyHistoryStatus 📍4.0.1 FHIR Std.
FamilyMemberHistory.​dataAbsentReason Base example FamilyHistoryAbsentReason 📍4.0.1 FHIR Std.
FamilyMemberHistory.​relationship Base extensible Biological Relationship Codes 📦0.2.0 This IG
FamilyMemberHistory.​condition.code Base example Condition/Problem/Diagnosis Codes 📍4.0.1 FHIR Std.
FamilyMemberHistory.​condition.outcome Base example Condition Outcome Codes 📍4.0.1 FHIR Std.

Constraints

Id Grade Path(s) Description Expression
dom-2 error FamilyMemberHistory If the resource is contained in another resource, it SHALL NOT contain nested Resources contained.contained.empty()
dom-3 error FamilyMemberHistory 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 FamilyMemberHistory 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 FamilyMemberHistory If a resource is contained in another resource, it SHALL NOT have a security label contained.meta.security.empty()
dom-6 best practice FamilyMemberHistory 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()
fhs-1 error FamilyMemberHistory Can have age[x] or born[x], but not both age.empty() or born.empty()
fhs-2 error FamilyMemberHistory Can only have estimatedAge if age[x] is present age.exists() or estimatedAge.empty()

This structure is derived from FamilyMemberHistory

Summary

Mandatory: 2 elements
Must-Support: 3 elements
Prohibited: 9 elements

Extensions

This structure refers to these extensions:

Key Elements View

NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. FamilyMemberHistory C 0..* FamilyMemberHistory Information about patient's relatives, relevant for patient
Constraints: fhs-1, fhs-2
... implicitRules ?!Σ 0..1 uri A set of rules under which this content was created
... Slices for extension 1..* Extension Extension
Slice: Unordered, Open by value:url
.... extension:relative S 1..1 Reference(Patient) The participant in the relationship who plays the role named by the relationship.
URL: http://hl7.org/fhir/StructureDefinition/familymemberhistory-patient-record
... modifierExtension ?! 0..* Extension Extensions that cannot be ignored
... patient SΣ 1..1 Reference(Patient) The participant we are describing.
... relationship SΣ 1..1 CodeableConcept The role the relative fills with respect to the patient for this relationship.
Binding: Biological Relationship Codes (extensible)

doco Documentation for this format

Terminology Bindings

Path Status Usage ValueSet Version Source
FamilyMemberHistory.​status Base required FamilyHistoryStatus 📍4.0.1 FHIR Std.
FamilyMemberHistory.​relationship Base extensible Biological Relationship Codes 📦0.2.0 This IG
FamilyMemberHistory.​condition.code Base example Condition/Problem/Diagnosis Codes 📍4.0.1 FHIR Std.

Constraints

Id Grade Path(s) Description Expression
dom-2 error FamilyMemberHistory If the resource is contained in another resource, it SHALL NOT contain nested Resources contained.contained.empty()
dom-3 error FamilyMemberHistory 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 FamilyMemberHistory 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 FamilyMemberHistory If a resource is contained in another resource, it SHALL NOT have a security label contained.meta.security.empty()
dom-6 best practice FamilyMemberHistory 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()
fhs-1 error FamilyMemberHistory Can have age[x] or born[x], but not both age.empty() or born.empty()
fhs-2 error FamilyMemberHistory Can only have estimatedAge if age[x] is present age.exists() or estimatedAge.empty()

Differential View

This structure is derived from FamilyMemberHistory

NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. FamilyMemberHistory 0..* FamilyMemberHistory Information about patient's relatives, relevant for patient
... Slices for extension 1..* Extension Extension
Slice: Unordered, Open by value:url
.... extension:relative S 1..1 Reference(Patient) The participant in the relationship who plays the role named by the relationship.
URL: http://hl7.org/fhir/StructureDefinition/familymemberhistory-patient-record
... patient S 1..1 Reference(Patient) The participant we are describing.
... name 0..0 The family member described
... sex 0..0 male | female | other | unknown
... born[x] 0..0 (approximate) date of birth
... age[x] 0..0 (approximate) age
... estimatedAge 0..0 Age is estimated?
... deceased[x] 0..0 Dead? How old/when?
... reasonCode 0..0 Why was family member history performed?
... reasonReference 0..0 Why was family member history performed?
... condition 0..0 Condition that the related person had

doco Documentation for this format

Terminology Bindings (Differential)

Path Status Usage ValueSet Version Source
FamilyMemberHistory.​relationship Base extensible Biological Relationship Codes 📦0.2.0 This IG

Snapshot View

NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. FamilyMemberHistory C 0..* FamilyMemberHistory Information about patient's relatives, relevant for patient
Constraints: fhs-1, fhs-2
... 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
... text 0..1 Narrative Text summary of the resource, for human interpretation
This profile does not constrain the narrative in regard to content, language, or traceability to data elements
... contained 0..* Resource Contained, inline Resources
... Slices for extension 1..* Extension Extension
Slice: Unordered, Open by value:url
.... extension:relative S 1..1 Reference(Patient) The participant in the relationship who plays the role named by the relationship.
URL: http://hl7.org/fhir/StructureDefinition/familymemberhistory-patient-record
... modifierExtension ?! 0..* Extension Extensions that cannot be ignored
... identifier Σ 0..* Identifier External Id(s) for this record
... instantiatesCanonical Σ 0..* canonical(PlanDefinition | Questionnaire | ActivityDefinition | Measure | OperationDefinition) Instantiates FHIR protocol or definition
... instantiatesUri Σ 0..* uri Instantiates external protocol or definition
... status ?!Σ 1..1 code partial | completed | entered-in-error | health-unknown
Binding: FamilyHistoryStatus (required): A code that identifies the status of the family history record.
... dataAbsentReason Σ 0..1 CodeableConcept subject-unknown | withheld | unable-to-obtain | deferred
Binding: FamilyHistoryAbsentReason (example): Codes describing the reason why a family member's history is not available.
... patient SΣ 1..1 Reference(Patient) The participant we are describing.
... date Σ 0..1 dateTime When history was recorded or last updated
... relationship SΣ 1..1 CodeableConcept The role the relative fills with respect to the patient for this relationship.
Binding: Biological Relationship Codes (extensible)
... note 0..* Annotation General note about related person

doco Documentation for this format

Terminology Bindings

Path Status Usage ValueSet Version Source
FamilyMemberHistory.​language Base preferred Common Languages 📍4.0.1 FHIR Std.
FamilyMemberHistory.​status Base required FamilyHistoryStatus 📍4.0.1 FHIR Std.
FamilyMemberHistory.​dataAbsentReason Base example FamilyHistoryAbsentReason 📍4.0.1 FHIR Std.
FamilyMemberHistory.​relationship Base extensible Biological Relationship Codes 📦0.2.0 This IG
FamilyMemberHistory.​condition.code Base example Condition/Problem/Diagnosis Codes 📍4.0.1 FHIR Std.
FamilyMemberHistory.​condition.outcome Base example Condition Outcome Codes 📍4.0.1 FHIR Std.

Constraints

Id Grade Path(s) Description Expression
dom-2 error FamilyMemberHistory If the resource is contained in another resource, it SHALL NOT contain nested Resources contained.contained.empty()
dom-3 error FamilyMemberHistory 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 FamilyMemberHistory 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 FamilyMemberHistory If a resource is contained in another resource, it SHALL NOT have a security label contained.meta.security.empty()
dom-6 best practice FamilyMemberHistory 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()
fhs-1 error FamilyMemberHistory Can have age[x] or born[x], but not both age.empty() or born.empty()
fhs-2 error FamilyMemberHistory Can only have estimatedAge if age[x] is present age.exists() or estimatedAge.empty()

This structure is derived from FamilyMemberHistory

Summary

Mandatory: 2 elements
Must-Support: 3 elements
Prohibited: 9 elements

Extensions

This structure refers to these extensions:

 

Other representations of profile: CSV, Excel, Schematron

Notes: