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 2026-03-09 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 using KIN:027 (isBiologicalMotherOf) and KIN:028 (isBiologicalFatherOf).
  • Monozygotic twins and other multiples are also a high-priority item for reporting using KIN:010 (isMonozygoticMultipleBirthSiblingOf).

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.
  • Treat rarer genetic relationships (for example, isMitochondrialDonor or isOvumDonor) like the parent-child relationship. The receiver of the genetic or cellular material is the patient and the donor is the relative.
  • For all monozygotic sibling relationships, create pairwise FamilyRelationship resources using KIN:010 (isMonozygoticMultipleBirthSiblingOf). For triplets, create six FamilyRelationship resources (one for each direction of each pair: A→B, B→A, A→C, C→A, B→C, C→B). For quadruplets, create twelve resources, and so on.
  • For other genetic relationships, (like grandparents), create FamilyRelationship resources for each parent-child relationship.
  • For non-genetic relationships, such as a partner, an adoptive parent, or a surrogate mother, create one FamilyRelationship with each participant as the patient and the other as the relative. So, "partner" 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 "partner" over "husband" or "wife." The KIN ontology lacks many terms for precise inverse relationships, so one direction may be isAdoptiveParentOf (KIN:022) and the other isSocialLegalRelativeOf (KIN:019).
  • 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 two FamilyRelationship resources for the mutual isPartner relationships and several more to map back to their common great-great-grandparent. In this case, you may not know the sex of the inferred figures, so you'd use KIN:003, isBiologicalParentOf for the ancestors of unknown sex.

Relationship to other implementation guides

GA4GH Family Relationships

GA4GH Family Relationships are defined in the GA4GH Pedigree FHIR IG specification.

This NcpiFamilyRelationship profile derives from the GA4GH PedigreeRelationship profile and uses codes from the GA4GH KIN ontology. The profile includes all 55 KIN codes in its ValueSet and maintains the parent's required binding for full GA4GH compatibility.

NCPI recommends using a canonical approach with three core codes (KIN:027 (isBiologicalMother), KIN:028 (isBiologicalFatherOf), KIN:010 (isMonozygoticMultipleBirthSiblingOf)) plus inferred individuals to express all pedigree relationships. This provides a complete, unambiguous representation that eases data consumption. While all KIN codes remain available for use when needed, we cannot machine-encode the preference for these three codes due to the required binding strength — doing so would require extensible binding restricted to the KIN ontology, a constraint not expressible in FHIR R4. If future FHIR versions (R5/R6) provide mechanisms to express "extensible within a required parent set," we would adopt that approach. For now, this canonical approach is documented as guidance in the profile definition and ValueSet description.

FHIR Mappings

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

Logical Model Property NCPI Family Relationship Instantiation
subject patient
target extension[relative]
relationship relationship
Please note that the original GA4GH profiles were built using older tooling that wasn't intended for being published 'as is'. As a result, some of the links below will be invalid. Please use the GA4GH PedigreeRelationship instead.

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..* PedigreeRelationship 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 (required)

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 required 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 PedigreeRelationship

NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. FamilyMemberHistory 0..* PedigreeRelationship Information about patient's relatives, relevant for patient
... Slices for extension Content/Rules for all slices
.... extension:relative 1..1 FMHPatientRecord(5.2.0) The participant in the relationship who plays the role named by the relationship.
... patient 1..1 Reference(Patient) The participant we are describing.
... relationship 1..1 CodeableConcept The role the relative fills with respect to the patient for this relationship.
Binding: Biological Relationship Codes (required)

doco Documentation for this format

Terminology Bindings (Differential)

Path Status Usage ValueSet Version Source
FamilyMemberHistory.​relationship Base required Biological Relationship Codes 📦0.2.0 This IG
NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. FamilyMemberHistory C 0..* PedigreeRelationship 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 (required)
... 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 required 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 PedigreeRelationship

Summary

Key Elements View

NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. FamilyMemberHistory C 0..* PedigreeRelationship 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 (required)

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 required 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 PedigreeRelationship

NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. FamilyMemberHistory 0..* PedigreeRelationship Information about patient's relatives, relevant for patient
... Slices for extension Content/Rules for all slices
.... extension:relative 1..1 FMHPatientRecord(5.2.0) The participant in the relationship who plays the role named by the relationship.
... patient 1..1 Reference(Patient) The participant we are describing.
... relationship 1..1 CodeableConcept The role the relative fills with respect to the patient for this relationship.
Binding: Biological Relationship Codes (required)

doco Documentation for this format

Terminology Bindings (Differential)

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

Snapshot View

NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. FamilyMemberHistory C 0..* PedigreeRelationship 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 (required)
... 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 required 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 PedigreeRelationship

Summary

 

Other representations of profile: CSV, Excel, Schematron

Notes: