TheSoftware LensSee engineering differently

SaaCIP 0.2: files for implementers

Not an article: the files that go with the SaaCIP 0.2 specification, for people building a capability or a hub. The schemas are the real, normative schemas of this version, the ones an implementation validates against, at their permanent addresses; the examples are illustrations of one made-up hire; the validator is a working tool. Version 0.2 is the current version, a draft for comment. Schemas, examples and the validator are licensed under the Apache License 2.0 (see LICENSE and NOTICE below). A reference implementation of both sides, a hub and a capability client, exists and will be linked from this page when its repository is public. If you came to read about the protocol, start with the core document or the examples.

Dated snapshots

A PDF of each document, for citing and for the record, not for reading: SaaCIP 0.2, the core and SaaCIP 0.2, the Resident SaaC profile and SaaCIP 0.2, the Hosted SaaC profile. The web pages are the living versions, a PDF is never edited after publication, and a later change gets a new dated PDF.

JSON Schemas (draft 2020-12)

Each schema's $id is its address here. Open a schema to read it in place; the raw file is linked inside.

ack-response.schema.json200 response to POST <base>/inbox/ack/: how many of each were marked delivered.
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/ack-response.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 HTTP binding: acknowledgement response",
  "description": "200 response to POST <base>/inbox/ack/: how many of each were marked delivered.",
  "type": "object",
  "required": [
    "approvals",
    "outcomes"
  ],
  "properties": {
    "approvals": {
      "type": "integer",
      "minimum": 0
    },
    "outcomes": {
      "type": "integer",
      "minimum": 0
    },
    "work_items": {
      "type": "integer",
      "minimum": 0,
      "description": "How many handed-off items were marked delivered. Added in 0.2."
    }
  }
}

Raw file: /saacip/0.2/schemas/ack-response.schema.json

ack.schema.jsonPOST <base>/inbox/ack/: what the capability has applied, so the hub stops sending it.
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/ack.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 HTTP binding: acknowledgement",
  "description": "POST <base>/inbox/ack/: what the capability has applied, so the hub stops sending it.",
  "type": "object",
  "properties": {
    "approvals": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The ids of approvals the capability applied."
    },
    "outcomes": {
      "type": "array",
      "items": {
        "$ref": "common.schema.json#/$defs/ref"
      },
      "description": "The refs of outcomes the capability applied."
    },
    "work_items": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The hub_refs of handed-off items the capability took up. Added in 0.2."
    }
  }
}

Raw file: /saacip/0.2/schemas/ack.schema.json

approval-request.schema.jsonPOST <base>/approvals/ (autonomy level 2 or above).
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/approval-request.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 HTTP binding: approval request",
  "description": "POST <base>/approvals/ (autonomy level 2 or above).",
  "type": "object",
  "required": [
    "action_id",
    "ref",
    "action"
  ],
  "properties": {
    "action_id": {
      "$ref": "common.schema.json#/$defs/ref"
    },
    "ref": {
      "$ref": "common.schema.json#/$defs/ref"
    },
    "action": {
      "type": "string",
      "minLength": 1,
      "description": "The id of a declared action."
    },
    "summary": {
      "type": "string",
      "maxLength": 500
    },
    "ext": {
      "$ref": "common.schema.json#/$defs/ext"
    }
  }
}

Raw file: /saacip/0.2/schemas/approval-request.schema.json

approval.schema.jsonA declared action waiting for, or given, a person's decision. Returned by POST <base>/approvals/ and listed in
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/approval.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 HTTP binding: approval",
  "description": "A declared action waiting for, or given, a person's decision. Returned by POST <base>/approvals/ and listed in the inbox once decided.",
  "type": "object",
  "required": [
    "id",
    "action_id",
    "ref",
    "action",
    "status"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "The hub's identifier for this approval; used to acknowledge it."
    },
    "action_id": {
      "$ref": "common.schema.json#/$defs/ref"
    },
    "ref": {
      "$ref": "common.schema.json#/$defs/ref"
    },
    "action": {
      "type": "string",
      "description": "The id of the declared action."
    },
    "summary": {
      "type": "string"
    },
    "status": {
      "enum": [
        "pending",
        "approved",
        "rejected"
      ]
    },
    "decided_by": {
      "type": [
        "string",
        "null"
      ],
      "description": "The person who decided, as the hub names them; null while pending."
    },
    "decided_at": {
      "oneOf": [
        {
          "$ref": "common.schema.json#/$defs/rfc3339"
        },
        {
          "type": "null"
        }
      ],
      "description": "When they decided; null while pending."
    }
  }
}

Raw file: /saacip/0.2/schemas/approval.schema.json

attestation.schema.jsonThe hub's signed record of a statement it accepted and of the outcomes it recorded for the hire (section 7.7).
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/attestation.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 attestation",
  "description": "The hub's signed record of a statement it accepted and of the outcomes it recorded for the hire (section 7.7). Returned in the statement response. Added in 0.2.",
  "type": "object",
  "required": [
    "protocol",
    "agent_id",
    "statement_hash",
    "final",
    "recorded",
    "signed_at",
    "hub_public_key",
    "signature"
  ],
  "properties": {
    "protocol": {
      "$ref": "common.schema.json#/$defs/protocol"
    },
    "agent_id": {
      "type": "string",
      "description": "The hub's identifier for the capability in this hire."
    },
    "statement_hash": {
      "$ref": "common.schema.json#/$defs/sha256Hex",
      "description": "SHA-256 of the canonical JSON of the statement the hub accepted."
    },
    "final": {
      "type": "boolean"
    },
    "recorded": {
      "type": "object",
      "required": [
        "reported",
        "judged",
        "accepted",
        "rejected",
        "actions_approved",
        "actions_rejected"
      ],
      "properties": {
        "reported": {
          "type": "integer",
          "minimum": 0
        },
        "judged": {
          "type": "integer",
          "minimum": 0
        },
        "accepted": {
          "type": "integer",
          "minimum": 0
        },
        "rejected": {
          "type": "integer",
          "minimum": 0
        },
        "actions_approved": {
          "type": "integer",
          "minimum": 0
        },
        "actions_rejected": {
          "type": "integer",
          "minimum": 0
        }
      },
      "description": "The hub's own counts for the hire, from its record, not copied from the statement. Where they differ from the statement, the difference is a fact for a registry to record."
    },
    "signed_at": {
      "$ref": "common.schema.json#/$defs/epochSeconds"
    },
    "hub_public_key": {
      "$ref": "common.schema.json#/$defs/base64",
      "description": "The Ed25519 key this attestation verifies with; the one returned at enrolment."
    },
    "signature": {
      "$ref": "common.schema.json#/$defs/base64",
      "description": "Ed25519 over the canonical JSON of the attestation without signature."
    },
    "ext": {
      "$ref": "common.schema.json#/$defs/ext"
    }
  }
}

Raw file: /saacip/0.2/schemas/attestation.schema.json

capability-manifest.schema.jsonWhat a hirer can read about a capability before hiring it (section 7.1). Usually written as YAML by people and
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/capability-manifest.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 capability manifest",
  "description": "What a hirer can read about a capability before hiring it (section 7.1). Usually written as YAML by people and exchanged as JSON.",
  "type": "object",
  "required": [
    "protocol",
    "id",
    "version",
    "profiles",
    "hire_kinds",
    "autonomy",
    "declared_actions",
    "data"
  ],
  "properties": {
    "protocol": {
      "$ref": "common.schema.json#/$defs/protocol"
    },
    "id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9._-]{0,119}$",
      "description": "A stable identifier for the capability, chosen by its provider."
    },
    "name": {
      "type": "string"
    },
    "version": {
      "type": "string"
    },
    "provider": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "profiles": {
      "type": "array",
      "items": {
        "$ref": "common.schema.json#/$defs/profile"
      },
      "minItems": 1,
      "uniqueItems": true
    },
    "hire_kinds": {
      "type": "array",
      "items": {
        "$ref": "common.schema.json#/$defs/hireKind"
      },
      "minItems": 1,
      "uniqueItems": true
    },
    "autonomy": {
      "type": "object",
      "required": [
        "default",
        "max"
      ],
      "properties": {
        "default": {
          "$ref": "common.schema.json#/$defs/autonomyLevel"
        },
        "max": {
          "$ref": "common.schema.json#/$defs/autonomyLevel"
        }
      }
    },
    "work_items": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "description": "What the capability calls its work items, for example incident."
        }
      }
    },
    "declared_actions": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "reversible"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "reversible": {
            "type": "boolean"
          },
          "auto_allowed": {
            "type": "boolean"
          }
        }
      },
      "description": "A summary of the declared actions file (section 7.6): enough for a hirer to see what the capability could ever do."
    },
    "data": {
      "type": "object",
      "required": [
        "stays",
        "leaves_by_default"
      ],
      "properties": {
        "stays": {
          "type": "string"
        },
        "leaves_by_default": {
          "type": "string"
        }
      }
    },
    "connectors": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Resident profile: the connector kinds the capability can use."
    },
    "ext": {
      "$ref": "common.schema.json#/$defs/ext"
    },
    "crit": {
      "$ref": "common.schema.json#/$defs/crit"
    },
    "skills": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 200
      },
      "description": "Skills, tools and protocols the capability uses to do the job, for people. None of them is hired (section 2.2). Added in 0.2."
    },
    "handoff_roles": {
      "type": "array",
      "items": {
        "$ref": "common.schema.json#/$defs/roleName"
      },
      "uniqueItems": true,
      "description": "Roles it can hand work to, if the hirer defines them (section 6.5). Added in 0.2."
    }
  }
}

