{
  "$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)."
    }
  }
}
