Home / Integration / Event catalog / Event envelope format.html

Event Envelope Format

Overview

All events in the Paklog platform follow the CloudEvents 1.0 Specification. This document defines the standard envelope format, conventions, and extensions used across all bounded contexts.

CloudEvents Envelope

Required Attributes

Attribute Type Description Example
specversion String CloudEvents spec version "1.0"
type String Event type identifier "com.paklog.processpath.shipment.routed.v1"
source URI Event producer identifier "/process-path-service"
id String Unique event identifier "evt-a1b2c3d4-e5f6-7890-abcd-ef1234567890"
Attribute Type Description Example
time Timestamp Event timestamp (RFC 3339) "2025-01-20T10:00:00.000Z"
datacontenttype String Content type of data "application/json"
subject String Event subject/entity ID "SHP-123456"
dataschema URI Schema URL "https://schema.paklog.com/processpath/v1/shipment-routed.json"

Type Naming Convention

1

com.paklog.{context}.{aggregate}.{action}.v{version}
Component Description Examples
com.paklog Organization namespace Always com.paklog
{context} Bounded context name processpath, order, inventory
{aggregate} Aggregate or entity shipment, path, wall, tray
{action} Past-tense action routed, allocated, changed, failed
v{version} Major version v1, v2

Examples:

Source Naming Convention

1

/{service-name}
Service Source
Process Path Service /process-path-service
Order Management /order-management-service
Inventory Service /inventory-service
WES Orchestration /wes-orchestration-engine
Wave Planning /wave-planning-service
Pack & Ship /pack-ship-service

Event ID Format

Event IDs use UUID v4 with a prefix:

1

evt-{uuid-v4}

Example: evt-a1b2c3d4-e5f6-7890-abcd-ef1234567890

Timestamp Format

All timestamps use RFC 3339 format with millisecond precision in UTC:

1

YYYY-MM-DDTHH:mm:ss.sssZ

Example: 2025-01-20T10:00:00.000Z

Complete Event Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

{
  "specversion": "1.0",
  "type": "com.paklog.processpath.shipment.routed.v1",
  "source": "/process-path-service",
  "id": "evt-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "time": "2025-01-20T10:00:00.000Z",
  "datacontenttype": "application/json",
  "subject": "SHP-123456",
  "dataschema": "https://schema.paklog.com/processpath/v1/shipment-routed.json",
  "data": {
    "shipmentId": "SHP-123456",
    "orderId": "ORD-789012",
    "assignedPath": "AFE",
    "pathId": "PATH-AFE-01",
    "routingScore": 87.5,
    "routingFactors": {
      "capacityScore": 15.0,
      "bufferScore": 30.0,
      "laborScore": 22.5,
      "affinityScore": 20.0
    },
    "shipmentType": "MULTI",
    "itemCount": 3,
    "slaPriority": "GREEN",
    "estimatedCycleTime": "PT15M",
    "carrierCutoffTime": "2025-01-20T16:00:00Z",
    "routedAt": "2025-01-20T10:00:00Z"
  }
}

Paklog Extension Attributes

In addition to standard CloudEvents attributes, Paklog defines extension attributes:

Extension Type Description Example
correlationid String Trace correlation ID "corr-xyz123"
causationid String Causing event ID "evt-previous-123"
tenantid String Multi-tenant identifier "tenant-us-east"
warehouseid String Warehouse identifier "WH-001"
partitionkey String Kafka partition key "SHP-123456"

Extension Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
  "specversion": "1.0",
  "type": "com.paklog.processpath.shipment.routed.v1",
  "source": "/process-path-service",
  "id": "evt-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "time": "2025-01-20T10:00:00.000Z",
  "datacontenttype": "application/json",
  "subject": "SHP-123456",
  "correlationid": "corr-order-789012",
  "causationid": "evt-order-released-123",
  "warehouseid": "WH-001",
  "partitionkey": "SHP-123456",
  "data": {
    ...
  }
}

Kafka Message Format

