05 — Event Schemas

Status: ✅ Draft
Prerequisite: 04 — Event Catalog
Next: 06 — Authentication Flow

Formal payload schemas for every event type in the catalog. Each schema defines the fields inside the payload block of the standard envelope. The envelope itself is fixed — every event carries it unchanged.

Core-published event schemas (C-020 to C-026) are the authoritative contract. Module-published event schemas included here cover the events Core subscribes to — modules own the full definition of all other events they publish.

1. Standard Envelope Schema

Every event on the platform carries this envelope. It does not vary by event type.

{
  "eventId":        "uuid-v4",
  "eventType":      "registration.confirmed",
  "schemaVersion":  "1.0",
  "timestamp":      "2026-07-15T10:30:00Z",
  "idempotencyKey": "uuid-v4",
  "sourceModule":   "ams",
  "miqaatId":       "MQ-1447-KHI",
  "itsId":          "ITS-1234567",
  "correlationId":  "uuid-v4",
  "payload":        { }
}

Envelope field definitions

Field	Type	Required	Description
`eventId`	string (UUID v4)	✅	Unique identifier for this event instance. Never reused.
`eventType`	string	✅	The registered event type name (`domain.action` notation).
`schemaVersion`	string	✅	Schema version of the `payload` block (e.g. `"1.0"`, `"2.0"`). Consumers use this to select their parser.
`timestamp`	string (ISO 8601)	✅	When the event was produced — UTC. Set by the publisher at the moment of publish.
`idempotencyKey`	string (UUID v4)	✅	Consumers use this to detect duplicate delivery. Two events with the same `idempotencyKey` carry the same logical event — the second delivery is a duplicate and must be discarded.
`sourceModule`	string	✅	Module identifier of the publisher (e.g. `ams`, `vms`, `rbac-engine`). Matches `X-Module-Id` in API calls.
`miqaatId`	string	✅	The Miqaat scope this event belongs to. All events are scoped to a Miqaat.
`itsId`	string	❌	The itsId of the Mumin this event concerns — present on person-specific events, absent on structural events (e.g. `miqaat.phase.changed`).
`correlationId`	string (UUID v4)	❌	Carries the `X-Correlation-Id` from the triggering API call, if the event was produced as a result of a synchronous request. Enables tracing from API call → event.
`payload`	object	✅	Event-specific data. Defined per event type below.

2. Schema Versioning

Version format

schemaVersion follows semantic versioning with two levels: MAJOR.MINOR.

Change type	Version bump	Consumer impact
New optional field added to `payload`	`MINOR` (e.g. `1.0` → `1.1`)	Safe — existing consumers ignore unknown fields
Removing a field from `payload`	`MAJOR` (e.g. `1.x` → `2.0`)	Breaking — consumers must migrate
Renaming or retyping a field	`MAJOR`	Breaking
Changing the meaning of an existing field	`MAJOR`	Breaking

Parallel version support

When a MAJOR version bump occurs, the old schema version continues to be published in parallel until all declared subscribers have migrated. The transition window is agreed between the Core team and affected module teams before the new version is deployed.

During the parallel window, both 1.x and 2.0 events may be in the stream. Consumers check schemaVersion and route to the appropriate parser.

// Consumer version routing
if (event.schemaVersion.startsWith("1.")) {
  parseV1(event.payload);
} else if (event.schemaVersion.startsWith("2.")) {
  parseV2(event.payload);
}

Old version support is removed only after Platform Admin confirms all subscribers have migrated. Premature removal of a version is a breaking contract violation.

3. Core-Published Event Schemas (C-020 to C-026)

Core engine event schemas are the authoritative contracts. These are the events modules consume from Core.

miqaat.created · C-020a

Payload

{
  "miqaatId":    "MQ-1447-KHI",
  "name":        "Ashara Mubaraka 1447 — Karachi",
  "type":        "ashara_mubaraka",
  "createdAt":   "2026-05-01T08:00:00Z",
  "createdBy":   "ITS-9999999"
}

Field	Type	Required	Description
`miqaatId`	string	✅	The newly assigned Miqaat identifier
`name`	string	✅	Display name of the Miqaat
`type`	string	✅	Miqaat type (`ashara_mubaraka`, `misaaq`, `safar`, etc.)
`createdAt`	string (ISO 8601)	✅	When Platform Admin created the Miqaat
`createdBy`	string	✅	itsId of the Platform Admin user who created it

