Population Health Service — Event Schemas

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 03 platform-services · 02 DDD

1. Conventions

Convention	Value
Event domain	population_health (per NAMING.md)
Event type format	population_health.{aggregate}.{event}.v{N}
NATS subject	Same as event type (identical per NAMING.md)
Stream name	POPULATION_HEALTH
Subjects pattern	population_health.>
Source	ghasi/population-health-service
Envelope	CloudEvents 1.0
PHI in events	Prohibited — only aggregate counts and IDs permitted

2. NATS JetStream Configuration

Setting	Value
Stream name	POPULATION_HEALTH
Subjects	population_health.>
Storage	File
Replicas	3 (production)
Retention	Limits — 14-day default
Max message size	128 KB
Discard policy	Old

3. Events Produced

3.1 population_health.cohort.created.v1

Field	Value
Trigger	Cohort definition persisted
Retention class	Standard (14 days)
Consumers	audit-service

{
  "specversion": "1.0",
  "type": "population_health.cohort.created.v1",
  "source": "ghasi/population-health-service",
  "id": "<uuid>",
  "time": "2026-04-18T07:00:00Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "<uuid>",
    "actorId": "<uuid>",
    "correlationId": "<uuid>",
    "cohortId": "coh_01HX...",
    "cohortVersion": 1,
    "name": "Diabetes adults overdue A1C",
    "isShared": true,
    "refreshPolicy": "schedule"
  }
}

---

3.2 population_health.cohort.refreshed.v1

Field	Value
Trigger	Cohort membership refresh job completes
Retention class	Standard (14 days)
Consumers	audit-service, dashboard BFF (via websocket bridge)

{
  "specversion": "1.0",
  "type": "population_health.cohort.refreshed.v1",
  "source": "ghasi/population-health-service",
  "id": "<uuid>",
  "time": "2026-04-18T07:05:00Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "<uuid>",
    "correlationId": "<uuid>",
    "cohortId": "coh_01HX...",
    "cohortVersion": 3,
    "membershipCount": 1240,
    "evaluatedAt": "2026-04-18T07:05:00Z",
    "durationMs": 18350,
    "sourceWatermark": "2026-04-18T06:45:00Z"
  }
}

---

3.3 population_health.risk_score.computed.v1

Field	Value
Trigger	Risk scoring job completes for patient set
Retention class	Standard (14 days)
Consumers	audit-service

{
  "specversion": "1.0",
  "type": "population_health.risk_score.computed.v1",
  "source": "ghasi/population-health-service",
  "id": "<uuid>",
  "time": "2026-04-18T07:10:00Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "<uuid>",
    "actorId": "<uuid>",
    "correlationId": "<uuid>",
    "modelKey": "clinical-risk-v1",
    "scope": "cohort",
    "scopeId": "coh_01HX...",
    "tierCounts": { "low": 420, "medium": 680, "high": 110, "critical": 30 },
    "computedAt": "2026-04-18T07:10:00Z"
  }
}

---

3.4 population_health.risk_score.overridden.v1

Field	Value
Trigger	Manual risk tier override recorded
Retention class	Long-term (90 days — compliance)
Consumers	audit-service

{
  "specversion": "1.0",
  "type": "population_health.risk_score.overridden.v1",
  "source": "ghasi/population-health-service",
  "id": "<uuid>",
  "time": "2026-04-18T09:00:00Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "<uuid>",
    "actorId": "<uuid>",
    "correlationId": "<uuid>",
    "riskScoreId": "rsk_01HX...",
    "patientId": "<uuid>",
    "previousTier": "medium",
    "overrideTier": "high",
    "overrideReason": "Complex multi-morbidity per MDT review"
  }
}

---

3.5 population_health.care_gap.detected.v1

Field	Value
Trigger	Care-gap run identifies due or overdue interventions
Retention class	Standard (14 days)
Consumers	audit-service, communication-service (outreach trigger)