Raw file: /saacip/0.2/schemas/capability-manifest.schema.json

common.schema.jsonTypes shared by every SaaCIP document and message.
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/common.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 common definitions",
  "description": "Types shared by every SaaCIP document and message.",
  "$defs": {
    "protocol": {
      "type": "string",
      "pattern": "^saacip/[0-9]+\\.[0-9]+$",
      "description": "Protocol identifier, saacip/<major>.<minor>. This version is saacip/0.2; a document says which version it follows."
    },
    "profile": {
      "type": "string",
      "pattern": "^([a-z][a-z0-9-]*|[a-z0-9-]+(\\.[a-z0-9-]+)+(/[a-z0-9._-]+)?)$",
      "description": "A registered profile name (resident, hosted) or a private one named by reverse domain name."
    },
    "epochSeconds": {
      "type": "number",
      "minimum": 0,
      "description": "Seconds since 1970-01-01T00:00:00Z, with at most millisecond precision (three decimal places)."
    },
    "rfc3339": {
      "type": "string",
      "format": "date-time",
      "description": "A timestamp in RFC 3339 form, for example 2026-10-29T09:15:00Z."
    },
    "ref": {
      "type": "string",
      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$",
      "description": "A reference chosen by the capability, unique within the hire: 1 to 64 characters, starting with a letter or digit, then letters, digits, dot, underscore, colon or hyphen."
    },
    "hireKind": {
      "type": "string",
      "enum": [
        "task",
        "trial",
        "standing"
      ],
      "description": "The three kinds of hire (section 6)."
    },
    "hireStatus": {
      "type": "string",
      "enum": [
        "pending",
        "active",
        "released",
        "ended",
        "revoked"
      ],
      "description": "The states of a hire (section 5.1)."
    },
    "autonomyLevel": {
      "type": "integer",
      "minimum": 0,
      "maximum": 3,
      "description": "0 observe, 1 report, 2 act after approval, 3 act within declared limits (section 9)."
    },
    "outcomeValue": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_]{0,63}$",
      "description": "A person's judgement of a work item. The core values are accepted and rejected; a profile defines its own and says which core value each counts as (Resident: real counts as accepted, false_alarm as rejected). Section 7.4."
    },
    "receiptKind": {
      "type": "string",
      "pattern": "^([a-z][a-z0-9_]*|[a-z][a-z0-9_-]*/[a-z0-9_]+|[a-z0-9-]+(\\.[a-z0-9-]+)+(/[a-z0-9._-]+)?/[a-z0-9_]+)$",
      "description": "A core receipt kind (section 7.3), a profile kind written as <profile>/<kind> (section 10.6, for example hosted/data_received), or a private kind written as <extension id>/<kind>."
    },
    "recordKind": {
      "type": "string",
      "enum": [
        "log",
        "metric",
        "trace",
        "change"
      ],
      "description": "The kinds of record a Resident connector may read (Resident profile, section 4)."
    },
    "extensionId": {
      "type": "string",
      "pattern": "^[a-z0-9-]+(\\.[a-z0-9-]+)+(/[a-z0-9._-]+)?$",
      "description": "An extension identifier: a reverse domain name the author controls, optionally followed by a path, for example com.example.pricing."
    },
    "ext": {
      "type": "object",
      "propertyNames": {
        "$ref": "#/$defs/extensionId"
      },
      "description": "Extension data, keyed by extension identifier. A receiver ignores extensions it does not understand unless they are listed in crit."
    },
    "crit": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/extensionId"
      },
      "uniqueItems": true,
      "description": "Extensions the receiver must understand. A receiver that does not understand one of them must reject the document."
    },
    "base64": {
      "type": "string",
      "pattern": "^[A-Za-z0-9+/]+={0,2}$",
      "description": "Standard base64 with padding (RFC 4648 section 4)."
    },
    "sha256Hex": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$",
      "description": "A SHA-256 digest as 64 lowercase hexadecimal characters."
    },
    "coreOutcomeValue": {
      "type": "string",
      "enum": [
        "accepted",
        "rejected"
      ],
      "description": "The two core outcome values every profile maps onto (section 7.4)."
    },
    "roleName": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]{0,63}$",
      "description": "A role the hirer defined at its hub, for example incident-resolution (section 6.5)."
    },
    "credentialRef": {
      "type": "object",
      "required": [
        "label",
        "scope"
      ],
      "properties": {
        "label": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120,
          "description": "The name the hirer gave the credential; never its value."
        },
        "scope": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500,
          "description": "What it may reach, in words: the connector or action, and the permission."
        }
      },
      "description": "A credential the hirer issued, by label and scope (section 9.4)."
    },
    "origin": {
      "type": "object",
      "required": [
        "agent_id",
        "ref",
        "hub_ref"
      ],
      "properties": {
        "agent_id": {
          "type": "string",
          "description": "The hub's identifier for the hire that handed the item off."
        },
        "ref": {
          "$ref": "#/$defs/ref",
          "description": "The sender's ref for the item."
        },
        "hub_ref": {
          "type": "string",
          "description": "The hub's own reference for the item, the common anchor."
        },
        "role": {
          "$ref": "#/$defs/roleName"
        }
      },
      "description": "Where a handed-off work item came from (section 6.5)."
    },
    "handoff": {
      "type": "object",
      "required": [
        "role"
      ],
      "properties": {
        "role": {
          "$ref": "#/$defs/roleName"
        },
        "reason": {
          "type": "string",
          "maxLength": 2000
        }
      },
      "description": "Hand this work item to the hire that holds the role (section 6.5)."
    }
  }
}

Raw file: /saacip/0.2/schemas/common.schema.json

connector-manifest.schema.jsonWhat a connector reads, what it may do, where the data stays and how it signs in (Resident profile, section 4;
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/connector-manifest.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 Resident and Hosted profiles: connector manifest",
  "description": "What a connector reads, what it may do, where the data stays and how it signs in (Resident profile, section 4; Hosted profile, section 5).",
  "type": "object",
  "required": [
    "protocol",
    "id",
    "kind",
    "version",
    "signals",
    "scopes",
    "data_location",
    "auth"
  ],
  "properties": {
    "protocol": {
      "$ref": "common.schema.json#/$defs/protocol"
    },
    "id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "kind": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60
    },
    "version": {
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "signals": {
      "type": "array",
      "items": {
        "enum": [
          "logs",
          "metrics",
          "traces",
          "changes"
        ]
      },
      "uniqueItems": true
    },
    "scopes": {
      "type": "array",
      "items": {
        "enum": [
          "read",
          "act"
        ]
      },
      "uniqueItems": true,
      "contains": {
        "const": "read"
      }
    },
    "operations": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "uniqueItems": true,
      "description": "Required when scopes contains act: the only operations the connector can perform."
    },
    "data_location": {
      "type": "string"
    },
    "auth": {
      "type": "string"
    },
    "ext": {
      "$ref": "common.schema.json#/$defs/ext"
    },
    "crit": {
      "$ref": "common.schema.json#/$defs/crit"
    }
  },
  "if": {
    "properties": {
      "scopes": {
        "contains": {
          "const": "act"
        }
      }
    }
  },
  "then": {
    "required": [
      "operations"
    ],
    "properties": {
      "operations": {
        "minItems": 1
      }
    }
  }
}

Raw file: /saacip/0.2/schemas/connector-manifest.schema.json

declared-actions.schema.jsonThe only actions a capability may ever take, written and approved by a person before the hire (section 7.6). T
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/declared-actions.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 declared actions file",
  "description": "The only actions a capability may ever take, written and approved by a person before the hire (section 7.6). The core fields are below; the Resident profile adds match, services and command (Resident profile, section 5).",
  "type": "object",
  "required": [
    "actions"
  ],
  "properties": {
    "actions": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "reversible"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
          },
          "title": {
            "type": "string"
          },
          "reversible": {
            "type": "boolean",
            "description": "true only when the action can be undone or safely repeated. Irreversible actions always wait for approval."
          },
          "auto_allowed": {
            "type": "boolean",
            "default": false,
            "description": "May run without a fresh approval at autonomy level 3."
          },
          "max_per_day": {
            "type": "integer",
            "minimum": 0,
            "description": "The most times the action may run by itself in one UTC calendar day. Absent means no automatic runs."
          },
          "match": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Resident profile: substrings a finding must contain for this action to be considered."
          },
          "services": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Resident profile: the only services the action may target."
          },
          "command": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "minItems": 1,
            "description": "Resident profile: an argument list run without a shell. The only placeholder is {service}, filled from services."
          }
        }
      }
    },
    "ext": {
      "$ref": "common.schema.json#/$defs/ext"
    },
    "crit": {
      "$ref": "common.schema.json#/$defs/crit"
    }
  }
}

Raw file: /saacip/0.2/schemas/declared-actions.schema.json

