Skip to main content

Terminology Service — Event Schemas

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

1. Overview​

The terminology-service is primarily a read-only query service. Individual lookup and search calls do not emit events — the volume would be too high and clinical significance too low for event-stream processing.

Events are published only for administrative mutations to the terminology dataset: concept creation, deactivation, and bulk dataset updates.

Transport: NATS JetStream via @ghasi/nats-client Envelope: CloudEvents v1.0 Stream: TERMINOLOGY

2. Published Events​

2.1 ghasi.terminology.concept.created​

NATS subject: TERMINOLOGY.concept.created Trigger: Admin creates a new concept (global or tenant-scoped)

{
  "specversion": "1.0",
  "id": "01JXXX",
  "source": "ghasi/terminology",
  "type": "ghasi.terminology.concept.created",
  "datacontenttype": "application/json",
  "time": "2026-04-18T10:00:00Z",
  "tenantid": "TENANT_01J",
  "data": {
    "conceptId": "CON_01JXXX",
    "system": "urn:ghasi:tenant:TENANT_01J",
    "code": "CUSTOM-001",
    "display": "Custom Lab Panel",
    "tenantId": "TENANT_01J",
    "active": true,
    "createdBy": "USR_01JXXX"
  }
}

Consumer(s): Audit log, clinical notification pipeline (if tenant-specific code additions warrant downstream notification).

2.2 ghasi.terminology.concept.deactivated​

NATS subject: TERMINOLOGY.concept.deactivated Trigger: Admin deactivates a concept

{
  "specversion": "1.0",
  "id": "01JXXX",
  "source": "ghasi/terminology",
  "type": "ghasi.terminology.concept.deactivated",
  "datacontenttype": "application/json",
  "time": "2026-04-18T10:05:00Z",
  "tenantid": "TENANT_01J",
  "data": {
    "conceptId": "CON_01JXXX",
    "system": "http://loinc.org",
    "code": "OLD-LAB-001",
    "tenantId": null,
    "deactivatedBy": "USR_01JXXX",
    "reason": "Superseded by LOINC 99999-1"
  }
}

Consumer(s): Cache invalidation pipeline — consuming services should bust cached responses for the deactivated (system, code) pair.

2.3 ghasi.terminology.dataset.updated​

NATS subject: TERMINOLOGY.dataset.updated Trigger: A bulk terminology import job completes (CSV import or ETL pipeline drop)

{
  "specversion": "1.0",
  "id": "01JXXX",
  "source": "ghasi/terminology",
  "type": "ghasi.terminology.dataset.updated",
  "datacontenttype": "application/json",
  "time": "2026-04-18T02:00:00Z",
  "tenantid": null,
  "data": {
    "importJobId": "IMP_01JXXX",
    "systemsUpdated": ["http://loinc.org", "http://snomed.info/sct"],
    "conceptsAdded": 1240,
    "conceptsUpdated": 88,
    "conceptsDeactivated": 12,
    "completedAt": "2026-04-18T02:03:45Z"
  }
}

Consumer(s): interop-service (may need to rebuild CapabilityStatement if ValueSets changed); downstream services with terminology caches.

3. Consumed Events​

None. Terminology-service is a leaf in the event-driven dependency graph — it publishes but does not subscribe to events from other platform services. Data enters only via admin API or ETL pipeline.

4. Dead-Letter Queue​

Terminology-service event publishing uses the transactional outbox pattern. On NATS unavailability:

  • Events are stored in outbox_events table with status = "pending"
  • Relay worker retries on NATS reconnect
  • Failed deliveries after 3 attempts are retained in the outbox for manual inspection

Terminology events have low business urgency (admin-only operations) — DLQ alert threshold: >10 pending outbox events older than 1 hour.