itsId is absent from the envelope for this event — this is a structural event, not a person-specific event.

miqaat.phase.changed · C-020

Payload

{
  "miqaatId":    "MQ-1447-KHI",
  "fromPhase":   "setup",
  "toPhase":     "registration_open",
  "changedAt":   "2026-07-01T00:00:00Z",
  "changedBy":   "ITS-9999999"
}

Field	Type	Required	Description
`miqaatId`	string	✅	The Miqaat whose phase changed
`fromPhase`	string	✅	The previous phase
`toPhase`	string	✅	The new active phase
`changedAt`	string (ISO 8601)	✅	When the transition occurred
`changedBy`	string	✅	itsId of the Platform Admin user who triggered the transition

Valid phase values: setup · registration_open · registration_closed · operational · closed · archived

itsId is absent from the envelope — structural event.

miqaat.archived · C-020b

Payload

{
  "miqaatId":   "MQ-1447-KHI",
  "archivedAt": "2026-11-01T00:00:00Z",
  "archivedBy": "ITS-9999999"
}

Field	Type	Required	Description
`miqaatId`	string	✅	The archived Miqaat
`archivedAt`	string (ISO 8601)	✅	When the Miqaat was archived
`archivedBy`	string	✅	itsId of the Platform Admin user who triggered archival

allocation.confirmed · C-021

Payload

{
  "allocationId":  "ALO-20261001-00042",
  "itsId":         "ITS-1234567",
  "miqaatId":      "MQ-1447-KHI",
  "category":      "residential",
  "zone":          "KHI-NORTH",
  "requestedBy":   "ams",
  "confirmedAt":   "2026-07-15T10:30:00Z"
}

Field	Type	Required	Description
`allocationId`	string	✅	The allocation record identifier
`itsId`	string	✅	The Mumin who received the allocation
`miqaatId`	string	✅	The Miqaat scope
`category`	string	✅	Allocation category (e.g. `residential`, `day_visitor`, `khidmatguzar`)
`zone`	string	❌	Zone assigned, if zone-quota allocation mode is active
`requestedBy`	string	✅	The module that submitted the allocation request
`confirmedAt`	string (ISO 8601)	✅	When the allocation was confirmed

allocation.waitlisted · C-022

Payload

{
  "allocationId":      "ALO-20261001-00043",
  "itsId":             "ITS-1234567",
  "miqaatId":          "MQ-1447-KHI",
  "category":          "residential",
  "waitlistPosition":  14,
  "requestedBy":       "ams",
  "waitlistedAt":      "2026-07-15T10:30:01Z"
}

Field	Type	Required	Description
`allocationId`	string	✅	The allocation record identifier (waitlisted state)
`itsId`	string	✅	The Mumin placed on the waitlist
`miqaatId`	string	✅	The Miqaat scope
`category`	string	✅	Allocation category
`waitlistPosition`	integer	✅	Current position in the waitlist at time of placement
`requestedBy`	string	✅	The module that submitted the request
`waitlistedAt`	string (ISO 8601)	✅	When the Mumin was placed on the waitlist

allocation.released · C-022a

Payload

{
  "allocationId":   "ALO-20261001-00042",
  "itsId":          "ITS-1234567",
  "miqaatId":       "MQ-1447-KHI",
  "category":       "residential",
  "reason":         "cancelled_by_mumin",
  "releasedAt":     "2026-08-01T09:00:00Z",
  "releasedBy":     "ITS-1234567",
  "nextWaitlistId": "ITS-9876543"
}

Field	Type	Required	Description
`allocationId`	string	✅	The allocation that was released
`itsId`	string	✅	The Mumin whose allocation was released
`miqaatId`	string	✅	The Miqaat scope
`category`	string	✅	Allocation category
`reason`	string	✅	Why the allocation was released. Values: `cancelled_by_mumin` · `revoked_by_operator` · `capacity_change`
`releasedAt`	string (ISO 8601)	✅	When the release occurred
`releasedBy`	string	✅	itsId of the person who triggered the release
`nextWaitlistId`	string	❌	itsId of the next person on the waitlist who will be promoted. Absent if waitlist is empty.

