{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/knock-app/main/json-schema/knock-workflow-trigger-schema.json",
  "title": "Knock Workflow Trigger Request",
  "description": "Request body for triggering a Knock workflow via POST /v1/workflows/{key}/trigger. Recipients can be user ids, object references, or inline-identified users; the data block becomes available to templates and step conditions.",
  "type": "object",
  "required": ["recipients"],
  "properties": {
    "recipients": {
      "type": "array",
      "minItems": 1,
      "items": {
        "oneOf": [
          { "type": "string", "description": "User id." },
          {
            "type": "object",
            "description": "Object reference recipient.",
            "required": ["id", "collection"],
            "properties": {
              "id":         { "type": "string" },
              "collection": { "type": "string" }
            }
          },
          {
            "type": "object",
            "description": "Inline-identified user recipient.",
            "required": ["id"],
            "properties": {
              "id":            { "type": "string" },
              "email":         { "type": "string", "format": "email" },
              "phone_number":  { "type": "string" },
              "name":          { "type": "string" },
              "avatar":        { "type": "string", "format": "uri" },
              "timezone":      { "type": "string" }
            },
            "additionalProperties": true
          }
        ]
      }
    },
    "actor": {
      "description": "Optional sender — surfaces in templates as actor.* properties.",
      "oneOf": [
        { "type": "string" },
        { "type": "object" }
      ]
    },
    "tenant": {
      "type": ["string", "null"],
      "description": "Tenant id to scope branding and preferences for this run."
    },
    "data": {
      "type": "object",
      "description": "Free-form trigger data interpolated into templates and step conditions."
    },
    "cancellation_key": {
      "type": ["string", "null"],
      "description": "Optional key for later cancelling this run via POST /v1/workflows/{key}/cancel."
    }
  },
  "additionalProperties": false
}