enrol-request.schema.jsonPOST <base>/enrol/ (HTTP binding, Resident profile section 6, shared with the Hosted profile). Sent once, with
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/enrol-request.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 HTTP binding: enrol request",
  "description": "POST <base>/enrol/ (HTTP binding, Resident profile section 6, shared with the Hosted profile). Sent once, with the enrolment token the hirer issued.",
  "type": "object",
  "required": [
    "enrolment_token",
    "protocol_versions",
    "profile",
    "version",
    "terms"
  ],
  "properties": {
    "enrolment_token": {
      "type": "string",
      "minLength": 1
    },
    "protocol_versions": {
      "type": "array",
      "items": {
        "$ref": "common.schema.json#/$defs/protocol"
      },
      "minItems": 1,
      "description": "The versions the capability speaks, preferred first."
    },
    "profile": {
      "$ref": "common.schema.json#/$defs/profile"
    },
    "version": {
      "type": "string",
      "description": "The capability's own version."
    },
    "terms": {
      "$ref": "terms.schema.json"
    },
    "ext": {
      "$ref": "common.schema.json#/$defs/ext"
    }
  }
}

Raw file: /saacip/0.2/schemas/enrol-request.schema.json

enrol-response.schema.json201 response to POST <base>/enrol/.
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/enrol-response.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 HTTP binding: enrol response",
  "description": "201 response to POST <base>/enrol/.",
  "type": "object",
  "required": [
    "protocol",
    "profile",
    "agent_id",
    "agent_token",
    "settings"
  ],
  "properties": {
    "protocol": {
      "$ref": "common.schema.json#/$defs/protocol"
    },
    "profile": {
      "$ref": "common.schema.json#/$defs/profile"
    },
    "agent_id": {
      "type": "string",
      "description": "The hub's identifier for this capability instance in this hire."
    },
    "agent_token": {
      "type": "string",
      "minLength": 40,
      "description": "The credential for every later call, shown once. At least 256 bits of randomness (section 11)."
    },
    "settings": {
      "type": "object",
      "required": [
        "autonomy_level",
        "hire_kind"
      ],
      "properties": {
        "autonomy_level": {
          "$ref": "common.schema.json#/$defs/autonomyLevel"
        },
        "hire_kind": {
          "$ref": "common.schema.json#/$defs/hireKind"
        },
        "trial_days": {
          "type": [
            "integer",
            "null"
          ],
          "description": "The trial length the hub holds, for a trial hire."
        },
        "poll_seconds": {
          "type": "integer",
          "minimum": 1,
          "default": 60,
          "description": "How often the capability should collect its inbox."
        }
      },
      "description": "What the hub asks of the capability. autonomy_level never raises the capability above the ceiling in its terms."
    },
    "hub_public_key": {
      "$ref": "common.schema.json#/$defs/base64",
      "description": "The hub's Ed25519 public key, with which its attestations verify (section 7.7). Added in 0.2."
    }
  }
}

Raw file: /saacip/0.2/schemas/enrol-response.schema.json

heartbeat-response.schema.json200 response to POST <base>/heartbeat/.
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/heartbeat-response.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 HTTP binding: heartbeat response",
  "description": "200 response to POST <base>/heartbeat/.",
  "type": "object",
  "required": [
    "settings",
    "release_requested"
  ],
  "properties": {
    "settings": {
      "type": "object",
      "required": [
        "autonomy_level",
        "hire_kind"
      ],
      "properties": {
        "autonomy_level": {
          "$ref": "common.schema.json#/$defs/autonomyLevel"
        },
        "hire_kind": {
          "$ref": "common.schema.json#/$defs/hireKind"
        },
        "trial_days": {
          "type": [
            "integer",
            "null"
          ],
          "description": "The trial length the hub holds, for a trial hire."
        },
        "poll_seconds": {
          "type": "integer",
          "minimum": 1,
          "default": 60,
          "description": "How often the capability should collect its inbox."
        }
      },
      "description": "What the hub asks of the capability. autonomy_level never raises the capability above the ceiling in its terms."
    },
    "release_requested": {
      "type": "boolean"
    }
  }
}

Raw file: /saacip/0.2/schemas/heartbeat-response.schema.json

heartbeat.schema.jsonPOST <base>/heartbeat/.
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/heartbeat.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 HTTP binding: heartbeat request",
  "description": "POST <base>/heartbeat/.",
  "type": "object",
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "enum": [
        "ok",
        "degraded"
      ],
      "description": "ok when every connector is healthy; degraded when any is not."
    },
    "connectors": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "ok"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "ok": {
            "type": "boolean"
          },
          "detail": {
            "type": "string",
            "description": "A short human-readable note on the connector's health."
          }
        }
      }
    },
    "counters": {
      "type": "object",
      "description": "The current track record, in the shape of statement.track_record."
    },
    "receipt_head": {
      "$ref": "common.schema.json#/$defs/sha256Hex"
    },
    "hire": {
      "type": [
        "object",
        "null"
      ],
      "description": "The capability's view of its hire.",
      "properties": {
        "id": {
          "type": "string",
          "description": "The capability's own identifier for the hire (hire_id)."
        },
        "kind": {
          "$ref": "common.schema.json#/$defs/hireKind"
        },
        "status": {
          "$ref": "common.schema.json#/$defs/hireStatus"
        },
        "expires": {
          "type": [
            "number",
            "null"
          ],
          "description": "When a trial or task ends, as a time (section 4.5); null for a standing hire."
        }
      }
    },
    "ext": {
      "$ref": "common.schema.json#/$defs/ext"
    }
  }
}

Raw file: /saacip/0.2/schemas/heartbeat.schema.json

inbox.schema.json200 response to GET <base>/inbox/: decisions and judgements not yet acknowledged, and whether the hirer asked
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/inbox.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 HTTP binding: inbox",
  "description": "200 response to GET <base>/inbox/: decisions and judgements not yet acknowledged, and whether the hirer asked for release.",
  "type": "object",
  "required": [
    "approvals",
    "outcomes",
    "release_requested"
  ],
  "properties": {
    "approvals": {
      "type": "array",
      "items": {
        "allOf": [
          {
            "$ref": "approval.schema.json"
          },
          {
            "properties": {
              "status": {
                "enum": [
                  "approved",
                  "rejected"
                ]
              }
            }
          }
        ]
      }
    },
    "outcomes": {
      "type": "array",
      "items": {
        "$ref": "outcome.schema.json"
      }
    },
    "release_requested": {
      "type": "boolean"
    },
    "work_items": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "hub_ref",
          "subject",
          "description_html",
          "origin",
          "role"
        ],
        "properties": {
          "hub_ref": {
            "type": "string"
          },
          "subject": {
            "type": "string"
          },
          "description_html": {
            "type": "string"
          },
          "priority_level": {
            "type": "integer",
            "minimum": 1,
            "maximum": 4
          },
          "origin": {
            "$ref": "common.schema.json#/$defs/origin"
          },
          "role": {
            "$ref": "common.schema.json#/$defs/roleName"
          }
        }
      },
      "description": "Work items handed to a role this hire holds, not yet acknowledged (section 6.5). Untrusted input. Added in 0.2."
    }
  }
}

Raw file: /saacip/0.2/schemas/inbox.schema.json

outcome.schema.jsonA person's judgement of one work item, delivered back to the capability (section 7.4).
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/outcome.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 outcome",
  "description": "A person's judgement of one work item, delivered back to the capability (section 7.4).",
  "type": "object",
  "required": [
    "ref",
    "outcome"
  ],
  "properties": {
    "ref": {
      "$ref": "common.schema.json#/$defs/ref"
    },
    "outcome": {
      "$ref": "common.schema.json#/$defs/outcomeValue"
    },
    "action_worked": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Whether the action taken for this item worked, when a person said so."
    },
    "note": {
      "type": "string"
    },
    "hub_ref": {
      "type": "string",
      "description": "The hub's own reference for the item, for example a ticket number."
    },
    "hub_status": {
      "type": "string",
      "description": "The hub's status for the item when the judgement was read."
    },
    "ext": {
      "$ref": "common.schema.json#/$defs/ext"
    }
  }
}

Raw file: /saacip/0.2/schemas/outcome.schema.json

problem.schema.jsonEvery error, as RFC 9457 problem details (section 8.7). The type is a URI under https://thesoftwarelens.com/sa
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/problem.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 problem details",
  "description": "Every error, as RFC 9457 problem details (section 8.7). The type is a URI under https://thesoftwarelens.com/saacip/0.1/errors/.",
  "type": "object",
  "required": [
    "type",
    "title",
    "status",
    "detail"
  ],
  "properties": {
    "type": {
      "type": "string",
      "format": "uri"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer",
      "minimum": 400,
      "maximum": 599
    },
    "detail": {
      "type": "string"
    },
    "errors": {
      "type": "object",
      "description": "invalid-request: the members that were wrong, and why."
    },
    "supported": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "unsupported-version and unsupported-profile: the versions or profiles the hub accepts."
    },
    "extensions": {
      "type": "array",
      "items": {
        "$ref": "common.schema.json#/$defs/extensionId"
      },
      "description": "critical-extension: the extensions the receiver did not understand."
    }
  }
}

Raw file: /saacip/0.2/schemas/problem.schema.json

