Demographic Modeling

Demographic Modeling

> The RM detail in the steps below is a working summary. The specs/rm-demographic guide loaded in Step 1 is authoritative — if they disagree, follow the guide (or confirm against type_specification_get).

Conflict Resolution

When guides conflict, apply this priority (highest first):

1. Rules and structural constraints
2. Privacy and separation principles
3. Anti-patterns
4. Principles and examples
5. Convenience

Step 1: Load Guides (MANDATORY)

Before any demographic modeling work, load the authoritative guides:

guide_get("specs/rm-demographic")
guide_get("archetypes/principles")

Load additional guides as needed:

• guide_get("specs/rm-ehr") — for EHR/demographic separation context and cross-referencing patterns

Step 2: Clarify Use Case

Before designing, gather requirements:

• Entity types: Which PARTY subtypes are needed — PERSON, ORGANISATION, GROUP, AGENT?
• Roles: What roles do parties play? What capabilities and time validity apply?
• Relationships: What relationships exist between parties? What is the directionality?
• Deployment context: Is this a standalone demographic service, a PMI wrapper, or embedded within an EHR system?
• Privacy requirements: What level of PARTY_SELF identification is appropriate for the deployment?

Step 3: Research Before Creating

Before designing new demographic archetypes, ALWAYS search CKM first:

ckm_archetype_search("person")
ckm_archetype_search("organisation")
ckm_archetype_search("party identity")

Reuse-first principle: If a suitable demographic archetype exists, use it. Only create new archetypes when no existing archetype covers the concept. If a close match exists, consider specialization instead.

Use ckm_archetype_get to retrieve and review candidate archetypes in full before deciding. For a deeper reuse survey across varied phrasings (demographic concepts are easy to phrase several ways), dispatch the ckm-scout agent — it runs parallel searches and returns a ranked reuse/specialize/new recommendation without filling the main context with raw hits.

Step 4: PARTY Hierarchy Design

ACTOR Subtype Selection

Choose the correct ACTOR subtype for each entity:

| ACTOR Subtype | Purpose | Examples | |---------------|---------|---------| | PERSON | Individual human beings | Patient, clinician, next of kin | | ORGANISATION | Legal or administrative entities | Hospital, clinic, insurer | | GROUP | Informal or functional collections | Care team, household | | AGENT | Non-human actors | Software agent, device |

Use type_specification_get to verify the RM structure of ACTOR and its subtypes when uncertain.

ROLE Modeling

ROLE represents a party acting in a specific capacity:

• Each ROLE references its ACTOR via performer
• Assign time_validity to express when the role is active
• Use capabilities to describe what the role is permitted to do
• A single ACTOR may hold multiple concurrent ROLEs (e.g., a person who is both a patient and a clinician)

GROUP vs ORGANISATION

• Use GROUP for informal or ad-hoc collections without a legal identity (e.g., care team, family unit)
• Use ORGANISATION for entities with a formal legal or administrative standing (e.g., registered company, government body)

Step 5: Identity and Contact Design

PARTY_IDENTITY

PARTY_IDENTITY holds names and designations for a party:

• Each identity has a purpose (e.g., legal name, alias, trading name, maiden name)
• Apply time_validity to capture historical names
• A party may hold multiple PARTY_IDENTITY instances simultaneously

Identifiers

State-issued and system-assigned identifiers (e.g., NHS number, passport number, employee ID) belong in PARTY.details, NOT in PARTYIDENTITY. PARTYIDENTITY is for names only.

Use type_specification_get("PARTY_IDENTITY") to confirm the structure before authoring.

CONTACT and ADDRESS

• CONTACT groups one or more ADDRESS instances under a shared purpose (e.g., home, work, billing)
• Each ADDRESS carries its own time_validity
• Prefer structured ADDRESS types over free-text where the deployment context supports it

Step 6: Relationship Design

PARTY_RELATIONSHIP Modeling

• PARTY_RELATIONSHIP is directional: source → target
• The source party carries the relationship instance by value in relationships
• The target party holds a reference back in reverse_relationships — by reference only, not by value
• Apply time_validity to express active periods for the relationship
• Assign a details archetype to carry relationship-specific data (e.g., next-of-kin type, guardian authority)

Serialisation Safety

When producing EHR Extracts, relationships that reference parties outside the extract boundary must be serialised safely. Avoid assumptions that all referenced parties are included in the same extract.

Step 7: Privacy and Separation

Three Levels of PARTY_SELF Identification

openEHR supports three levels of identification in the EHR for privacy:

1. Full identification: EHR contains explicit demographic references pointing to a Party in the demographic service
2. Coded identification: EHR contains only a coded reference; mapping is held externally
3. Anonymous: EHR contains no identifying links; identification is impossible from the EHR alone

Choose the level appropriate for the deployment context and applicable data-protection regulations.

EHR Index Service

Cross-referencing between the EHR and the demographic service is mediated by an EHR Index (or Master Patient Index). The EHR does not directly embed demographic records.

Clinical Demographic Data in the EHR

Certain demographic-adjacent data is legitimately recorded in the EHR as clinical observations:

• Age, date of birth (as OBSERVATION or ADMIN_ENTRY)
• Biological sex, gender identity (as OBSERVATION)
• Occupation, ethnicity (as ADMIN_ENTRY or EVALUATION)

This data lives in the EHR by clinical necessity and is distinct from the authoritative demographic record in the Party service.

Step 8: Versioning

• Demographic records use VERSIONED_PARTY, following the same change-control model as EHR content
• Every update creates a new Version; the version history is immutable
• Lifecycle states (draft, complete, deleted) apply to demographic versions
• All changes are associated with a Contribution carrying audit metadata (committer, timestamp, reason)

Ensure that any demographic archetype design accounts for which fields are expected to change over time and how version history will be navigated.

Step 9: Quality Review

Before finalizing the demographic model, verify:

• [ ] Clear entity type selection (PERSON / ORGANISATION / GROUP / AGENT / ROLE)
• [ ] Appropriate CKM archetype reuse confirmed via search
• [ ] Identity (PARTY_IDENTITY) and identifiers (PARTY.details) correctly separated
• [ ] Roles carry performer reference and time_validity
• [ ] Relationship directionality is correct (source carries by value, target by reference)
• [ ] Privacy level chosen and documented for the deployment context
• [ ] Versioning approach defined and VERSIONED_PARTY lifecycle considered
• [ ] PMI / EHR Index integration strategy documented if applicable

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Cadasto
• Source: Cadasto/openehr-assistant-plugin
• License: MIT

Install and usage instructions live in the source repository linked above.