{
  "specversion": "1.0",
  "type": "population_health.care_gap.detected.v1",
  "source": "ghasi/population-health-service",
  "id": "<uuid>",
  "time": "2026-04-18T06:00:00Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "<uuid>",
    "correlationId": "<uuid>",
    "runId": "<uuid>",
    "cohortId": "coh_01HX...",
    "gapType": "colorectal-screening-overdue",
    "patientCount": 180,
    "asOf": "2026-04-18T06:00:00Z"
  }
}

---

3.6 population_health.outreach_list.generated.v1

Field	Value
Trigger	Outreach list generation job completes
Retention class	Standard (14 days)
Consumers	audit-service, communication-service

{
  "specversion": "1.0",
  "type": "population_health.outreach_list.generated.v1",
  "source": "ghasi/population-health-service",
  "id": "<uuid>",
  "time": "2026-04-18T08:00:00Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "<uuid>",
    "actorId": "<uuid>",
    "correlationId": "<uuid>",
    "outreachListId": "ors_01HX...",
    "name": "April Overdue Hypertension Follow-up",
    "itemCount": 310,
    "channelMix": ["phone", "sms"],
    "assignedTeamId": "<uuid>"
  }
}

---

3.7 population_health.quality_metric.calculated.v1

Field	Value
Trigger	Quality metric snapshot job completes
Retention class	Long-term (90 days)
Consumers	audit-service, FHIR MeasureReport publisher

{
  "specversion": "1.0",
  "type": "population_health.quality_metric.calculated.v1",
  "source": "ghasi/population-health-service",
  "id": "<uuid>",
  "time": "2026-04-18T06:00:00Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "<uuid>",
    "correlationId": "<uuid>",
    "metricKey": "hedis-bp-control",
    "program": "hedis",
    "periodStart": "2026-01-01",
    "periodEnd": "2026-03-31",
    "numerator": 820,
    "denominator": 1020,
    "exclusions": 70,
    "rate": 0.8039
  }
}

---

3.8 population_health.hmis_export.completed.v1

Field	Value
Trigger	DHIS2 push succeeds
Retention class	Long-term (90 days — compliance)
Consumers	audit-service, ops alerting

{
  "specversion": "1.0",
  "type": "population_health.hmis_export.completed.v1",
  "source": "ghasi/population-health-service",
  "id": "<uuid>",
  "time": "2026-04-18T06:05:00Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "<uuid>",
    "correlationId": "<uuid>",
    "jobId": "hmis_01HX...",
    "indicatorFamily": "service-utilization",
    "period": { "start": "2026-04-01", "end": "2026-04-17" },
    "dhis2ImportCount": { "imported": 124, "updated": 8, "ignored": 0 },
    "dhis2Reference": "dhis2-job-uid-xxxx"
  }
}

---

3.9 population_health.hmis_export.failed.v1

Trigger: DHIS2 push fails after max retries. Consumers: audit-service, ops alert.

{
  "data": {
    "tenantId": "<uuid>",
    "jobId": "hmis_01HX...",
    "indicatorFamily": "service-utilization",
    "period": { "start": "2026-04-01", "end": "2026-04-17" },
    "failureReason": "DHIS2 API returned 502 after 3 retries",
    "retryCount": 3
  }
}

---

3.10 population_health.deident_export.released.v1

Field	Value
Trigger	De-identified dataset released to researcher
Retention class	Long-term (90 days — compliance)
Consumers	audit-service

{
  "data": {
    "tenantId": "<uuid>",
    "actorId": "<uuid>",
    "jobId": "exp_01HX...",
    "purpose": "academic-research",
    "irbReference": "IRB-2026-AFG-014",
    "rowCount": 4120,
    "kValue": 5,
    "dpEpsilon": 0.8,
    "expiresAt": "2026-04-19T08:00:00Z"
  }
}

4. Events Consumed

NATS Subject	Source Service	Handling
scheduling.appointment.scheduled.v1	scheduling-service	May trigger cohort refresh if appointment type affects registry
patient_chart.encounter.completed.v1	patient-chart-service	Triggers incremental cohort member re-evaluation
immunizations.immunization.administered.v1	immunizations-service	Updates immunization coverage snapshot
laboratory.result.resulted.v1	laboratory-service	Updates lab-based care gap and registry control status
medication.prescription.dispensed.v1	medication-service	Updates medication-based cohort predicates