Document Service — Event Schemas

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 04 event-driven-architecture

---

1. Envelope

All events follow CloudEvents 1.0.

Field	Value
specversion	"1.0"
source	"ghasi/document-service"
datacontenttype	"application/json"
subject (NATS)	document.{aggregate}.{event}.v{N}

Service domain: document per NAMING.md.

---

2. NATS Subject Map

Subject	JetStream Stream	Retention	Produced when
document.template.created.v1	doc-template-events	7 years	Template metadata created
document.template.updated.v1	doc-template-events	7 years	Template metadata updated
document.template.version_published.v1	doc-template-events	7 years	Template version published
document.template.retired.v1	doc-template-events	7 years	Template retired
document.render.started.v1	doc-render-events	30 days	Async render job started
document.render.completed.v1	doc-render-events	30 days	Render job completed
document.render.failed.v1	doc-render-events	30 days	Render job failed
document.artifact.registered.v1	doc-artifact-events	7 years	DocumentReference created
document.upload.quarantined.v1	doc-security-events	7 years	Upload failed virus scan

---

3. Events Produced

3.1 document.template.created.v1

{
  "specversion": "1.0",
  "type": "document.template.created.v1",
  "source": "ghasi/document-service",
  "id": "tmpl_01JRXXXX",
  "time": "2026-04-18T09:00:00Z",
  "datacontenttype": "application/json",
  "data": {
    "templateId": "tmpl_01JRXXXX",
    "tenantId": "ten_afg_moph_001",
    "name": "Outpatient Prescription",
    "category": "prescription",
    "origin": "tenant",
    "createdBy": "usr_docauthor001"
  }
}

---

3.2 document.template.version_published.v1

{
  "data": {
    "templateId": "tmpl_01JRXXXX",
    "versionId": "tv_01JRXXXX",
    "tenantId": "ten_afg_moph_001",
    "semver": "1.2.0",
    "effectiveFrom": "2026-04-18",
    "checksum": "sha256:abcdef...",
    "publishedBy": "usr_docauthor001"
  }
}

---

3.3 document.template.retired.v1

{
  "data": {
    "templateId": "tmpl_01JRXXXX",
    "tenantId": "ten_afg_moph_001",
    "retiredAt": "2026-04-18T09:00:00Z",
    "retiredBy": "usr_tenantadmin001"
  }
}

---

3.4 document.render.started.v1

{
  "data": {
    "jobId": "rjob_01JRXXXX",
    "tenantId": "ten_afg_moph_001",
    "templateVersionId": "tv_01JRXXXX",
    "patientId": "pat_01JRXXXX",
    "encounterId": "enc_01JRXXXX"
  }
}

---

3.5 document.render.completed.v1

{
  "data": {
    "jobId": "rjob_01JRXXXX",
    "tenantId": "ten_afg_moph_001",
    "documentReferenceId": "DocRef/01JRXXXX",
    "binaryId": "Binary/01JRXXXX",
    "durationMs": 3420
  }
}

---

3.6 document.render.failed.v1

{
  "data": {
    "jobId": "rjob_01JRXXXX",
    "tenantId": "ten_afg_moph_001",
    "errorCode": "BINDING_RESOLUTION_FAILED",
    "message": "Patient resource not found"
  }
}

Note: message must not contain PHI.

---

3.7 document.artifact.registered.v1

{
  "data": {
    "documentReferenceId": "DocRef/01JRXXXX",
    "tenantId": "ten_afg_moph_001",
    "patientId": "pat_01JRXXXX",
    "documentType": "11502-2",
    "origin": "generated",
    "category": "lab_requisition",
    "registeredAt": "2026-04-18T09:00:00Z"
  }
}

documentType: LOINC code where applicable. origin: generated | uploaded.

---

3.8 document.upload.quarantined.v1

{
  "data": {
    "uploadId": "upl_01JRXXXX",
    "tenantId": "ten_afg_moph_001",
    "reason": "virus_detected",
    "quarantinedAt": "2026-04-18T09:00:00Z"
  }
}

---

4. Events Consumed

Subject consumed	Source	Action taken
config.design_token.updated.v1	config-service	Refresh tenant branding for next generation request

---

5. Consumer Reaction Map

Event	Consumer	Reaction
document.artifact.registered.v1	patient-chart-service	Index document reference in patient chart
document.artifact.registered.v1	interop-service	Optionally forward to HIE as CDA
document.artifact.registered.v1	patient-portal-service	Surface patient-visible document
document.upload.quarantined.v1	audit-service	Security audit record
document.upload.quarantined.v1	SIEM / security tools	Alert on virus detection
All events	audit-service	Persist audit records (7-year retention)

---

6. Dead Letter Queue

DLQ subject: document.dlq

Condition	Retry	Post-retry
NATS consumer 5 NACKs	JetStream moves to DLQ	Alert if DLQ depth > 5
Schema validation failure	No retry	Log event ID; manual review
FHIR write failure on artifact registration	3 retries + exponential backoff	Alert; mark job failed