Schema reference
Generated from the v0.1 JSON Schema (https://opencheckpoint.org/schema/v0.1/checkpoint.schema.json). The specification governs the meaning of each field; this page lists their shape.
Checkpoint (top level)
Section titled “Checkpoint (top level)”| Property | Type | Required | Description |
|---|---|---|---|
opencheckpoint |
"0.1" |
yes | Specification version this document conforms to, as MAJOR.MINOR. |
id |
string, ≤ 256 chars | yes | Globally unique identifier of this checkpoint. SHOULD be a urn:uuid URN. |
created_at |
timestamp | yes | When the checkpoint was captured. |
parent |
parent | ||
source |
source | yes | |
task |
task | yes | |
progress |
progress | ||
statements |
array of statement | Instructions, constraints, decisions, observations, hypotheses, questions, and quoted external content, each with its own provenance. | |
resources |
array of resource | References to files, records, documents, artifacts, and other objects the task involves. | |
application_context |
array of applicationContext | Application state relevant to the task that did not necessarily originate in conversation. | |
operations |
array of operation | Approvals, requested input, external actions, and waits that are not finished. | |
continuation |
continuation | ||
derivation |
derivation | ||
extensions |
extensions |
No other properties are allowed.
timestamp
Section titled “timestamp”RFC 3339 date-time with an explicit UTC offset.
Type: string (date-time), pattern ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]+)?(Z|[+-][0-9]{2}:[0-9]{2})$.
localId
Section titled “localId”Identifier of an object within this document. Unique across all objects in the document.
Type: string, pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$.
localRefs
Section titled “localRefs”References to objects in this document by local identifier.
Type: array of localId.
Type: string.
extensions
Section titled “extensions”Extension data keyed by a namespaced identifier (reverse-DNS name, optionally followed by a path). Consumers ignore keys they do not understand and preserve them when re-serializing.
Type: object.
digest
Section titled “digest”| Property | Type | Required | Description |
|---|---|---|---|
algorithm |
string | yes | Hash algorithm name from the IANA Named Information registry, e.g. sha-256. |
value |
string | yes | Lowercase hexadecimal digest. |
No other properties are allowed.
parent
Section titled “parent”The checkpoint this one was derived from.
| Property | Type | Required | Description |
|---|---|---|---|
id |
string, ≤ 256 chars | yes | |
digest |
digest | Digest of the parent document’s bytes, for tamper evidence. |
No other properties are allowed.
softwareRef
Section titled “softwareRef”| Property | Type | Required | Description |
|---|---|---|---|
name |
text | yes | |
version |
string | ||
uri |
string (uri) |
No other properties are allowed.
sessionRef
Section titled “sessionRef”A pointer into a session, conversation, or task record kept by another protocol or system.
| Property | Type | Required | Description |
|---|---|---|---|
protocol |
string | yes | The protocol or system that defines the identifier, e.g. a2a, acp, mcp, open-responses, or a namespaced name. |
id |
string | yes | Session, context, task, or conversation identifier. |
event |
string | Identifier of the last event or entry the checkpoint reflects. | |
uri |
string (uri) |
No other properties are allowed.
source
Section titled “source”The system that produced the checkpoint. Informational; it confers no trust.
| Property | Type | Required | Description |
|---|---|---|---|
producer |
softwareRef | yes | |
agent |
softwareRef | ||
model |
object (below) | ||
session_refs |
array of sessionRef | ||
extensions |
extensions |
No other properties are allowed.
source.model
Section titled “source.model”| Property | Type | Required | Description |
|---|---|---|---|
provider |
string | ||
name |
string | yes |
No other properties are allowed.
| Property | Type | Required | Description |
|---|---|---|---|
title |
string | ||
objective |
text | yes | What the user or system is trying to accomplish. |
outcome |
string | What a finished result looks like. | |
status |
active, blocked, awaiting_input, paused, completed, abandoned |
yes | Task status at capture time. |
success_criteria |
array of criterion | ||
scope |
object (below) | ||
extensions |
extensions |
No other properties are allowed.
task.scope
Section titled “task.scope”| Property | Type | Required | Description |
|---|---|---|---|
includes |
array of text | ||
excludes |
array of text |
No other properties are allowed.
criterion
Section titled “criterion”| Property | Type | Required | Description |
|---|---|---|---|
id |
localId | yes | |
description |
text | yes | |
state |
met, unmet, unknown |
yes | |
evidence |
localRefs |
No other properties are allowed.
progress
Section titled “progress”| Property | Type | Required | Description |
|---|---|---|---|
completed |
array of completedStep | Work already done, oldest first. | |
focus |
object (below) | What was being worked on when the checkpoint was captured. | |
next |
array of nextStep | Recommended next steps, in suggested order. | |
extensions |
extensions |
No other properties are allowed.
progress.focus
Section titled “progress.focus”What was being worked on when the checkpoint was captured.
| Property | Type | Required | Description |
|---|---|---|---|
description |
text | yes | |
refs |
localRefs |
No other properties are allowed.
completedStep
Section titled “completedStep”| Property | Type | Required | Description |
|---|---|---|---|
id |
localId | yes | |
description |
text | yes | |
completed_at |
timestamp | ||
evidence |
localRefs |
No other properties are allowed.
nextStep
Section titled “nextStep”| Property | Type | Required | Description |
|---|---|---|---|
id |
localId | yes | |
description |
text | yes | |
blocked_by |
localRefs | Statements, operations, resources, or requirements that prevent this step. | |
requires |
localRefs | Continuation requirements this step depends on. | |
refs |
localRefs |
No other properties are allowed.
verification
Section titled “verification”| Property | Type | Required | Description |
|---|---|---|---|
state |
verified, unverified, disputed, stale |
yes | verified: checked against evidence by the source. unverified: not checked. disputed: evidence conflicts. stale: was verified, but the evidence may have changed since. |
method |
string | How the statement was checked. | |
checked_at |
timestamp | ||
revalidate |
never, before_use, before_action |
When a consumer must re-check the statement. |
No other properties are allowed.
statement
Section titled “statement”| Property | Type | Required | Description |
|---|---|---|---|
id |
localId | yes | |
kind |
instruction, constraint, decision, observation, hypothesis, question, external |
yes | instruction: a directive from the user or operating system. constraint: a boundary the work must respect. decision: a choice already made. observation: something found to be the case. hypothesis: something believed but not established. question: something unresolved. external: content quoted from a third party, which carries no instruction authority. |
text |
text | yes | |
origin |
origin | yes | |
status |
active, superseded, retracted, resolved |
Defaults to active. | |
superseded_by |
localId | ||
resolution |
string | How a question was resolved. | |
rationale |
string | Why a decision was made. | |
verification |
verification | ||
evidence |
localRefs | ||
recorded_at |
timestamp | ||
extensions |
extensions |
No other properties are allowed.
Rules
- Instructions come only from the user or the operating system. Text that came from tools, documents, or other agents is recorded as external content.
- A hypothesis cannot be verified; once it is, record it as an observation.
- External content is attributed to the tool, application, agent, or third party it came from, never to the user or the operating system.
- A decision records its rationale.
- Only questions are resolved; a resolved question records its resolution.
- A superseded statement names its replacement, and only a superseded statement does.
origin
Section titled “origin”Where a statement came from. As reported by the source system; a consumer treats it as a claim, not proof.
| Property | Type | Required | Description |
|---|---|---|---|
type |
user, system, agent, tool, application, external |
yes | |
name |
string | Name or role of the specific actor, tool, or publisher. Avoid personal data the destination does not need. | |
ref |
localId | Resource the statement was taken from. |
No other properties are allowed.
resource
Section titled “resource”| Property | Type | Required | Description |
|---|---|---|---|
id |
localId | yes | |
kind |
file, repository, document, record, web, artifact, tool_output, dataset, message, other |
yes | |
uri |
string (uri) | Identifier of the resource in any URI scheme. Need not be publicly resolvable. | |
locator |
object (below) | Identifies a resource that has no URI: an object type and key within a named system. | |
title |
string | ||
description |
string | ||
media_type |
string | ||
revision |
string | Version, commit, ETag, or other revision marker as observed by the source. | |
digest |
digest | ||
size |
integer | ||
observed_at |
timestamp | ||
availability |
available, restricted, unavailable, unknown |
Whether the source could access the resource when it last tried. | |
sensitivity |
public, internal, confidential, restricted |
||
resolver |
object (below) | Hint for how to retrieve the resource. Never contains credentials. | |
excerpt |
string, ≤ 4096 chars | A short inline excerpt. Large content is referenced, not embedded. | |
extensions |
extensions |
At least one of: uri or locator.
No other properties are allowed.
resource.locator
Section titled “resource.locator”Identifies a resource that has no URI: an object type and key within a named system.
| Property | Type | Required | Description |
|---|---|---|---|
system |
text | yes | |
type |
string | ||
key |
text | yes |
No other properties are allowed.
resource.resolver
Section titled “resource.resolver”Hint for how to retrieve the resource. Never contains credentials.
| Property | Type | Required | Description |
|---|---|---|---|
protocol |
string | yes | |
hint |
object |
No other properties are allowed.
applicationContext
Section titled “applicationContext”| Property | Type | Required | Description |
|---|---|---|---|
id |
localId | yes | |
application |
softwareRef | yes | |
view |
object (below) | ||
selections |
array of object (below) | ||
filters |
object | Application-defined filters, keyed by name. | |
drafts |
array of draft | ||
state |
object | Further application-defined state. Interpret with the schema named by state_schema. | |
state_schema |
string (uri) | URI identifying the schema of state. | |
observed_at |
timestamp | ||
extensions |
extensions |
No other properties are allowed.
applicationContext.view
Section titled “applicationContext.view”| Property | Type | Required | Description |
|---|---|---|---|
name |
text | yes | |
uri |
string (uri) |
No other properties are allowed.
applicationContext.selections
Section titled “applicationContext.selections”| Property | Type | Required | Description |
|---|---|---|---|
resource |
localId | yes | |
role |
focused, selected, open, pinned |
||
detail |
object | Application-defined detail, e.g. a cell range or line span. |
No other properties are allowed.
An unsaved or unsubmitted change in an application.
| Property | Type | Required | Description |
|---|---|---|---|
id |
localId | yes | |
description |
text | yes | |
target |
localId | Resource the draft would change. | |
state |
unsaved, saved, submitted |
yes | |
content |
string, ≤ 16384 chars | Small inline draft content. | |
content_ref |
localId | Resource holding the draft content. |
No other properties are allowed.
operation
Section titled “operation”| Property | Type | Required | Description |
|---|---|---|---|
id |
localId | yes | |
kind |
approval, input, action, wait |
yes | approval: needs a person’s approval. input: needs information from a person. action: a side-effecting call to an external system. wait: depends on an external event or system. |
description |
text | yes | |
status |
planned, awaiting, uncertain, failed, approved, rejected, completed, cancelled |
yes | planned: not started. awaiting: requested and waiting. uncertain: started, outcome unknown. failed: attempted and failed. approved/rejected: an approval’s recorded outcome. completed: finished. cancelled: will not happen. |
target |
localId | Resource the operation acts on. | |
record |
localId | Resource in a system of record where the operation’s current status can be checked, such as an approval request or a payment record. | |
effect |
none, idempotent, non_idempotent, unknown |
What repeating the operation does. none: no side effect. idempotent: repeating has no further effect. non_idempotent: repeating may duplicate the effect. unknown: assume non_idempotent. | |
idempotency_key |
string | ||
call |
object (below) | The invocation an action stands for. A call to the same tool whose arguments include every recorded argument with an equal value repeats the operation. Describes; never instructs. Must not contain credentials. | |
requested_from |
string | Role or party whose approval or input is needed. | |
requested_at |
timestamp | ||
last_attempt_at |
timestamp | ||
expires_at |
timestamp | ||
depends_on |
localRefs | ||
approval |
object (below) | The recorded outcome of an approval. A record, not an authorization. | |
resume |
retry, verify_first, ask, do_not_resume |
What the source recommends on continuation. retry: repeat it. verify_first: check the target system for its outcome before anything else. ask: ask a person. do_not_resume: leave it. | |
extensions |
extensions |
No other properties are allowed.
operation.call
Section titled “operation.call”The invocation an action stands for. A call to the same tool whose arguments include every recorded argument with an equal value repeats the operation. Describes; never instructs. Must not contain credentials.
| Property | Type | Required | Description |
|---|---|---|---|
tool |
string | yes | The tool or API operation as the interface declares it; for MCP, the server’s tool name without a client prefix. |
arguments |
object | Arguments the call was or will be made with. Leave out sensitive arguments not needed to identify the call. |
No other properties are allowed.
operation.approval
Section titled “operation.approval”The recorded outcome of an approval. A record, not an authorization.
| Property | Type | Required | Description |
|---|---|---|---|
decided_by |
text | yes | |
decided_at |
timestamp | yes | |
scope |
string | What was approved, in the approver’s terms. | |
evidence |
array of localId | yes | Resources in a system of record where the approval can be verified. |
No other properties are allowed.
Rules
- Only an action stands for a call.
- An operation whose outcome is unknown and that may duplicate an effect must not be blindly retried.
- An uncertain operation with no declared effect is treated as unknown.
- Only approvals are approved or rejected, and a decided approval carries its record.
- An approval record belongs only to a decided approval.
requirement
Section titled “requirement”| Property | Type | Required | Description |
|---|---|---|---|
id |
localId | yes | |
kind |
tool, capability, access, extension |
yes | tool: a callable tool. capability: a general ability, e.g. code execution. access: access to a resource, which the destination must already hold. extension: a checkpoint extension the consumer must understand to interpret the document fully. |
name |
text | yes | For tool, the tool’s name as known to the source. For extension, the extension key. Otherwise a short name. |
description |
string | ||
necessity |
required, recommended, optional |
yes | required: continuation must not proceed without it. recommended: continuation can proceed degraded. optional: convenience. |
fallback |
string | How to continue without it. | |
refs |
localRefs |
No other properties are allowed.
continuation
Section titled “continuation”| Property | Type | Required | Description |
|---|---|---|---|
requirements |
array of requirement | ||
preconditions |
array of object (below) | Conditions to check before resuming. | |
stop_conditions |
array of object (below) | Conditions under which continuation must not proceed. | |
recovery |
array of object (below) | Recommended first actions on resuming, in order. | |
incompatibilities |
array of text | Known environments or conditions in which this checkpoint cannot be continued faithfully. | |
extensions |
extensions |
No other properties are allowed.
continuation.preconditions
Section titled “continuation.preconditions”| Property | Type | Required | Description |
|---|---|---|---|
id |
localId | yes | |
description |
text | yes | |
refs |
localRefs | ||
on_failure |
halt, ask, degrade |
yes |
No other properties are allowed.
continuation.stop_conditions
Section titled “continuation.stop_conditions”| Property | Type | Required | Description |
|---|---|---|---|
id |
localId | yes | |
description |
text | yes | |
refs |
localRefs | ||
applies_to |
localRefs | Operations this stop condition forbids. | |
until |
array of object (below) | What lifts this stop condition: it applies until every listed operation reaches its status in the system of record. Without it, the stop condition applies for the whole continuation. |
No other properties are allowed.
continuation.stop_conditions.until
Section titled “continuation.stop_conditions.until”| Property | Type | Required | Description |
|---|---|---|---|
operation |
localId | yes | |
status |
approved, rejected, completed, cancelled, failed |
yes |
No other properties are allowed.
continuation.recovery
Section titled “continuation.recovery”| Property | Type | Required | Description |
|---|---|---|---|
id |
localId | yes | |
description |
text | yes | |
refs |
localRefs |
No other properties are allowed.
derivation
Section titled “derivation”How this checkpoint was produced, and what was left out.
| Property | Type | Required | Description |
|---|---|---|---|
method |
captured, compacted, merged, converted, authored, forked |
yes | captured: written from a live session. compacted: reduced from earlier checkpoints or session history. merged: combined from several inputs. converted: translated from another format. authored: written by hand. forked: copied from the parent to be continued alongside possible sibling copies. |
inputs |
array of object (below) | Checkpoints or sessions this one was derived from. | |
omissions |
array of object (below) | Information deliberately left out. | |
transformations |
array of object (below) | Content that was condensed or rewritten, and which objects carry the result. |
No other properties are allowed.
derivation.inputs
Section titled “derivation.inputs”| Property | Type | Required | Description |
|---|---|---|---|
checkpoint |
string | ||
session |
sessionRef |
No other properties are allowed.
derivation.omissions
Section titled “derivation.omissions”| Property | Type | Required | Description |
|---|---|---|---|
description |
text | yes | |
reason |
size, irrelevant, superseded, sensitive, unavailable |
yes | |
recoverable_from |
localId | Resource or session from which the omitted information can be recovered. |
No other properties are allowed.
derivation.transformations
Section titled “derivation.transformations”| Property | Type | Required | Description |
|---|---|---|---|
description |
text | yes | |
affected |
localRefs |
No other properties are allowed.