$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://openawf.org/schemas/0.1.0/schema.yaml"
title: OpenAWF Workflow
description: >-
  Structural schema for an OpenAWF workflow document. Non-normative: the
  specification prose is the source of truth. Some constraints (a start task
  that exists, edges that resolve to defined tasks, at least one terminal node)
  cannot be expressed here and are enforced by a conformant validator.

type: object
required: [openawf, name, start, orchestration, tasks]
additionalProperties: false

properties:
  openawf:
    description: The OpenAWF version this document is written against.
    type: string
    const: "0.1.0"

  name:
    type: string
    minLength: 1

  summary:
    type: string

  model:
    description: The model every task runs on unless the task overrides it.
    type: string

  start:
    description: The name of the task the flow begins at.
    type: string
    minLength: 1

  orchestration:
    description: >-
      The task graph. Each key is a task name; its value is the node: the
      transition out of that task, plus optional per-node execution policy.
    type: object
    minProperties: 1
    additionalProperties:
      $ref: "#/$defs/transition"

  tasks:
    description: >-
      Task definitions keyed by name. Each entry is an inline task or a $ref to
      one.
    type: object
    minProperties: 1
    additionalProperties:
      $ref: "#/$defs/taskEntry"

  mcp:
    description: >-
      External MCP servers the workflow depends on, keyed by name. Declares the
      requirement; connection details (command, url, credentials) are resolved
      by the runner and are not part of the document.
    type: object
    additionalProperties:
      $ref: "#/$defs/mcpServer"

  version:
    description: The workflow's version (identity). A human version string.
    type: string
    minLength: 1

  sha:
    description: >-
      Content hash of the workflow, algorithm-prefixed (e.g. sha256-...). null
      until sealed. Recomputed to verify the content is unchanged.
    $ref: "#/$defs/sha"

  source:
    description: >-
      Where this workflow is fetched from (url, path, or registry id). Omitted
      when the workflow is authored in place rather than referenced.
    type: string
    minLength: 1


$defs:

  sha:
    description: A content hash, algorithm-prefixed, or null until sealed.
    type: [string, "null"]
    pattern: "^(sha256|sha384|sha512)-.+"

  transition:
    description: >-
      Where a task goes next. null ends the flow; an edge is an unconditional
      transition; an object mapping outcomes to edges is a branch. An edge is a
      task name, or an object naming the task with per-edge execution policy.
    oneOf:
      - type: "null"
      - $ref: "#/$defs/edge"
      - $ref: "#/$defs/branch"

  edge:
    description: >-
      A single transition to a task. A bare string names the task; the object
      form names it under `task` and adds per-edge execution policy.
    oneOf:
      - type: string
        minLength: 1
      - type: object
        required: [task]
        additionalProperties: false
        properties:
          task:
            description: The task this edge transitions to.
            type: string
            minLength: 1
          retries:
            description: >-
              Attempts after the first failure before the task fails hard. null
              (the default) retries indefinitely; 0 means a single attempt.
            type: [integer, "null"]
            minimum: 0
            default: null
          session:
            description: >-
              How the task behaves when reached through this edge. "fresh" starts
              a new context; "resume" keeps the prior session's context.
            type: string
            enum: [fresh, resume]
            default: fresh

  branch:
    description: >-
      A map from each emitted outcome to the edge it takes. "task" is reserved
      (it marks an edge object), so no outcome may be named task.
    type: object
    minProperties: 1
    propertyNames:
      not:
        const: task
    additionalProperties:
      $ref: "#/$defs/edge"

  taskEntry:
    oneOf:
      - $ref: "#/$defs/task"
      - $ref: "#/$defs/ref"

  ref:
    description: A reference to a task defined elsewhere (file path, URL, or id).
    type: object
    required: ["$ref"]
    additionalProperties: false
    properties:
      $ref:
        type: string
        minLength: 1

  task:
    description: An inline task definition.
    type: object
    required: [body]
    additionalProperties: false
    properties:
      version:
        description: The task's version (identity). A human version string.
        type: string
        minLength: 1
      sha:
        description: Content hash of the task, algorithm-prefixed. null until sealed.
        $ref: "#/$defs/sha"
      source:
        description: >-
          Where this task is fetched from (url, path, or registry id). Omitted
          when the task is authored in place.
        type: string
        minLength: 1
      summary:
        type: string
      input:
        description: JSON Schema the incoming data must satisfy. Absent when the task takes no input.
        type: object
      output:
        description: JSON Schema the task's output must satisfy. Absent when unconstrained.
        type: object
      model:
        description: Overrides the workflow model for this task.
        type: string
      outcomes:
        description: The outcomes this task may emit. Absent or empty when the task does not branch.
        type: array
        items:
          type: string
          minLength: 1
        uniqueItems: true
      uses:
        description: >-
          Names of MCP servers (declared in the top-level mcp block) this task
          requires.
        type: array
        items:
          type: string
          minLength: 1
        uniqueItems: true
      body:
        description: The tool-agnostic prompt.
        type: string
        minLength: 1

  mcpServer:
    description: A declared dependency on an external MCP server.
    type: object
    additionalProperties: false
    properties:
      transport:
        description: The MCP transport. A hint; connection details are resolved by the runner.
        type: string
        enum: [stdio, http, sse]
      tools:
        description: >-
          The tools this workflow uses from the server. "*" (the default when
          omitted) grants all of the server's tools.
        oneOf:
          - const: "*"
          - type: array
            items:
              type: string
              minLength: 1
            uniqueItems: true
        default: "*"