SnapOS Specifications

Home / JSON Schemas

This page lists the structure of the JSON bundles generated by the SnapOS Systemic Order Test dashboard. These schemas describe how audit scores and supporting evidence are serialised for sharing and reproducibility. All fields are shown with example values for clarity.

1. Audit Bundle (snapos_bundle.json)

The audit bundle combines summary scores, per‑metric scores, forecast information, and embedded evidence documents. A bundle always contains the following top‑level keys:

{
  "summary": {
    "company": "ACME Payments EU",
    "period": "Q3/2025",
    "score": 72,
    "median": 65,
    "delta": 7,
    "regime": "mid",
    "cost": 4800000
  },
  "scores": {
    "tr": 80,
    "rb": 75,
    "ttd": 55,
    "inc": 85,
    "cost": 60,
    "comp": 70,
    "sup": 50,
    "resp": 65,
    "mu": 60,
    "snapcuts": 70,
    "orbit": 55,
    "trueclaim": 75,
    "benchmark": 65
  },
  "forecast": {
    "regime": "mid",
    "score": 60,
    "band": [0.25, 0.40],
    "q25": 0.22,
    "q75": 0.36
  },
  "oief": { /* see below */ },
  "rcp": { /* see below */ },
  "origin": "local"
}

Use the summary object to convey the overall interpretation, and the scores object for individual metrics. The forecast object summarises recent quantile analysis. The oief and rcp keys embed the evidence documents described below.

2. Operational Incident Evidence File (OIEF)

The OIEF object records the context of an assessment and cryptographically binds it to the original input. It contains:

{
  "id": "oief-1699917785123",
  "ts": "2025-11-08T12:33:45.678Z",
  "actor": "ops-risk",
  "action": "ASSESS",
  "object": "payments:EU",
  "version": "Q3/2025",
  "evidence": [
    { "kind": "score", "uri": "local://score", "hash": "sha256:72" },
    { "kind": "cost", "uri": "local://annual_cost", "hash": "sha256:4800000" }
  ],
  "labels": {
    "company": "ACME Payments EU"
  },
  "origin": "local",
  "origin_fingerprint": "1a2b3c4d5e6f7890",
  "sig": "hmac256.0af4c3d88e9a0b3c"
}

Explanation of fields:

• id: Unique identifier generated at the time of export.
• ts: Timestamp (ISO 8601) of the export.
• actor/action: Audit role and verb.
• object: Canonical domain and region pair.
• version: Reporting period.
• evidence: Array of references linking to local data (e.g. score, cost) with hashed values.
• labels: Additional metadata (e.g. company name).
• origin: Origin context of the assessment ("local" for browser).
• origin_fingerprint: Hash of the origin identifier (privacy preserving).
• sig: Cryptographic signature (HMAC) over the entire document for tamper detection.

3. Rollback Contingency Plan (RCP)

The RCP object describes the planned rollback steps for the evaluated system in case of an adverse incident:

{
  "plan_id": "rcp-default-rollback",
  "target": "release/24.6",
  "trigger": "critical:red>2h",
  "steps": [
    "throttle 50%",
    "rollback",
    "smoke tests",
    "restore"
  ],
  "sla_hours": 48,
  "owner": "ops-lead",
  "test_evidence": [],
  "origin": "local",
  "origin_fingerprint": "1a2b3c4d5e6f7890",
  "sig": "hmac256.7e9f1b2c3d4e5f6a"
}

Explanation of fields:

• plan_id: Identifier of the rollback plan.
• target: Target state after rollback (e.g. release version).
• trigger: Condition that triggers the rollback.
• steps: Ordered list of actions to return to the target state.
• sla_hours: Maximum allowable downtime in hours.
• owner: Role responsible for executing the plan.
• test_evidence: Evidence of plan rehearsal (currently empty; reserved for future use).
• origin and origin_fingerprint: Same as in the OIEF.
• sig: HMAC signature over the document.

4. Using these schemas

These structures are intentionally minimal to ensure that you can verify and reproduce audits without storing personal data. They can be extended with additional evidence types, cryptographic hashes, or domain‑specific labels as needed. When you generate downloads from the SnapOS dashboard, the exported files follow these structures exactly.

© 2025 Marko Chalupa – SnapOS Foundation. All specifications are released under CC BY‑NC‑ND 4.0 and AuditCore Licence v1.2. Redistribution with attribution permitted; commercial or derivative use requires written authorization.