Fix FHIR Mapping Cardinalities in NCPI Person

[mingward]

Description

The FHIR mapping section of the NCPI Person resource currently states:

This can be misread to imply each Person is related to 0..1 Participant resources by the link.target field. But we know from:
https://nih-ncpi.github.io/ncpi-fhir-ig-2/StructureDefinition-ncpi-person.html
that one Person can link to multiple Participants:

Proposed Clarification

We want to represent the relationship in a clearer subject–predicate–object form, ensuring the cardinalities are more explicit:

Subject Resource	Predicate	Object Resource
NCPI Person	Is the same individual as	NCPI Participant

• Subject Cardinality: 0..1
• Object Cardinality: 1..*
• Subject-to-object field: None
• Object-to-subject field: Person.target.link

Rationale

Explicitly separating subject and object clarifies the relationship. The current mapping might be interpreted incorrectly, so a more detailed table (with fully qualified locations of mapping fields) would avoid ambiguity. This fix would keep the logical relationship modeling aligned with how multiple Participants might map to a single Person (e.g., in multi-study scenarios).

[RobertJCarroll]

It does look like some of the logical model Person didn't translate well into the IG, and those mapping fields are confusing as described. Let's make edits to the logical model as well, adjusting the participant cardinality to be 1..* and adjusting the type- I'm not sure why Value Set Reference was used.

[RobertJCarroll]

Regarding how to update the documentation, my mental model looks a little different. It's reasonable to take an approach like this, though. I'd probably think about the predicate more like "Has the study reported individual" or something similar. The NCPI participant resources "grouped" by a person may have "is" relationships, but the Person is of a different type in my book. Maybe that's too confusing. If your team wants to create a PR with your recommended changes, we can get the WG to review.

[RadixSeven]

comment for discussion in the meeting

Reading your response, that didn't seem to communicate what we intended. Here is a new version of how we might update the FHIR Mapping tables.

I'd like a summary of how to interpret the FHIR mapping tables inserted in the overview materials (or its own page) and linked from the FHIR Mapping section. The example (minus the explanatory rows) would go into the NCPI Person page.

Proposed FHIR mapping explanation section

How to interpret the FHIR Mapping Section

The FHIR mapping table represents the cardinality of the relationship implied by a field or fields as a UML class diagram would describe them and how that maps to the logical model.

Each mapped field is represented by a row in a table with the following columns:

• Subject Resource: the resource representing the subject of the predicate.
• Object Resource: the resource representing the object of the predicate. "None" for value fields.
• Predicate implied by the field(s): An English representation of the predicate implied by the reference or value.
• Subject cardinality: This predicate connects each (Object Resource) to this range of (Subject resource)s.
• Object cardinality: This predicate connects each (Subject Resource) to this range of (Object resource)s.
• Subject-to-object field: The path to the field in the subject resource that expresses the relationship
• Object-to-subject field: The path to the field in the object resource that expresses the relationship
• Logical model subject-to-object field: The path to the field in the subject resource (in the logical model) that expresses the relationship
• Logical model object-to-subject field: The path to the field in the object resource (in the logical model) that expresses the relationship

Example FHIR Mapping with explanations

The "brief table" row shows what we'd expect to see in the table. The "Verbose explanation" and "Implication" rows explain the semantics.

Type of explanation	Subject Resource	Predicate implied by the field	Object Resource	Subject Cardinality	Object Cardinality	Subject-to-object field	Object-to-subject field	Logical model subject-to-object field	Logical model object-to-subject field
Brief table	NCPI Person	Represents the same individual in the real world as	NCPI Participant	0..1	1..*	Person.target.link	None	SharedDataModelPerson.participant	None
Verbose explanation				An NCPI Participant can have 0 or 1 NCPI Person	An NCPI Person can have 1 to many NCPI Participants	An NCPI Person FHIR resource (Patient) must link to at least one NCPI Participant resource.	An NCPI Participant FHIR resource (Patient) has no link to an NCPI Person resource (Person).
Implication				If a participant is linked to a person, then no other Person can link to the same Participant.  Since the Participant resource does not have a Person link, this constraint must be enforced programmatically, even on the same server. ( see #91)
Brief table	NCPI Person	Id of the individual human (unique ID assigned to that individual in the FHIR server)	None	N/A	1..1	Person.id	None	SharedDataModelPerson.identifier	None
Verbose explanation				Value fields do not have a backreference	An NCPI Person has exactly 1 ID