capacity.imbalance.detected · C-023

Payload

{
  "miqaatId":   "MQ-1447-KHI",
  "detectedAt": "2026-06-12T08:00:01Z",
  "imbalances": [
    {
      "description":   "Vaaz capacity (8,000) is more than double Mawaid capacity (3,200). Ratio exceeds threshold.",
      "venueA":        "vaaz",
      "capacityA":     8000,
      "venueB":        "mawaid",
      "capacityB":     3200,
      "ratio":         2.5,
      "threshold":     2.0
    }
  ]
}

Field	Type	Required	Description
`miqaatId`	string	✅	The Miqaat where the imbalance was detected
`detectedAt`	string (ISO 8601)	✅	When the imbalance was detected
`imbalances`	array	✅	One object per detected imbalance
`imbalances[].description`	string	✅	Human-readable description for Platform Admin display
`imbalances[].venueA`	string	✅	First venue in the comparison
`imbalances[].capacityA`	integer	✅	Capacity reported by venueA
`imbalances[].venueB`	string	✅	Second venue in the comparison
`imbalances[].capacityB`	integer	✅	Capacity reported by venueB
`imbalances[].ratio`	number	✅	Actual ratio (capacityA / capacityB)
`imbalances[].threshold`	number	✅	The configured threshold that was exceeded

itsId is absent from the envelope — structural event, not person-specific.

eligibility.status.changed · C-024

Payload

{
  "itsId":          "ITS-1234567",
  "miqaatId":       "MQ-1447-KHI",
  "ruleSetId":      "ISTEFADAH_2026_GENTS",
  "previousStatus": "eligible",
  "newStatus":      "ineligible",
  "changedAt":      "2026-07-20T14:00:00Z",
  "reason":         "PRIOR_ATTENDANCE rule failed after ITS sync update"
}

Field	Type	Required	Description
`itsId`	string	✅	The Mumin whose eligibility changed
`miqaatId`	string	✅	The Miqaat scope
`ruleSetId`	string	✅	The rule set whose evaluation changed
`previousStatus`	string	✅	The eligibility status before this change. Values: `eligible` · `ineligible` · `unknown`
`newStatus`	string	✅	The new eligibility status
`changedAt`	string (ISO 8601)	✅	When the status changed
`reason`	string	❌	Human-readable description of what caused the status change — for logging and audit, not for display

role.assigned · C-025

Payload

{
  "itsId":       "ITS-1234567",
  "miqaatId":    "MQ-1447-KHI",
  "roleId":      "VMS_Coordinator",
  "assignedAt":  "2026-06-01T08:00:00Z",
  "assignedBy":  "ITS-9999999"
}

Field	Type	Required	Description
`itsId`	string	✅	The Mumin who was assigned the role
`miqaatId`	string	✅	The Miqaat scope the role applies in
`roleId`	string	✅	The role identifier assigned
`assignedAt`	string (ISO 8601)	✅	When the assignment occurred
`assignedBy`	string	✅	itsId of the Platform Admin user who made the assignment

role.revoked · C-026

Payload

{
  "itsId":      "ITS-1234567",
  "miqaatId":   "MQ-1447-KHI",
  "roleId":     "VMS_Coordinator",
  "revokedAt":  "2026-09-15T10:00:00Z",
  "revokedBy":  "ITS-9999999",
  "reason":     "Role reassigned to different coordinator"
}

Field	Type	Required	Description
`itsId`	string	✅	The Mumin whose role was revoked
`miqaatId`	string	✅	The Miqaat scope
`roleId`	string	✅	The role that was revoked
`revokedAt`	string (ISO 8601)	✅	When the revocation occurred
`revokedBy`	string	✅	itsId of the Platform Admin user who revoked it
`reason`	string	❌	Optional reason for revocation

Cache invalidation: any module that receives role.revoked must immediately clear its local permission cache for the affected itsId + miqaatId. See 03 — API Contracts, C-010.

4. Module-Published Event Schemas

Core subscribes to the events below. The schema here is the minimum Core requires from the payload. Modules may include additional fields — Core ignores unknown fields.

Module-published events that Core does not subscribe to (most of section 4 of the Event Catalog) are owned entirely by the module. Core does not define their payload schema.