Events are published to Kafka with the following structure:

Message Key

1

{partitionkey}

Default: subject attribute value (e.g., SHP-123456)

Message Headers

Header Value Purpose
ce_specversion 1.0 CloudEvents version
ce_type Event type Routing/filtering
ce_source Source URI Origin identification
ce_id Event ID Deduplication
ce_time Timestamp Ordering
content-type application/cloudevents+json Format indicator
ce_correlationid Correlation ID Tracing

Message Value

1
2
3
4
5

{
  "specversion": "1.0",
  "type": "com.paklog.processpath.shipment.routed.v1",
  ...
}

Schema Registry

Schema Naming Convention

1

com.paklog.{context}.{aggregate}.{action}.v{version}

Matches the event type attribute.

Compatibility Mode

Level Mode Description
Subject BACKWARD New schemas can read old data
Global BACKWARD_TRANSITIVE Full backward compatibility chain

Schema Evolution Rules

Allowed Changes (Backward Compatible):

Breaking Changes (Require New Version):

Error Events

Error events follow a standard format:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

{
  "specversion": "1.0",
  "type": "com.paklog.processpath.assignment.failed.v1",
  "source": "/process-path-service",
  "id": "evt-error-123456",
  "time": "2025-01-20T10:00:00.000Z",
  "datacontenttype": "application/json",
  "subject": "SHP-123456",
  "data": {
    "errorCode": "NO_ELIGIBLE_PATH",
    "errorMessage": "No path available for shipment with current properties",
    "errorDetails": {
      "shipmentId": "SHP-123456",
      "attemptedPaths": ["SINGLES", "AFE", "BATCH_FLOW"],
      "rejectionReasons": {
        "SINGLES": "MULTI_ITEM_ORDER",
        "AFE": "UTILIZATION_CRITICAL",
        "BATCH_FLOW": "NO_WAVE_SCHEDULED"
      }
    },
    "retryable": true,
    "retryAfter": "PT5M",
    "occurredAt": "2025-01-20T10:00:00Z"
  }
}

Standard Error Codes

Code Description Retryable
NO_ELIGIBLE_PATH No path can handle shipment Yes
ALL_PATHS_CONSTRAINED All paths at capacity Yes
SLA_UNACHIEVABLE Cannot meet SLA deadline No
INVALID_SHIPMENT_PROPERTIES Bad input data No
SERVICE_UNAVAILABLE Downstream service down Yes

Dead Letter Queue

Failed events are routed to DLQ with additional metadata:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{
  "specversion": "1.0",
  "type": "com.paklog.dlq.event.v1",
  "source": "/process-path-service",
  "id": "evt-dlq-123456",
  "time": "2025-01-20T10:05:00.000Z",
  "data": {
    "originalEvent": {
      ... // Original event payload
    },
    "failureReason": "PROCESSING_EXCEPTION",
    "exceptionMessage": "NullPointerException at PathAssignmentService.java:123",
    "retryCount": 3,
    "firstFailureAt": "2025-01-20T10:00:00.000Z",
    "lastFailureAt": "2025-01-20T10:05:00.000Z",
    "consumerGroup": "process-path-service-group"
  }
}

Idempotency

Producer Idempotency

Events include deterministic IDs for deduplication:

1

evt-{context}-{aggregate}-{action}-{entityId}-{timestamp-hash}

Consumer Idempotency

Consumers maintain processed event registry:

Field Purpose
event_id CloudEvents ID
processed_at Processing timestamp
outcome SUCCESS/FAILURE
idempotency_key Business key for dedup

Observability

Tracing Headers

Header Purpose Example
traceparent W3C Trace Context 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
tracestate Vendor-specific data paklog=process-path
ce_correlationid Business correlation corr-order-789012

Metrics

Metric Labels Description
events_published_total type, source Published event count
events_consumed_total type, consumer Consumed event count
event_processing_duration_seconds type, consumer Processing latency
event_failures_total type, consumer, error Failed event count