​

Canonical JSON

​

Rules

1. Keys sorted alphabetically — recursive for nested objects
2. Compact format — no whitespace (separators: , and :)
3. Exclude hash and signature — these fields are not part of the hash input
4. Exclude null/None fields — omitted entirely, not serialized as null
5. UTF-8 encoding — consistent byte representation

​

Example

{
  "event_id": "abc-123",
  "event_type": "myapp.user.login",
  "timestamp": "2025-01-15T10:30:00Z",
  "actor_id": "user-42",
  "tenant_id": "acme-corp",
  "trace_id": null,
  "session_id": null,
  "payload": { "method": "oauth", "ip": "1.2.3.4" },
  "prev_hash": "0000...0000",
  "hash": "a1b2c3...",
  "signature": "hmac-sha256:..."
}

{"actor_id":"user-42","event_id":"abc-123","event_type":"myapp.user.login","payload":{"ip":"1.2.3.4","method":"oauth"},"prev_hash":"0000...0000","tenant_id":"acme-corp","timestamp":"2025-01-15T10:30:00Z"}

• Keys are sorted alphabetically (actor_id before event_id before event_type…)
• hash and signature are excluded
• trace_id and session_id are excluded because they’re null
• Payload keys are also sorted (ip before method)
• No whitespace

​

Nested Objects

payload = {
    "details": {
        "score": 0.95,
        "action": "approved",
    },
    "actor": "agent-47",
}

# Canonical: {"actor":"agent-47","details":{"action":"approved","score":0.95}}

​

Hash Computation

hash = SHA-256(prev_hash + canonical_json(event))

​

Next Steps