Documentation · schema version 1.0

Approval change record: export schema

SanctumShield keeps a dated record of who approved each agent, on what terms, and every change since. The record lives in the organization’s Decisions log. This page documents the file a customer can download from it: one JSON file, built in the customer’s browser, that a partner or a tool can read.

It is the organization’s own record. SanctumShield records what the organization states, with its date. It does not observe agents and does not confirm that an event took place. The file says so itself: attestation_basis is always "self_reported".

Where the values come from

Nobody fills in anything for this file. Every event is a row of the Decisions log about an agent; the agent fields come from the agent inventory the review already holds.

  • Decision “Approved” is exported as granted.
  • “Access widened” is scope_expanded; “Access narrowed” is scope_narrowed.
  • “Replaced an earlier approval” is superseded, and supersedes holds the event_id of the agent’s latest earlier approval. The pointer is worked out from the log, not typed.
  • “Stopped” is withdrawn.
  • The agent’s recorded stop test is stop_tested. It is read from the stop fields on the agent and is not a Decisions log row.
  • A row that says “Changed” (from before that choice was split in two) is exported with event_type null and event_type_status "unknown": a change whose direction was not recorded.
  • “Declined” and “Risk accepted” rows changed nothing an agent may do and are left out. Rows about tools that are not agents are left out.

Two dates, kept apart

effective_from is when the change took effect: the Date of the Decisions log row. It may be a date without a time. recorded_at is when a review captured the row. It is filled in automatically. Rows written before November 15, 2026, and rows that came back from a Light or Standard answers file, carry no captured moment; for those recorded_at is null with recorded_at_status "not_recorded".

Unknowns are stated, never left out

A field that is not known is present with the value null and a matching status field, so a receiving system can tell “not known” from “does not apply”. For a field named x the status field is x_status, and it is required whenever x is null.

  • "unknown": the organization said it does not know (for example, a date answered “Not sure”).
  • "not_recorded": nothing was entered.
  • "not_applicable": the field has no meaning for this event (for example, supersedes on a first approval).

“Not sure” is a complete answer. When a person answers Not sure to “Has anything about this agent changed since the last review?”, the agent’s change_review.answer is null with answer_status "unknown" and the moment they answered. It is never written as an event.

The freshness boundary

snapshot_as_of is the moment the file was produced. The file covers only what the organization had recorded up to that moment. Every file carries this statement:

This file covers only the events the organization had recorded up to snapshot_as_of. Every entry was stated by the organization; SanctumShield recorded it with its date, did not observe the agents and does not confirm that an event took place. The file cannot establish that no later change or withdrawal occurred. Treat anything after snapshot_as_of as unknown.

Identifiers

agent_id is made from the agent’s name, so it stays the same across re-runs and re-imports of the workbook; renaming an agent changes it. event_id is worked out from the row itself (agent, date, decision, who decided, and its position among rows identical in those four), so it also stays the same across re-runs and re-imports without any stored id. The limit: editing one of those four values in the Decisions log gives the row a new event_id. To correct a row, add a new one.

Fingerprint and Verification URL

The browser computes the SHA-256 fingerprint of the exact file it downloads. Each export gets its own Verification URL, issued the same way as for the four documents: SanctumShield records the date, the organization name, the registry version and the fingerprint, for six years. The file’s contents are not sent to SanctumShield and are not stored. The Verification ID is the last part of the file name. A recipient can confirm that the file matches the fingerprint SanctumShield recorded on that date: a dated, third-party-verifiable check of the file, not of the events in it.

Names are personal data

decided_by and issuer may hold a name or a role. A role alone is accepted everywhere. The organization chooses what it records and whom it shares the file with.

Top level

FieldTypeAllowed valuesMeaning
_aboutstringA plain sentence a person can read: what this file is and where its fields are documented.
schema_versionstring"1.0"
schemastringWhere this JSON Schema is published.
organizationobjectThe organization the record belongs to.
snapshot_as_ofstringISO 8601 date or date and timeThe moment the file was produced (ISO 8601). The file says nothing about anything after this moment.
attestation_basisstring"self_reported"Every entry was stated by the organization.
freshness_statementstringThe freshness boundary in words: the file covers only events recorded up to snapshot_as_of, was stated by the organization, and cannot establish that no later change occurred.
agentsarray of objectsEvery agent the record speaks about.
eventsarray of objectsEvery recorded event, oldest entry first within each agent. Events are never edited or removed; a correction is a later event.
last_assessment_atwith last_assessment_at_statusstring or nullISO 8601 dateThe date of the review this file was produced from.
next_review_duewith next_review_due_statusstring or nullISO 8601 dateThe date the organization has set for its next review.

agents[]

One entry for every agent the record speaks about.

FieldTypeAllowed valuesMeaning
agent_idstringStable across re-runs and re-imports.
actorstringThe agent's name.
in_inventorybooleanFalse when the agent has history but is no longer listed in the organization's inventory.
change_reviewobjectThe answer, in this review, to: has anything about this agent changed since the last review? A person who answered Not sure is recorded as answer null with answer_status unknown and the moment they answered. It is never recorded as an event.
issuerwith issuer_statusstring or nullWho holds the authority to approve this agent: the agent's recorded owner or approver. A name or a role.
operationwith operation_statusstring or nullWhat the agent is for, as the organization recorded it.
scopewith scope_statusstring or nullWhat the agent can reach or do, in plain words, as the organization recorded it.

agents[].change_review