receipt.schema.jsonOne signed, chained record of a step the capability took (section 7.3). Stored one per line as canonical JSON
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/receipt.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 receipt",
  "description": "One signed, chained record of a step the capability took (section 7.3). Stored one per line as canonical JSON (JSON Lines).",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "ts",
    "kind",
    "purpose",
    "body",
    "prev",
    "public_key",
    "signature"
  ],
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "ts": {
      "$ref": "common.schema.json#/$defs/epochSeconds"
    },
    "kind": {
      "$ref": "common.schema.json#/$defs/receiptKind"
    },
    "purpose": {
      "type": "object",
      "description": "Why the step was taken: the hire, the work item or the action it belongs to."
    },
    "body": {
      "type": "object",
      "description": "What was done."
    },
    "prev": {
      "$ref": "common.schema.json#/$defs/sha256Hex"
    },
    "public_key": {
      "$ref": "common.schema.json#/$defs/base64"
    },
    "signature": {
      "$ref": "common.schema.json#/$defs/base64"
    }
  }
}

Raw file: /saacip/0.2/schemas/receipt.schema.json

record.schema.jsonOne record read from a source (Resident profile, section 4).
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/record.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 Resident profile: record",
  "description": "One record read from a source (Resident profile, section 4).",
  "type": "object",
  "required": [
    "ts",
    "source",
    "service",
    "kind",
    "level",
    "body",
    "attributes"
  ],
  "properties": {
    "ts": {
      "$ref": "common.schema.json#/$defs/epochSeconds"
    },
    "source": {
      "type": "string"
    },
    "service": {
      "type": "string"
    },
    "kind": {
      "$ref": "common.schema.json#/$defs/recordKind"
    },
    "level": {
      "type": "string"
    },
    "body": {
      "type": "string"
    },
    "attributes": {
      "type": "object"
    }
  }
}

Raw file: /saacip/0.2/schemas/record.schema.json

report-response.schema.json201 (created) or 200 (updated or unchanged) response to PUT <base>/work-items/<ref>/.
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/report-response.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 HTTP binding: report response",
  "description": "201 (created) or 200 (updated or unchanged) response to PUT <base>/work-items/<ref>/.",
  "type": "object",
  "required": [
    "hub_ref",
    "status",
    "created"
  ],
  "properties": {
    "hub_ref": {
      "type": "string",
      "description": "The hub's own reference for the work item, for example a ticket number."
    },
    "status": {
      "type": "string",
      "description": "The hub's current status for the item, in the hub's own words."
    },
    "created": {
      "type": "boolean",
      "description": "true when this call created the item."
    },
    "updated": {
      "type": "boolean",
      "description": "true when this call added a note to the item."
    },
    "reopened": {
      "type": "boolean",
      "description": "true when the note reopened a closed item and cleared its outcome."
    },
    "handed_off": {
      "type": "boolean",
      "description": "True when the hub accepted a hand-off in this report. Added in 0.2."
    }
  }
}

Raw file: /saacip/0.2/schemas/report-response.schema.json

report.schema.jsonPUT <base>/work-items/<ref>/ (HTTP binding, Resident profile section 6, shared with the Hosted profile). The f
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/report.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 HTTP binding: report request",
  "description": "PUT <base>/work-items/<ref>/ (HTTP binding, Resident profile section 6, shared with the Hosted profile). The first call for a ref creates the work item; later calls with the same ref add a note. Repeating a call has no further effect.",
  "type": "object",
  "anyOf": [
    {
      "required": [
        "subject",
        "description_html"
      ]
    },
    {
      "required": [
        "note"
      ]
    },
    {
      "required": [
        "handoff"
      ]
    }
  ],
  "properties": {
    "subject": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "description_html": {
      "type": "string",
      "maxLength": 20000
    },
    "priority_level": {
      "type": "integer",
      "minimum": 1,
      "maximum": 4,
      "description": "How urgent the capability thinks the item is: 1 is the most urgent."
    },
    "note": {
      "type": "string",
      "maxLength": 5000,
      "description": "An update to an open item: what changed since the last report."
    },
    "ext": {
      "$ref": "common.schema.json#/$defs/ext"
    },
    "handoff": {
      "$ref": "common.schema.json#/$defs/handoff",
      "description": "Hand this item to a role in the capability's terms (section 6.5). Added in 0.2."
    },
    "origin": {
      "$ref": "common.schema.json#/$defs/origin",
      "description": "This new item was taken up from a hand-off (section 6.5). Added in 0.2."
    }
  }
}

Raw file: /saacip/0.2/schemas/report.schema.json

statement-request.schema.jsonPOST <base>/statement/. With final true the hire ends; the same final statement may be sent again and changes
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/statement-request.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 HTTP binding: statement request",
  "description": "POST <base>/statement/. With final true the hire ends; the same final statement may be sent again and changes nothing.",
  "type": "object",
  "required": [
    "statement"
  ],
  "properties": {
    "statement": {
      "$ref": "statement.schema.json"
    },
    "final": {
      "type": "boolean",
      "default": false
    }
  }
}

Raw file: /saacip/0.2/schemas/statement-request.schema.json

statement-response.schema.json200 response to POST <base>/statement/.
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/statement-response.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 HTTP binding: statement response",
  "description": "200 response to POST <base>/statement/.",
  "type": "object",
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "$ref": "common.schema.json#/$defs/hireStatus"
    },
    "attestation": {
      "$ref": "attestation.schema.json",
      "description": "Present with every accepted final statement from a 0.2 hub (section 7.7)."
    }
  }
}

Raw file: /saacip/0.2/schemas/statement-response.schema.json

statement.schema.jsonThe capability's account of a hire, built from its own receipts (section 7.5).
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/statement.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 statement",
  "description": "The capability's account of a hire, built from its own receipts (section 7.5).",
  "type": "object",
  "required": [
    "hire_id",
    "kind",
    "track_record"
  ],
  "properties": {
    "hire_id": {
      "type": "string"
    },
    "kind": {
      "$ref": "common.schema.json#/$defs/hireKind"
    },
    "reason": {
      "type": "string",
      "description": "Why the hire ended, when it has."
    },
    "track_record": {
      "type": "object",
      "required": [
        "findings",
        "reported",
        "judged",
        "real",
        "false_alarms",
        "share_real",
        "actions"
      ],
      "properties": {
        "findings": {
          "type": "integer",
          "minimum": 0
        },
        "reported": {
          "type": "integer",
          "minimum": 0
        },
        "judged": {
          "type": "integer",
          "minimum": 0
        },
        "real": {
          "type": "integer",
          "minimum": 0,
          "description": "Outcomes that count as accepted (under the Resident profile, real). Required in 0.2 for 0.1 readers; replaced by accepted in 1.0."
        },
        "false_alarms": {
          "type": "integer",
          "minimum": 0,
          "description": "Outcomes that count as rejected (under the Resident profile, false_alarm). Required in 0.2 for 0.1 readers; replaced by rejected in 1.0."
        },
        "share_real": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0,
          "maximum": 1,
          "description": "real divided by judged; null until something has been judged."
        },
        "actions": {
          "type": "object",
          "additionalProperties": {
            "type": "integer",
            "minimum": 0
          },
          "description": "Counts of declared actions by result: done, dry_run, failed, rejected, refused, and awaiting for those not yet decided."
        },
        "accepted": {
          "type": "integer",
          "minimum": 0,
          "description": "Outcomes that count as the core value accepted (section 7.4). Added in 0.2; required from 1.0."
        },
        "rejected": {
          "type": "integer",
          "minimum": 0,
          "description": "Outcomes that count as the core value rejected (section 7.4). Added in 0.2; required from 1.0."
        },
        "handed_off": {
          "type": "integer",
          "minimum": 0,
          "description": "Work items handed to another hire through the hub (section 6.5). Added in 0.2."
        },
        "received": {
          "type": "integer",
          "minimum": 0,
          "description": "Work items taken up from a hand-off (section 6.5). Added in 0.2."
        }
      }
    },
    "ext": {
      "$ref": "common.schema.json#/$defs/ext"
    }
  }
}

Raw file: /saacip/0.2/schemas/statement.schema.json

