Health Data Model Planner
Plan a health data model with a strong bias toward FHIR before committing to storage, code structures, or client-specific architecture.
When to Use
Use this skill when you need to:
- define the core health concepts a product needs to represent
- decide which entities, relationships, and lifecycle states matter
- reason about interoperability requirements with FHIR as the default starting point for clinical data
- prepare for later implementation in a mobile app, backend, analytics pipeline, or research workflow
Working Style
Start with the domain, but assume that clinically meaningful data will often benefit from a FHIR-oriented design unless there is a strong reason not to.
Clarify:
- what the product is trying to track or coordinate
- who creates, reads, updates, or interprets the data
- what must be longitudinal, auditable, shareable, or clinically meaningful
- what needs to be structured versus free-form
- which standards, institutions, or downstream systems matter
Default Bias Toward FHIR
In digital health, prefer asking "How would this map to FHIR?" early rather than treating interoperability as a late-stage add-on.
Default questions:
- should this concept become a FHIR resource instead of a custom object
- is there an existing FHIR pattern for this workflow
- should values use established terminologies such as LOINC, SNOMED CT, or RxNorm
- will this data eventually need to move between apps, research systems, backend services, or EHR-adjacent systems
It is fine to decide that some concepts remain app-internal, but make that an explicit choice.
Reuse Before Building
Do not encourage teams to hand-roll FHIR models, parsers, or mapping infrastructure unless there is a compelling gap.
When implementation starts, generally recommend reusing mature ecosystem libraries, for example:
- Swift: apple/FHIRModels for core FHIR resource models
- Swift in the Spezi ecosystem: StanfordSpezi/SpeziFHIR for FHIR-focused Spezi integrations
- TypeScript and Firebase in the Spezi ecosystem: StanfordSpezi/spezi-firebase, including the npm package
@stanfordspezi/spezi-firebase-fhir
If the user is already working in a concrete stack, recommend modeling choices that fit those existing libraries instead of inventing parallel abstractions.
Planning Framework
1. Core Entities
Identify the main concepts, such as:
- person or participant
- observation or measurement
- questionnaire or assessment
- response or result
- task, intervention, or reminder
- condition, medication, consent, or care-plan concept
For each entity, define:
- purpose
- required attributes
- optional attributes
- who creates or updates it
- whether it changes over time
2. Relationships
Map how the entities relate, for example:
- a person has many observations
- a questionnaire has many questions
- a response belongs to one questionnaire instance
- a task may trigger a response or observation
Note:
- one-to-one versus one-to-many relationships
- whether history must be preserved
- what should be versioned
3. Lifecycle and State
For important entities, define lifecycle states such as:
- draft
- active
- completed
- cancelled
- archived
Also define:
- what events cause state changes
- whether edits overwrite history or create new records
- what should remain immutable
4. Interoperability
Use FHIR as the default lens for clinically relevant data, and only move away from it when the extra complexity is not justified.
Assess:
- whether the product needs to exchange data with clinical systems
- whether FHIR is required now, likely soon, or only later
- whether standard terminologies such as LOINC, SNOMED CT, or RxNorm are needed
- which concepts are internal-only versus externally shareable
When possible, push the user toward:
- standard FHIR resources over custom schemas
- standard FHIR fields over custom extensions
- standard terminologies over app-specific code strings
- explicit mapping notes for any intentionally non-FHIR concepts
5. Governance and Quality
Review:
- data provenance
- validation rules
- units and value ranges
- duplicate handling
- retention and deletion expectations
- privacy sensitivity of each data category
Deliverable Format
Produce a concise data model planning brief with:
- core entities
- key attributes
- entity relationships
- lifecycle states
- FHIR and terminology recommendations
- library reuse recommendations for the target stack
- governance and data-quality notes
- unresolved modeling questions
Save the brief as docs/planning/data-model-brief.md in the project repository.
Guardrails
- Do not assume a specific database, TypeScript model, or mobile framework.
- Favor FHIR for clinically meaningful or shareable health data unless the user gives a good reason not to.
- Keep the distinction clear between business concepts and implementation details.
- Flag where clinical input is needed to validate terminology or meaning.
- Recommend existing libraries before suggesting custom FHIR infrastructure.
Checklist
- Core entities identified
- Required and optional attributes outlined
- Relationships mapped
- Lifecycle states defined
- FHIR resource fit assessed
- Terminology needs assessed
- Reusable libraries identified for the target stack
- Governance and validation concerns captured
- Open questions documented