Decision Log Specification
A decision log is a structured, machine-verifiable record of an AI system's inputs, outputs, and execution context — designed to enable traceability, auditing, and reproducibility across the AI lifecycle.
CertifiedData implements decision logs as cryptographic artifacts: SHA-256 fingerprinted, Ed25519-signed, and organized in a tamper-evident hash chain. This document is the normative schema reference.
Dual-chain architecture
CertifiedData maintains two parallel chains for every decision:
Internal chain
Full fidelity — actor identity, entity references, raw context, PII-containing fields. Access restricted to authenticated account holders.
Public chain
Sterilized — PII removed, governance-relevant fields retained. Publicly readable at /api/decision-log.
Schema — V1
{
// Required
"decision_id": "uuid",
"timestamp": "ISO-8601",
"record_hash": "sha256:...", // SHA-256 of RFC 8785 canonical payload
"previous_hash": "sha256:...", // null for genesis record
"selected_option": "string",
"reason_codes": ["string"],
"signature": "ed25519:...",
// Optional — present when provided at ingestion
"actor": { "type": "human|agent|system", "id": "string" },
"model": { "name": "string", "version": "string", "provider": "string" },
"policy": { "id": "string", "version": "string", "name": "string" },
"artifact_reference": {
"artifact_id": "string",
"cert_id": "string",
"artifact_type": "string"
},
"rationale_summary": "string", // sterilized in public chain
"evidence_refs": ["string"],
"human_override": false,
"approval_required": false,
"certificate_id": "cert_..." // links to CertifiedData artifact
}Required fields
Optional fields
Canonicalization and signing
Before hashing, the decision payload is canonicalized using RFC 8785 JSON Canonicalization Scheme. This ensures deterministic hashing across all platforms and runtimes — the same payload always produces the same hash, regardless of key ordering or whitespace.
- 1. Serialize decision fields using RFC 8785 canonical JSON
- 2. Compute SHA-256 of the canonical bytes →
record_hash - 3. Append
previous_hashfrom the preceding record - 4. Sign the canonical payload with Ed25519
- 5. Store record + signature in the chain
API reference
/v1/decisionsIngest a single decision record. Auth: Bearer JWT or x-api-key.
/v1/decisions/batchIngest up to 100 records in one request.
/v1/decisions/searchSearch internal records by actor_id, cert_id, date range.
/v1/decisions/exportJSONL export of decision records (streaming).
/api/decision-logPaginated public chain (sterilized). No auth required.
/api/decision-log/:idSingle public record by decision_id.
/api/decision-log/:id/verifyVerify record hash + signature. Returns chain position.
/api/decision-log/checkpoints/latestMost recent sealed checkpoint of the public chain.
Log checkpoints
Periodic sealed checkpoints are created over the public chain. Each checkpoint contains: record count, latest record hash, previous checkpoint hash — signed with Ed25519. Third parties can verify log continuity by checking checkpoint hashes without reading every individual record. Checkpoints are created on a scheduled basis viaPOST /api/decision-log/checkpoints/create(CRON_SECRET gated).
Comparison to traditional logging
Traditional logs
- • Mutable application records
- • Internal-only — not independently auditable
- • No cryptographic proof of integrity
- • Inconsistent schema across systems
CertifiedData decision logs
- • SHA-256 + Ed25519 signed — tamper-evident
- • Public chain — independently auditable
- • Hash-chained — chain breaks on tampering
- • Normative schema — this document
Start logging decisions
Ingest decision records via API. Each record is cryptographically signed and published to the public transparency chain.