terms.schema.jsonThe scope the hirer agrees to for one hire (section 7.2). The terms are the authoritative statement of the hir
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://thesoftwarelens.com/saacip/0.2/schemas/terms.schema.json",
  "$comment": "SaaCIP 0.2 (https://thesoftwarelens.com/saacip/). Licensed under the Apache License 2.0.",
  "title": "SaaCIP 0.2 terms of the hire",
  "description": "The scope the hirer agrees to for one hire (section 7.2). The terms are the authoritative statement of the hire's kind and limits.",
  "type": "object",
  "required": [
    "protocol",
    "profile",
    "kind",
    "term",
    "autonomy_ceiling",
    "dry_run",
    "data_leaving",
    "model",
    "public_key",
    "environment"
  ],
  "properties": {
    "protocol": {
      "$ref": "common.schema.json#/$defs/protocol"
    },
    "profile": {
      "$ref": "common.schema.json#/$defs/profile"
    },
    "kind": {
      "$ref": "common.schema.json#/$defs/hireKind"
    },
    "term": {
      "description": "null for a standing hire; {days} for a trial; {window_seconds} for a task.",
      "oneOf": [
        {
          "type": "null"
        },
        {
          "type": "object",
          "required": [
            "days"
          ],
          "properties": {
            "days": {
              "type": "integer",
              "minimum": 1
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": [
            "window_seconds"
          ],
          "properties": {
            "window_seconds": {
              "type": "integer",
              "minimum": 1
            }
          },
          "additionalProperties": false
        }
      ]
    },
    "autonomy_ceiling": {
      "$ref": "common.schema.json#/$defs/autonomyLevel"
    },
    "dry_run": {
      "type": "boolean"
    },
    "connectors": {
      "type": "array",
      "items": {
        "$ref": "connector-manifest.schema.json"
      },
      "description": "Resident profile: the connectors the capability found, one manifest each. Required under the resident and hosted profiles."
    },
    "data_leaving": {
      "type": "string",
      "description": "In plain words, what leaves the hirer's environment and where it goes."
    },
    "model": {
      "type": "string",
      "description": "The model the capability uses, or offline."
    },
    "public_key": {
      "$ref": "common.schema.json#/$defs/base64"
    },
    "environment": {
      "type": "string"
    },
    "ext": {
      "$ref": "common.schema.json#/$defs/ext"
    },
    "crit": {
      "$ref": "common.schema.json#/$defs/crit"
    },
    "handoff_roles": {
      "type": "array",
      "items": {
        "$ref": "common.schema.json#/$defs/roleName"
      },
      "uniqueItems": true,
      "description": "Roles this hire may hand work to (section 6.5). Absent or empty: none. Added in 0.2."
    },
    "credentials": {
      "type": "array",
      "items": {
        "$ref": "common.schema.json#/$defs/credentialRef"
      },
      "description": "The credentials the hirer issued to this capability, by label and scope, never by value (section 9.4). Added in 0.2."
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "kind": {
            "const": "standing"
          }
        }
      },
      "then": {
        "properties": {
          "term": {
            "type": "null"
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "kind": {
            "const": "trial"
          }
        }
      },
      "then": {
        "properties": {
          "term": {
            "type": "object",
            "required": [
              "days"
            ]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "kind": {
            "const": "task"
          }
        }
      },
      "then": {
        "properties": {
          "term": {
            "type": "object",
            "required": [
              "window_seconds"
            ]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "profile": {
            "const": "resident"
          }
        }
      },
      "then": {
        "required": [
          "connectors"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "profile": {
            "const": "hosted"
          }
        }
      },
      "then": {
        "required": [
          "connectors",
          "credentials"
        ]
      }
    }
  ]
}

Raw file: /saacip/0.2/schemas/terms.schema.json

Examples

One per schema (except common, which only holds shared definitions), plus three extra examples for the hand-off and the Hosted profile. They tell one story: a made-up capability on a 14-day trial. The receipts are really signed and chain correctly. Read them step by step, in the order they happen. Every example is one JSON object except receipt.example.jsonl, which is JSON Lines: the whole receipt chain, one signed receipt per line, as receipts are stored.

ack-response.example.json
{
  "approvals": 1,
  "outcomes": 1
}

Raw file: /saacip/0.2/examples/ack-response.example.json

ack.example.json
{
  "approvals": [
    "7"
  ],
  "outcomes": [
    "wi-5516e077e5"
  ]
}

Raw file: /saacip/0.2/examples/ack.example.json

approval-request.example.json
{
  "action_id": "act-3f9a1c2b7d",
  "ref": "wi-5516e077e5",
  "action": "restart-api",
  "summary": "Rolling restart of the api service"
}

Raw file: /saacip/0.2/examples/approval-request.example.json

approval.example.json
{
  "id": "7",
  "action_id": "act-3f9a1c2b7d",
  "ref": "wi-5516e077e5",
  "action": "restart-api",
  "summary": "Rolling restart of the api service",
  "status": "approved",
  "decided_by": "on-call engineer",
  "decided_at": "2026-10-29T09:41:07Z"
}

Raw file: /saacip/0.2/examples/approval.example.json

attestation.example.json
{
  "protocol": "saacip/0.2",
  "agent_id": "5b1b273c-847f-4ecc-8dc7-0c2f5246cecd",
  "statement_hash": "98b92218f26c5fac65c32cd7c4d71cb0319104444ab44bb8594f30b925876af1",
  "final": true,
  "recorded": {
    "reported": 1,
    "judged": 1,
    "accepted": 1,
    "rejected": 0,
    "actions_approved": 1,
    "actions_rejected": 0
  },
  "signed_at": 1794474001,
  "hub_public_key": "zRv1fpF0arN+NqLb3fff4Xyy7Elpgpcr81K7AWraU2o=",
  "signature": "p8Fh/UV2jcbFqAyEJAQ0MKxj8WvjaKIEuSm2C9hGSbbuq0obiovuwpt3Yoi/VFBYrydBkjkDXLu1s+aQlGcLBQ=="
}

Raw file: /saacip/0.2/examples/attestation.example.json

capability-manifest.example.yaml
# A capability manifest, as its provider writes it (YAML). Converted to JSON before it is
# published or sent. 0.2 adds skills (what it uses; none of them is hired) and handoff_roles.
protocol: saacip/0.2
id: example-log-watch
name: Example Log Watch
version: 1.0.0
provider: Example Provider
description: 'Watches logs inside the hirer''s environment, reports what is unusual
  to the hirer''s help desk and acts only through actions a person declared in advance.

  '
profiles:
- resident
hire_kinds:
- task
- trial
- standing
autonomy:
  default: 1
  max: 3
work_items:
  kind: incident
declared_actions:
- id: restart-api
  title: Rolling restart of the api service
  reversible: true
  auto_allowed: true
- id: clear-tmp
  title: Clear temporary files on the worker volume
  reversible: false
  auto_allowed: false
data:
  stays: 'in the hirer''s environment: logs, baselines, receipts, signing key'
  leaves_by_default: nothing; redacted work item summaries to the hirer's help desk
    when one is set
connectors:
- file
- cloud-logs
- mcp
ext:
  com.example.support:
    hours: business
    timezone: Europe/Dublin
skills:
- log pattern detection (rules, no model)
- kubectl (declared actions only)
handoff_roles:
- incident-resolution

Raw file: /saacip/0.2/examples/capability-manifest.example.yaml

connector-manifest.example.json
{
  "protocol": "saacip/0.2",
  "id": "api-logs",
  "kind": "file",
  "version": "1.0.0",
  "signals": [
    "logs"
  ],
  "scopes": [
    "read"
  ],
  "data_location": "a log file on a volume mounted into the capability; read in place",
  "auth": "file system permission (read-only mount)"
}

Raw file: /saacip/0.2/examples/connector-manifest.example.json

declared-actions.example.yaml
# The only things the capability can ever do. A person writes and approves this file
# before the hire. Commands are argument lists (no shell). {service} is only ever
# filled with a name from "services". Unchanged from 0.1.
actions:
- id: restart-api
  title: Rolling restart of the api service
  match:
  - connection pool exhausted
  - OutOfMemory
  services:
  - api
  command:
  - kubectl
  - rollout
  - restart
  - deployment/{service}
  - -n
  - prod
  reversible: true
  auto_allowed: true
  max_per_day: 2
- id: clear-tmp
  title: Clear temporary files on the worker volume
  match:
  - No space left on device
  services:
  - worker
  command:
  - kubectl
  - exec
  - deployment/{service}
  - -n
  - prod
  - --
  - find
  - /tmp/work
  - -mtime
  - '+1'
  - -delete
  reversible: false
  auto_allowed: false

Raw file: /saacip/0.2/examples/declared-actions.example.yaml

enrol-request.example.json
{
  "enrolment_token": "enrol_8yQm...shown-once-by-the-hub",
  "protocol_versions": [
    "saacip/0.2",
    "saacip/0.1"
  ],
  "profile": "resident",
  "version": "1.0.0",
  "terms": {
    "protocol": "saacip/0.2",
    "profile": "resident",
    "kind": "trial",
    "term": {
      "days": 14
    },
    "autonomy_ceiling": 2,
    "dry_run": false,
    "connectors": [
      {
        "protocol": "saacip/0.2",
        "id": "api-logs",
        "kind": "file",
        "version": "1.0.0",
        "signals": [
          "logs"
        ],
        "scopes": [
          "read"
        ],
        "data_location": "a log file on a volume mounted into the capability; read in place",
        "auth": "file system permission (read-only mount)"
      }
    ],
    "data_leaving": "work item summaries (redacted) to the hirer's help desk; nothing else",
    "model": "offline",
    "public_key": "3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=",
    "environment": "prod-eu",
    "handoff_roles": [
      "incident-resolution"
    ],
    "credentials": [
      {
        "label": "logs-reader",
        "scope": "connector api-logs, read"
      },
      {
        "label": "cluster-operator",
        "scope": "declared actions restart-api and clear-tmp"
      }
    ]
  }
}

Raw file: /saacip/0.2/examples/enrol-request.example.json

enrol-response.example.json
{
  "protocol": "saacip/0.2",
  "profile": "resident",
  "agent_id": "5b1b273c-847f-4ecc-8dc7-0c2f5246cecd",
  "agent_token": "agent_Qe4c7v1Zr0VJ2bq9tN6yXw3kHf8sLp5uYa1dC0mGiE",
  "settings": {
    "autonomy_level": 2,
    "hire_kind": "trial",
    "trial_days": 14,
    "poll_seconds": 60
  },
  "hub_public_key": "zRv1fpF0arN+NqLb3fff4Xyy7Elpgpcr81K7AWraU2o="
}

Raw file: /saacip/0.2/examples/enrol-response.example.json

heartbeat-response.example.json
{
  "settings": {
    "autonomy_level": 2,
    "hire_kind": "trial",
    "trial_days": 14,
    "poll_seconds": 60
  },
  "release_requested": false
}

Raw file: /saacip/0.2/examples/heartbeat-response.example.json

heartbeat.example.json
{
  "status": "ok",
  "connectors": [
    {
      "id": "api-logs",
      "kind": "file",
      "ok": true,
      "detail": "read 1,204 lines in the last minute"
    }
  ],
  "counters": {
    "findings": 1,
    "reported": 1,
    "judged": 0,
    "real": 0,
    "false_alarms": 0,
    "share_real": null,
    "actions": {
      "awaiting": 1
    },
    "accepted": 0,
    "rejected": 0,
    "handed_off": 0,
    "received": 0
  },
  "receipt_head": "a70128cdb979f8a38f79d078a701f24cff9dc0bdeed565ac82daaabafbe21f33",
  "hire": {
    "id": "hire-74804b49c3",
    "kind": "trial",
    "status": "active",
    "expires": 1794474000.0
  }
}

Raw file: /saacip/0.2/examples/heartbeat.example.json

inbox.example.json
{
  "approvals": [
    {
      "id": "7",
      "action_id": "act-3f9a1c2b7d",
      "ref": "wi-5516e077e5",
      "action": "restart-api",
      "summary": "Rolling restart of the api service",
      "status": "approved",
      "decided_by": "on-call engineer",
      "decided_at": "2026-10-29T09:41:07Z"
    }
  ],
  "outcomes": [
    {
      "ref": "wi-5516e077e5",
      "outcome": "real",
      "action_worked": true,
      "note": "pool too small after the 2.4.1 deploy",
      "hub_ref": "TKT-2026-0042",
      "hub_status": "resolved"
    }
  ],
  "release_requested": false
}

Raw file: /saacip/0.2/examples/inbox.example.json

inbox.handoff.example.json
{
  "approvals": [],
  "outcomes": [],
  "release_requested": false,
  "work_items": [
    {
      "hub_ref": "TKT-2026-0042",
      "subject": "[prod-eu] A new error pattern in api",
      "description_html": "<p>A new error pattern in api, seen 22 times in one minute.</p>",
      "priority_level": 3,
      "role": "incident-resolution",
      "origin": {
        "agent_id": "5b1b273c-847f-4ecc-8dc7-0c2f5246cecd",
        "ref": "wi-5516e077e5",
        "hub_ref": "TKT-2026-0042",
        "role": "incident-resolution"
      }
    }
  ]
}

Raw file: /saacip/0.2/examples/inbox.handoff.example.json

outcome.example.json
{
  "ref": "wi-5516e077e5",
  "outcome": "real",
  "action_worked": true,
  "note": "pool too small after the 2.4.1 deploy",
  "hub_ref": "TKT-2026-0042",
  "hub_status": "resolved"
}

Raw file: /saacip/0.2/examples/outcome.example.json

problem.example.json
{
  "type": "https://thesoftwarelens.com/saacip/0.1/errors/#unsupported-version",
  "title": "Unsupported version",
  "status": 400,
  "detail": "None of the offered protocol versions is supported.",
  "supported": [
    "saacip/0.2",
    "saacip/0.1"
  ]
}

Raw file: /saacip/0.2/examples/problem.example.json

receipt.example.jsonl
{"body":{"expires":1794474000,"hire_id":"hire-74804b49c3","terms":{"autonomy_ceiling":2,"connectors":[{"auth":"file system permission (read-only mount)","data_location":"a log file on a volume mounted into the capability; read in place","id":"api-logs","kind":"file","protocol":"saacip/0.2","scopes":["read"],"signals":["logs"],"version":"1.0.0"}],"credentials":[{"label":"logs-reader","scope":"connector api-logs, read"},{"label":"cluster-operator","scope":"declared actions restart-api and clear-tmp"}],"data_leaving":"work item summaries (redacted) to the hirer's help desk; nothing else","dry_run":false,"environment":"prod-eu","handoff_roles":["incident-resolution"],"kind":"trial","model":"offline","profile":"resident","protocol":"saacip/0.2","public_key":"3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=","term":{"days":14}}},"id":"rcpt-49f23486900f","kind":"hire_started","prev":"0000000000000000000000000000000000000000000000000000000000000000","public_key":"3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=","purpose":{"autonomy_level":2,"environment":"prod-eu","kind":"trial","why":"hire"},"signature":"HEPpezT1zvbbE5lJo6plh7efdaSprNSwEkp97gttDwT41PmbdZAWhAOrSoRm89HURbRqUQiOqNyaNS84+K0ACw==","ts":1793264400}
{"body":{"agent_id":"5b1b273c-847f-4ecc-8dc7-0c2f5246cecd","hub":"https://acme.hub.example.com/saacip/","hub_public_key":"zRv1fpF0arN+NqLb3fff4Xyy7Elpgpcr81K7AWraU2o=","protocol":"saacip/0.2"},"id":"rcpt-505f36f31b33","kind":"enrolled","prev":"c2701d53582930c600993122c8c581337b1df3d6dcb5ce2b9eb53e379e34461b","public_key":"3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=","purpose":{"why":"hire"},"signature":"letIdkpgO7O/+3v9llHTlin5s0FC6O5Dw4ebbRRinT8xRx9WA86rqfwZgntMt1GdxDCNOiHu1b3dDT6MTr7WAQ==","ts":1793264401}
{"body":{"created":true,"decision":"await_approval","evidence":[{"count":22,"kind":"new_error","level":"ERROR","template":"database connection pool exhausted after <NUM><UNIT> (active=<NUM>, request_id=<HEX>)"}],"explanation":{"by":"offline","confidence":"medium","headline":"A new error pattern in api","likely_cause":"started shortly after the deploy of 2.4.1"},"hub_ref":"TKT-2026-0042","service":"api"},"id":"rcpt-fbe0ab16ddff","kind":"work_item_reported","prev":"8cad7f62fce7a3a8820e83bc71d08fcc29290b8236295bc2a67bd98f3f855c06","public_key":"3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=","purpose":{"autonomy_level":2,"ref":"wi-5516e077e5","why":"monitoring"},"signature":"vV1M/rSd+NqryC+YVGyH3CPba7WBKJMXOHW3BhaBmeWeGyqVADJf915OxN1KWJEzFTAvMNXicwhXiEd89rqvBg==","ts":1793265301}
{"body":{"action":"restart-api","action_id":"act-3f9a1c2b7d","reversible":true},"id":"rcpt-e07cb4d8bd85","kind":"approval_requested","prev":"a144fe1884de3eecd9569930ce169aebb1dc7ed993c63515f12d1a28a10eb662","public_key":"3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=","purpose":{"ref":"wi-5516e077e5","why":"remediation"},"signature":"rCiGL3bw93r75KDZAT94b7GZTDftTuIQLcodaXdCKSHUaY5zIhqVYv+J0qd3Ol11CpnhMfrE+81/eDjLTSexCg==","ts":1793265302}
{"body":{"action":"restart-api","action_id":"act-3f9a1c2b7d","argv":["kubectl","rollout","restart","deployment/api","-n","prod"],"dry_run":false,"returncode":0,"stdout_sha256":"8c9d5ac0eb2ac4c9bbbb6b813ffb32e764b1d0db9a397ed32a0207970957c558"},"id":"rcpt-64c55d295ef2","kind":"action_taken","prev":"a70128cdb979f8a38f79d078a701f24cff9dc0bdeed565ac82daaabafbe21f33","public_key":"3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=","purpose":{"approved_by":"on-call engineer","credential":"cluster-operator","ref":"wi-5516e077e5","why":"remediation"},"signature":"ch9Ny5LkizYtOG4oPkS8ZYAX0VPBhFvkbOJwYUk3+DcAheN1tN5EcM4noT2yMRA72N4tbVTWJENE+919BCTYCA==","ts":1793266870}
{"body":{"action_worked":true,"outcome":"real","weight_after":1.1,"weight_before":1},"id":"rcpt-21bedbe059f9","kind":"feedback_applied","prev":"a088e93ce8f133301f8a85294e9f2bc9cbf43c5f9a58eaf2ea76e81a2f07c4b8","public_key":"3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=","purpose":{"ref":"wi-5516e077e5","why":"learning"},"signature":"M9ZATr1JrZGSHOTQkT/+TDa8fPLwIf88pPf+awksmKLzJ+8f5tbxdNAeZzgrXmd++i0R3ImXkioQDIdxvZZJBg==","ts":1793269860}
{"body":{"hire_id":"hire-74804b49c3","statement":{"hire_id":"hire-74804b49c3","kind":"trial","reason":"trial term ended","track_record":{"accepted":1,"actions":{"awaiting":0,"done":1,"dry_run":0,"failed":0,"refused":0,"rejected":0},"false_alarms":0,"findings":1,"handed_off":0,"judged":1,"real":1,"received":0,"rejected":0,"reported":1,"share_real":1}}},"id":"rcpt-d381990ce7de","kind":"hire_ended","prev":"2a2af591892b1cc65e0ced53c754b083064d74f99e64911dbf504369c8cd979d","public_key":"3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=","purpose":{"reason":"trial term ended","why":"hire"},"signature":"m5vqkuF+iAtwDnMVCqzNvndcEwv5ByZwS76MAACBT0e+kbFg3IYcJim/zwUVMlWtEQuSLgfD9aXZnQaUh7EKCQ==","ts":1794474000}
{"body":{"attestation":{"agent_id":"5b1b273c-847f-4ecc-8dc7-0c2f5246cecd","final":true,"hub_public_key":"zRv1fpF0arN+NqLb3fff4Xyy7Elpgpcr81K7AWraU2o=","protocol":"saacip/0.2","recorded":{"accepted":1,"actions_approved":1,"actions_rejected":0,"judged":1,"rejected":0,"reported":1},"signature":"p8Fh/UV2jcbFqAyEJAQ0MKxj8WvjaKIEuSm2C9hGSbbuq0obiovuwpt3Yoi/VFBYrydBkjkDXLu1s+aQlGcLBQ==","signed_at":1794474001,"statement_hash":"98b92218f26c5fac65c32cd7c4d71cb0319104444ab44bb8594f30b925876af1"},"verified":true},"id":"rcpt-7c1e0a9d2b44","kind":"attestation_received","prev":"b19823897ed21696d1bcd4bfebbc583a3718d2b985e5a37ec8cc8242357ac837","public_key":"3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=","purpose":{"reason":"the hub attested the final statement","why":"hire"},"signature":"u7txmChwR9aE6XFNrnCR7gOcKabrNgy5/9gX/DrmDZEA7h0LYzxI5C/ugiA2ycv2Vhvt1n9/SY0zlUawbD7SBg==","ts":1794474002}

Raw file: /saacip/0.2/examples/receipt.example.jsonl

record.example.json
{
  "ts": 1793265292.0,
  "source": "api-logs",
  "service": "api",
  "kind": "log",
  "level": "ERROR",
  "body": "database connection pool exhausted after 30s (active=50, request_id=9f3c1a)",
  "attributes": {
    "pod": "api-7d9f6b5c4-x2k8q",
    "version": "2.4.1"
  }
}

Raw file: /saacip/0.2/examples/record.example.json

report-response.example.json
{
  "hub_ref": "TKT-2026-0042",
  "status": "open",
  "created": true
}

Raw file: /saacip/0.2/examples/report-response.example.json

report.example.json
{
  "subject": "[prod-eu] A new error pattern in api",
  "description_html": "<p>A new error pattern in api, seen 22 times in one minute.</p><p><b>Likely cause:</b> started shortly after the deploy of 2.4.1.</p>",
  "priority_level": 3
}

Raw file: /saacip/0.2/examples/report.example.json

report.handoff.example.json
{
  "subject": "[prod-eu] A new error pattern in api",
  "description_html": "<p>A new error pattern in api, seen 22 times in one minute.</p><p>This hire is at autonomy level 1; handed to the incident-resolution role.</p>",
  "priority_level": 3,
  "handoff": {
    "role": "incident-resolution",
    "reason": "needs an action this hire may not take"
  }
}

Raw file: /saacip/0.2/examples/report.handoff.example.json

report.received.example.json
{
  "subject": "[prod-eu] A new error pattern in api (taken up)",
  "description_html": "<p>Taken up from the log watcher. Candidate declared action: restart-api.</p>",
  "priority_level": 3,
  "origin": {
    "agent_id": "5b1b273c-847f-4ecc-8dc7-0c2f5246cecd",
    "ref": "wi-5516e077e5",
    "hub_ref": "TKT-2026-0042",
    "role": "incident-resolution"
  }
}

Raw file: /saacip/0.2/examples/report.received.example.json

statement-request.example.json
{
  "statement": {
    "hire_id": "hire-74804b49c3",
    "kind": "trial",
    "reason": "trial term ended",
    "track_record": {
      "findings": 1,
      "reported": 1,
      "judged": 1,
      "real": 1,
      "false_alarms": 0,
      "share_real": 1.0,
      "actions": {
        "done": 1,
        "dry_run": 0,
        "failed": 0,
        "rejected": 0,
        "refused": 0,
        "awaiting": 0
      },
      "accepted": 1,
      "rejected": 0,
      "handed_off": 0,
      "received": 0
    }
  },
  "final": true
}

Raw file: /saacip/0.2/examples/statement-request.example.json

statement-response.example.json
{
  "status": "ended",
  "attestation": {
    "protocol": "saacip/0.2",
    "agent_id": "5b1b273c-847f-4ecc-8dc7-0c2f5246cecd",
    "statement_hash": "98b92218f26c5fac65c32cd7c4d71cb0319104444ab44bb8594f30b925876af1",
    "final": true,
    "recorded": {
      "reported": 1,
      "judged": 1,
      "accepted": 1,
      "rejected": 0,
      "actions_approved": 1,
      "actions_rejected": 0
    },
    "signed_at": 1794474001,
    "hub_public_key": "zRv1fpF0arN+NqLb3fff4Xyy7Elpgpcr81K7AWraU2o=",
    "signature": "p8Fh/UV2jcbFqAyEJAQ0MKxj8WvjaKIEuSm2C9hGSbbuq0obiovuwpt3Yoi/VFBYrydBkjkDXLu1s+aQlGcLBQ=="
  }
}

Raw file: /saacip/0.2/examples/statement-response.example.json

statement.example.json
{
  "hire_id": "hire-74804b49c3",
  "kind": "trial",
  "reason": "trial term ended",
  "track_record": {
    "findings": 1,
    "reported": 1,
    "judged": 1,
    "real": 1,
    "false_alarms": 0,
    "share_real": 1.0,
    "actions": {
      "done": 1,
      "dry_run": 0,
      "failed": 0,
      "rejected": 0,
      "refused": 0,
      "awaiting": 0
    },
    "accepted": 1,
    "rejected": 0,
    "handed_off": 0,
    "received": 0
  }
}

Raw file: /saacip/0.2/examples/statement.example.json

terms.example.json
{
  "protocol": "saacip/0.2",
  "profile": "resident",
  "kind": "trial",
  "term": {
    "days": 14
  },
  "autonomy_ceiling": 2,
  "dry_run": false,
  "connectors": [
    {
      "protocol": "saacip/0.2",
      "id": "api-logs",
      "kind": "file",
      "version": "1.0.0",
      "signals": [
        "logs"
      ],
      "scopes": [
        "read"
      ],
      "data_location": "a log file on a volume mounted into the capability; read in place",
      "auth": "file system permission (read-only mount)"
    }
  ],
  "data_leaving": "work item summaries (redacted) to the hirer's help desk; nothing else",
  "model": "offline",
  "public_key": "3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=",
  "environment": "prod-eu",
  "handoff_roles": [
    "incident-resolution"
  ],
  "credentials": [
    {
      "label": "logs-reader",
      "scope": "connector api-logs, read"
    },
    {
      "label": "cluster-operator",
      "scope": "declared actions restart-api and clear-tmp"
    }
  ]
}

Raw file: /saacip/0.2/examples/terms.example.json

terms.hosted.example.json
{
  "protocol": "saacip/0.2",
  "profile": "hosted",
  "kind": "trial",
  "term": {
    "days": 14
  },
  "autonomy_ceiling": 2,
  "dry_run": true,
  "connectors": [
    {
      "protocol": "saacip/0.2",
      "id": "time-entries",
      "kind": "export",
      "version": "1.0.0",
      "signals": [
        "changes"
      ],
      "scopes": [
        "read"
      ],
      "data_location": "the hirer's time-logging system; a nightly export is fetched to the provider's environment and deleted after 7 days",
      "auth": "timesheets-export (hirer-issued, renewed daily)"
    }
  ],
  "data_leaving": "the week's time entries (names, dates, hours, project codes) to the provider's environment in the EU; nothing to any model or other recipient",
  "model": "offline",
  "public_key": "3RsIo8MiE66DyZ36VRYsLZsEYkt8g4Q5yYToIvLfkNc=",
  "environment": "provider-eu",
  "credentials": [
    {
      "label": "timesheets-export",
      "scope": "connector time-entries, read, renewed daily"
    },
    {
      "label": "reminder-sender",
      "scope": "declared action send-reminder, hirer mail relay"
    }
  ]
}

Raw file: /saacip/0.2/examples/terms.hosted.example.json

Validator

python validate.py <schema name> <file> lists every way a document fails its schema, and exits 0 when it is valid. It needs the jsonschema and referencing packages, and pyyaml for YAML files. Keep it next to the schemas folder; the reference implementation carries the same schemas and a validator of its own.

validate.pythe script, about 100 lines, Apache 2.0
"""Check a SaaCIP 0.2 document or message against its JSON Schema.

    python validate.py <schema name> <file>

    python validate.py terms my-terms.json
    python validate.py capability-manifest saacip-manifest.yaml
    python validate.py receipt receipts.jsonl          (every line is checked)

<schema name> is the file name without ".schema.json": terms, receipt, statement,
capability-manifest, declared-actions, enrol-request, and so on. Run with no
arguments to see the full list.

The file may be JSON, YAML (for the two documents people write: the capability
manifest and the declared actions file; it is converted to JSON first, as the
specification requires) or JSON Lines (one document per line).

Exit code 0: valid. 1: problems found, listed one per line. 2: wrong usage.

Needs the "jsonschema" and "referencing" packages (pip install jsonschema referencing),
and "pyyaml" for YAML files. Keep this file next to the "schemas" folder.

SaaCIP 0.2, https://thesoftwarelens.com/saacip/ . Licensed under the Apache License 2.0.
"""

import json
import os
import sys

HERE = os.path.dirname(os.path.abspath(__file__))
SCHEMAS = os.path.join(HERE, "schemas")
BASE = "https://thesoftwarelens.com/saacip/0.2/schemas/"


def schema_names():
    """The schema names this folder holds, for example ["ack", "approval", ...]."""
    return sorted(f[:-len(".schema.json")] for f in os.listdir(SCHEMAS) if f.endswith(".schema.json"))


_REGISTRY = None


def _registry():
    """All schemas, registered under their published $id so that $ref works offline."""
    global _REGISTRY
    if _REGISTRY is None:
        from referencing import Registry, Resource
        resources = []
        for name in schema_names():
            with open(os.path.join(SCHEMAS, name + ".schema.json"), encoding="utf-8") as fh:
                resources.append((BASE + name + ".schema.json", Resource.from_contents(json.load(fh))))
        _REGISTRY = Registry().with_resources(resources)
    return _REGISTRY


def errors(kind, data):
    """Every way `data` fails the schema `kind`, as messages; an empty list means valid."""
    from jsonschema import Draft202012Validator
    if kind not in schema_names():
        raise KeyError(kind)
    schema = _registry().get_or_retrieve(BASE + kind + ".schema.json").value.contents
    validator = Draft202012Validator(schema, registry=_registry())
    found = sorted(validator.iter_errors(data), key=lambda e: list(e.absolute_path))
    return [f"{'/'.join(str(p) for p in e.absolute_path) or '(root)'}: {e.message}" for e in found]


def load(path):
    """Read a JSON, YAML or JSON Lines file. JSON Lines gives a list, one item per line."""
    with open(path, encoding="utf-8") as fh:
        text = fh.read()
    if path.endswith((".yaml", ".yml")):
        import yaml
        return yaml.safe_load(text)
    if path.endswith(".jsonl"):
        return [json.loads(line) for line in text.splitlines() if line.strip()]
    return json.loads(text)


def main(argv):
    if len(argv) != 3:
        print(__doc__)
        print("Schemas in this folder:", ", ".join(schema_names()))
        return 2
    kind, path = argv[1], argv[2]
    if kind not in schema_names():
        print(f"No schema called {kind!r}. Choose one of: {', '.join(schema_names())}")
        return 2
    if not os.path.isfile(path):
        print(f"No such file: {path}")
        return 2
    try:
        import jsonschema, referencing  # noqa: F401
    except ImportError:
        print("This script needs the jsonschema and referencing packages: pip install jsonschema referencing")
        return 2
    try:
        data = load(path)
    except ImportError:
        print("Reading YAML needs the pyyaml package: pip install pyyaml")
        return 2
    except ValueError as exc:
        print(f"{path}: not valid JSON or YAML: {exc}")
        return 1
    items = data if isinstance(data, list) else [data]
    bad = 0
    for i, item in enumerate(items, 1):
        where = f"{path} line {i}" if len(items) > 1 else path
        for message in errors(kind, item):
            bad += 1
            print(f"{where}: {message}")
    print("valid" if not bad else f"{bad} problem(s)")
    return 0 if not bad else 1


if __name__ == "__main__":
    sys.exit(main(sys.argv))

Raw file: /saacip/0.2/validate.py

Errata

Erratum 1, 8 November 2026. common.schema.json: the pattern for a receipt kind accepted core kinds and dotted extension ids but not a profile prefix, so hosted/data_received and hosted/data_sent_on, which the core (sections 7.3 and 10.6) and the Hosted profile require, failed validation. The pattern now accepts <profile>/<kind>. No text changed; the PDFs are unaffected; the 0.1 schemas are untouched.

Erratum 2, 10 November 2026. Corrections to the web pages; no rule and no schema changed. Core: section 1.1 says hirer where it said customer; the note for readers who are not engineers points to sections 1, 3 and 5, and to 9.1 for the autonomy levels, as section 1.4 does; section 7.6 is printed before section 7.7; Appendix A names the Resident profile as a SaaCIP 0.2 document. Resident profile: the protocol member of a connector manifest reads saacip/0.2. Hosted profile: providers and hirers where it said vendors and customers; in the example of section 1 the capability fetches the export from the time-logging system, as its manifest declares. Core and Resident profile: the caption of the figure of the seven calls says that step 9 of the walkthrough, the hand-off, is a second hire. Registry examples: the worked hires were corrected. Invoice Review is shown on its 14-day trial with the hold simulated, and Backup Verify as a standing hire at level 3 that followed a trial; Backup Verify accepts trial as a hire kind; a missing model is no longer listed as a skill; the five figures of those hires (seq-*.svg, except seq-orchestration.svg) were redrawn to match. The PDFs are as published on 6 November 2026 and carry the earlier wording; the 0.1 text and files are untouched.

Erratum 3, 10 November 2026. In the core and in both profiles, every paragraph that began Example. now begins For example:, so that no reader takes a made-up example for a rule. The words of the examples are the same. No rule, schema or file changed; the PDFs carry the earlier wording; the 0.1 text and files are untouched.

Erratum 4, 10 November 2026. The documents said that a reference implementation was published with the schemas. It exists and it is not public yet. The core (the table at its head, its abstract and its change log) and the Resident profile (the table at its head) now say so, and this page will link to the code when it is public. No rule, schema or file changed; the PDFs carry the earlier wording; the 0.1 text and files are untouched.

Erratum 5, 19 November 2026. heartbeat.example.json: receipt_head is now the hash of line 4 of the example chain, as the walk-through says it is; the earlier value was left over from the 0.1 chain. The annotated receipt figure now shows the prev and the signature of the 0.2 chain. The wording about the examples and the reference implementation was made plainer: the examples are for readers to test in their own environment, and the reference implementation is not yet public. A listing page was added at /saacip/0.2/schemas/. No rule and no schema changed; the PDFs carry the earlier figure and wording.

Figures

The diagrams of the documents, as SVG files: annotated-receipt.svg · annotated-terms.svg · deployment-resident.svg · hire-overview.svg · hub-hire.png · hub-resolver.png · lifecycle-action.svg · lifecycle-hire.svg · lifecycle-work-item.svg · resident-architecture.svg · seq-backup-verify.svg · seq-cert-expiry.svg · seq-invoice-review.svg · seq-log-watch.svg · seq-orchestration.svg · seq-timesheet-check.svg · sequence.svg. Text licence, CC BY 4.0.

Problem types

The error identifiers are listed at /saacip/0.1/errors/; the 0.1 address is the permanent address of each type.

Licence

Apache License 2.0 for everything on this page except the figures; the specification text itself is under CC BY 4.0.

NOTICEwho holds the copyright, and the patent statement
SaaCIP 0.2: JSON Schemas, examples and validator
Copyright 2026 Imtiaz Hassan

Licensed under the Apache License, Version 2.0 (see LICENSE).

The SaaCIP specification text (published at https://thesoftwarelens.com/saacip/
and as SaaCIP-0.1-draft.pdf) is licensed under the Creative Commons
Attribution 4.0 International licence (CC BY 4.0):
https://creativecommons.org/licenses/by/4.0/

The author holds no patents on SaaCIP and has not applied for any.

Raw file: /saacip/0.2/NOTICE

LICENSEthe Apache License 2.0, full text

                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   APPENDIX: How to apply the Apache License to your work.

      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.

   Copyright [yyyy] [name of copyright owner]

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

Raw file: /saacip/0.2/LICENSE

Important notice. This page is part of my ongoing research into the Agentic Economy and reflects my thinking at the time of writing. It is shared in good faith, for information and discussion. It is not legal, regulatory, technical, financial or other professional advice, and it is not a verdict on how the EU AI Act or any other law applies to any organisation, system or situation. Laws, guidance, technology and my own research all move on, and others may reach different conclusions. The examples, designs, diagrams and technology choices show one possible approach. Before relying on, adapting or applying any part of it in your own situation, you must test and verify it, design it for your own architecture, and take independent expert advice, including from qualified lawyers and from your own IT, security and data protection specialists. Any decision to act on it, and its consequences, rest with you. To the fullest extent permitted by law, the author accepts no responsibility or liability for any loss, damage or consequence arising from any use of, or reliance on, this page, which is provided without any warranty of accuracy, completeness or fitness for a particular purpose. Reading it does not create a professional or advisory relationship with the author. The views expressed are the author’s own.