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
| Field | Type | Allowed values | Meaning |
|---|---|---|---|
| _about | string | A plain sentence a person can read: what this file is and where its fields are documented. | |
| schema_version | string | "1.0" | |
| schema | string | Where this JSON Schema is published. | |
| organization | object | The organization the record belongs to. | |
| snapshot_as_of | string | ISO 8601 date or date and time | The moment the file was produced (ISO 8601). The file says nothing about anything after this moment. |
| attestation_basis | string | "self_reported" | Every entry was stated by the organization. |
| freshness_statement | string | The 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. | |
| agents | array of objects | Every agent the record speaks about. | |
| events | array of objects | Every 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_status | string or null | ISO 8601 date | The date of the review this file was produced from. |
| next_review_duewith next_review_due_status | string or null | ISO 8601 date | The date the organization has set for its next review. |
agents[]
One entry for every agent the record speaks about.
| Field | Type | Allowed values | Meaning |
|---|---|---|---|
| agent_id | string | Stable across re-runs and re-imports. | |
| actor | string | The agent's name. | |
| in_inventory | boolean | False when the agent has history but is no longer listed in the organization's inventory. | |
| change_review | object | The 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_status | string or null | Who holds the authority to approve this agent: the agent's recorded owner or approver. A name or a role. | |
| operationwith operation_status | string or null | What the agent is for, as the organization recorded it. | |
| scopewith scope_status | string or null | What the agent can reach or do, in plain words, as the organization recorded it. |
agents[].change_review
| Field | Type | Allowed values | Meaning |
|---|---|---|---|
| answerwith answer_status | string or null | "no_change", "changed", null | no_change or changed. |
| answered_atwith answered_at_status | string or null | ISO 8601 date or date and time | When 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.
| Field | Type | Allowed values | Meaning |
|---|---|---|---|
| event_id | string | Stable across re-runs and re-imports. | |
| agent_id | string | ||
| actor | string | The agent's name. | |
| event_typewith event_type_status | string or null | "granted", "scope_expanded", "scope_narrowed", "superseded", "withdrawn", "stop_tested", null | What happened. Null with event_type_status unknown for a change whose direction (wider or narrower) was not recorded. |
| issuerwith issuer_status | string or null | Who holds the authority to approve this agent: the agent's recorded owner or approver. A name or a role. | |
| decided_bywith decided_by_status | string or null | Who made this change. A name or a role; a role alone is accepted. | |
| operationwith operation_status | string or null | What the agent is for, as the organization recorded it. | |
| scopewith scope_status | string or null | What the agent can reach or do, in plain words, as the organization recorded it. | |
| supersedeswith supersedes_status | string or null | For a superseded event: the event_id of the approval it replaces. | |
| effective_fromwith effective_from_status | string or null | ISO 8601 date or date and time | When the change took effect (ISO 8601; may be a date only). |
| effective_towith effective_to_status | string or null | ISO 8601 date or date and time | For an approval that a later event replaced or withdrew: when it stopped applying. |
| recorded_atwith recorded_at_status | string or null | ISO 8601 date or date and time | When a review captured the event (ISO 8601). Kept apart from effective_from. |
| reasonwith reason_status | string or null | Why, in the organization's words. | |
| evidencewith evidence_status | string or null | A reference the organization provides (for example a ticket number). Never stored content. | |
| assessment_run_idwith assessment_run_id_status | string or null | The 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.