FieldTypeAllowed valuesMeaning
answerwith answer_statusstring or null"no_change", "changed", nullno_change or changed.
answered_atwith answered_at_statusstring or nullISO 8601 date or date and timeWhen the answer was given (ISO 8601).

events[]

One entry per event. Events are never edited or removed by the export; a correction is a later event.

FieldTypeAllowed valuesMeaning
event_idstringStable across re-runs and re-imports.
agent_idstring
actorstringThe agent's name.
event_typewith event_type_statusstring or null"granted", "scope_expanded", "scope_narrowed", "superseded", "withdrawn", "stop_tested", nullWhat happened. Null with event_type_status unknown for a change whose direction (wider or narrower) was not recorded.
issuerwith issuer_statusstring or nullWho holds the authority to approve this agent: the agent's recorded owner or approver. A name or a role.
decided_bywith decided_by_statusstring or nullWho made this change. A name or a role; a role alone is accepted.
operationwith operation_statusstring or nullWhat the agent is for, as the organization recorded it.
scopewith scope_statusstring or nullWhat the agent can reach or do, in plain words, as the organization recorded it.
supersedeswith supersedes_statusstring or nullFor a superseded event: the event_id of the approval it replaces.
effective_fromwith effective_from_statusstring or nullISO 8601 date or date and timeWhen the change took effect (ISO 8601; may be a date only).
effective_towith effective_to_statusstring or nullISO 8601 date or date and timeFor an approval that a later event replaced or withdrew: when it stopped applying.
recorded_atwith recorded_at_statusstring or nullISO 8601 date or date and timeWhen a review captured the event (ISO 8601). Kept apart from effective_from.
reasonwith reason_statusstring or nullWhy, in the organization's words.
evidencewith evidence_statusstring or nullA reference the organization provides (for example a ticket number). Never stored content.
assessment_run_idwith assessment_run_id_statusstring or nullThe review the event was recorded in.

A short example

Taken from the synthetic sample (a fictional company): one agent answered Not sure, with a first approval and a later change whose date is not known.

{
  "_about": "SanctumShield approval change record. The organization's own dated record of who approved each agent and every change since. Self-reported; covers events recorded up to snapshot_as_of only. Field reference: https://sanctumshield.com/docs/authority-record-schema",
  "schema_version": "1.0",
  "schema": "https://sanctumshield.com/schemas/authority-record-1.0.schema.json",
  "organization": {
    "name": "Acme Health, Inc."
  },
  "snapshot_as_of": "2026-11-15T16:00:00.000Z",
  "last_assessment_at": "2026-11-15",
  "next_review_due": null,
  "next_review_due_status": "not_recorded",
  "attestation_basis": "self_reported",
  "freshness_statement": "This file covers only the events the organization had recorded up to snapshot_as_of. Every entry was stated by the organization; SanctumShield recorded it with its date, did not observe the agents and does not confirm that an event took place. The file cannot establish that no later change or withdrawal occurred. Treat anything after snapshot_as_of as unknown.",
  "agents": [
    {
      "agent_id": "agent-claims-appeal-drafting-agent",
      "actor": "Claims appeal drafting agent",
      "in_inventory": true,
      "issuer": "Claims Operations Manager",
      "operation": "Drafts appeal letters for a claims specialist to approve",
      "scope": "runs on Microsoft Copilot Studio",
      "change_review": {
        "answer": null,
        "answer_status": "unknown",
        "answered_at": "2026-11-15T15:00:00.000Z"
      }
    }
  ],
  "events": [
    {
      "event_id": "evt-47f45fb36b7c2a24",
      "agent_id": "agent-claims-appeal-drafting-agent",
      "actor": "Claims appeal drafting agent",
      "issuer": "Claims Operations Manager",
      "operation": "Drafts appeal letters for a claims specialist to approve",
      "scope": "runs on Microsoft Copilot Studio",
      "decided_by": "Claims Operations Manager",
      "event_type": "granted",
      "supersedes": null,
      "supersedes_status": "not_applicable",
      "effective_from": "2026-03-09",
      "effective_to": null,
      "effective_to_status": "not_applicable",
      "recorded_at": null,
      "recorded_at_status": "not_recorded",
      "reason": null,
      "reason_status": "not_recorded",
      "evidence": null,
      "evidence_status": "not_recorded",
      "assessment_run_id": null,
      "assessment_run_id_status": "not_recorded"
    },
    {
      "event_id": "evt-afc7565c02a0fbff",
      "agent_id": "agent-claims-appeal-drafting-agent",
      "actor": "Claims appeal drafting agent",
      "issuer": "Claims Operations Manager",
      "operation": "Drafts appeal letters for a claims specialist to approve",
      "scope": "runs on Microsoft Copilot Studio",
      "decided_by": "Claims Operations Manager",
      "event_type": "scope_expanded",
      "supersedes": null,
      "supersedes_status": "not_applicable",
      "effective_from": null,
      "effective_from_status": "unknown",
      "effective_to": null,
      "effective_to_status": "not_applicable",
      "recorded_at": "2026-05-04T15:00:00.000Z",
      "reason": "Connected to the shared appeals mailbox",
      "evidence": null,
      "evidence_status": "not_recorded",
      "assessment_run_id": "review-2026-05-04"
    }
  ]
}

Versions

Version 1.0, November 15, 2026: first published version. A change that removes or renames a field, or changes its meaning, gets a new version number and a new schema file; earlier schema files stay at their addresses.

Approval change record: export schema — SanctumShield