# Demographic Modeling

> >

- **Type:** Skill
- **Install:** `agentstack add skill-cadasto-openehr-assistant-plugin-demographic-modeling`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Cadasto](https://agentstack.voostack.com/s/cadasto)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Cadasto](https://github.com/Cadasto)
- **Source:** https://github.com/Cadasto/openehr-assistant-plugin/tree/main/skills/demographic-modeling

## Install

```sh
agentstack add skill-cadasto-openehr-assistant-plugin-demographic-modeling
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 PARTY_IDENTITY. PARTY_IDENTITY 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](https://github.com/Cadasto)
- **Source:** [Cadasto/openehr-assistant-plugin](https://github.com/Cadasto/openehr-assistant-plugin)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-cadasto-openehr-assistant-plugin-demographic-modeling
- Seller: https://agentstack.voostack.com/s/cadasto
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.