Taskfile.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "title": "Taskfile YAML Schema",
  "description": "Schema for Taskfile files.",
  "definitions": {
    "env": {
      "$ref": "#/definitions/vars"
    },
    "platforms": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "tasks": {
      "type": "object",
      "patternProperties": {
        "^.*$": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "array",
              "items": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "$ref": "#/definitions/task_call"
                  },
                  {
                    "$ref": "#/definitions/defer_task_call"
                  },
                  {
                    "$ref": "#/definitions/defer_cmd_call"
                  }
                ]
              }
            },
            {
              "$ref": "#/definitions/task"
            }
          ]
        }
      }
    },
    "task": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "cmds": {
          "description": "A list of commands to be executed.",
          "$ref": "#/definitions/cmds"
        },
        "cmd": {
          "description": "The command to be executed.",
          "$ref": "#/definitions/cmd"
        },
        "deps": {
          "description": "A list of dependencies of this task. Tasks defined here will run in parallel before this task.",
          "$ref": "#/definitions/deps"
        },
        "label": {
          "description": "Overrides the name of the task in the output when a task is run. Supports variables.",
          "type": "string"
        },
        "desc": {
          "description": "A short description of the task. This is displayed when calling `task --list`.",
          "type": "string"
        },
        "prompt": {
          "description": "One or more prompts that will be presented before a task is run. Declining will cancel running the current and any subsequent tasks.",
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          ]
        },
        "summary": {
          "description": "A longer description of the task. This is displayed when calling `task --summary [task]`.",
          "type": "string"
        },
        "aliases": {
          "description": "A list of alternative names by which the task can be called.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "sources": {
          "description": "A list of sources to check before running this task. Relevant for `checksum` and `timestamp` methods. Can be file paths or star globs.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/glob"
          }
        },
        "generates": {
          "description": "A list of files meant to be generated by this task. Relevant for `timestamp` method. Can be file paths or star globs.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/glob"
          }
        },
        "status": {
          "description": "A list of commands to check if this task should run. The task is skipped otherwise. This overrides `method`, `sources` and `generates`.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "preconditions": {
          "description": "A list of commands to check if this task should run. If a condition is not met, the task will error.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/precondition"
          }
        },
        "dir": {
          "description": "The directory in which this task should run. Defaults to the current working directory.",
          "type": "string"
        },
        "set": {
          "description": "Enables POSIX shell options for all of a task's commands. See https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html",
          "type": "array",
          "items": {
            "$ref": "#/definitions/set"
          }
        },
        "shopt": {
          "description": "Enables Bash shell options for all of a task's commands. See https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html",
          "type": "array",
          "items": {
            "$ref": "#/definitions/shopt"
          }
        },
        "vars": {
          "description": "A set of variables that can be used in the task.",
          "$ref": "#/definitions/vars"
        },
        "env": {
          "description": "A set of environment variables that will be made available to shell commands.",
          "$ref": "#/definitions/env"
        },
        "dotenv": {
          "description": "A list of `.env` file paths to be parsed.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "silent": {
          "description": "Hides task name and command from output. The command's output will still be redirected to `STDOUT` and `STDERR`. When combined with the `--list` flag, task descriptions will be hidden.",
          "type": "boolean",
          "default": false
        },
        "interactive": {
          "description": "Tells task that the command is interactive.",
          "type": "boolean",
          "default": false
        },
        "internal": {
          "description": "Stops a task from being callable on the command line. It will also be omitted from the output when used with `--list`.",
          "type": "boolean",
          "default": false
        },
        "method": {
          "description": "Defines which method is used to check the task is up-to-date. `timestamp` will compare the timestamp of the sources and generates files. `checksum` will check the checksum (You probably want to ignore the .task folder in your .gitignore file). `none` skips any validation and always run the task.",
          "type": "string",
          "enum": ["none", "checksum", "timestamp"],
          "default": "none"
        },
        "prefix": {
          "description": "Defines a string to prefix the output of tasks running in parallel. Only used when the output mode is `prefixed`.",
          "type": "string"
        },
        "ignore_error": {
          "description": "Continue execution if errors happen while executing commands.",
          "type": "boolean"
        },
        "run": {
          "description": "Specifies whether the task should run again or not if called more than once. Available options: `always`, `once` and `when_changed`.",
          "$ref": "#/definitions/run"
        },
        "platforms": {
          "description": "Specifies which platforms the task should be run on.",
          "$ref": "#/definitions/platforms"
        },
        "requires": {
          "description": "A list of variables which should be set if this task is to run, if any of these variables are unset the task will error and not run",
          "$ref": "#/definitions/requires_obj"
        },
        "watch": {
          "description": "Configures a task to run in watch mode automatically.",
          "type": "boolean",
          "default": false
        }
      }
    },
    "cmds": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/cmd"
      }
    },
    "cmd": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "$ref": "#/definitions/cmd_call"
        },
        {
          "$ref": "#/definitions/task_call"
        },
        {
          "$ref": "#/definitions/parallel_call"
        },
        {
          "$ref": "#/definitions/defer_task_call"
        },
        {
          "$ref": "#/definitions/defer_cmd_call"
        },
        {
          "$ref": "#/definitions/for_cmds_call"
        }
      ]
    },
    "deps": {
      "type": "array",
      "items": {
        "oneOf": [
          {
            "type": "string"
          },
          {
            "$ref": "#/definitions/task_call"
          },
          {
            "$ref": "#/definitions/for_deps_call"
          }
        ]
      }
    },
    "set": {
      "type": "string",
      "enum": [
        "allexport",
        "a",
        "errexit",
        "e",
        "noexec",
        "n",
        "noglob",
        "f",
        "nounset",
        "u",
        "xtrace",
        "x",
        "pipefail"
      ]
    },
    "shopt": {
      "type": "string",
      "enum": ["expand_aliases", "globstar", "nullglob"]
    },
    "vars": {
      "type": "object",
      "patternProperties": {
        "^.*$": {
          "anyOf": [
            {
              "type": [
                "boolean",
                "integer",
                "null",
                "number",
                "string",
                "array"
              ]
            },
            {
              "$ref": "#/definitions/var_subkey"
            }
          ]
        }
      }
    },
    "var_subkey": {
      "type": "object",
      "properties": {
        "sh": {
          "type": "string",
          "description": "The value will be treated as a command and the output assigned to the variable"
        },
        "ref": {
          "type": "string",
          "description": "The value will be used to lookup the value of another variable which will then be assigned to this variable"
        },
        "map": {
          "type": "object",
          "description": "The value will be treated as a literal map type and stored in the variable"
        }
      },
      "additionalProperties": false
    },
    "task_call": {
      "type": "object",
      "properties": {
        "task": {
          "description": "Name of the task to run",
          "type": "string"
        },
        "vars": {
          "description": "Values passed to the task called",
          "$ref": "#/definitions/vars"
        },
        "silent": {
          "description": "Hides task name and command from output. The command's output will still be redirected to `STDOUT` and `STDERR`.",
          "type": "boolean"
        }
      },
      "additionalProperties": false,
      "required": ["task"]
    },
    "parallel_call": {
      "type": "object",
      "properties": {
        "parallel": {
          "$ref": "#/definitions/cmds"
        },
        "log": {
          "description": "Log output at the end",
          "type": "boolean"
        }
      },
      "additionalProperties": false,
      "required": ["parallel"]
    },
    "cmd_call": {
      "type": "object",
      "properties": {
        "cmd": {
          "description": "Command to run",
          "type": "string"
        },
        "silent": {
          "description": "Silent mode disables echoing of command before Task runs it",
          "type": "boolean"
        },
        "set": {
          "description": "Enables POSIX shell options for this command. See https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html",
          "type": "array",
          "items": {
            "$ref": "#/definitions/set"
          }
        },
        "shopt": {
          "description": "Enables Bash shell options for this command. See https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html",
          "type": "array",
          "items": {
            "$ref": "#/definitions/shopt"
          }
        },
        "ignore_error": {
          "description": "Prevent command from aborting the execution of task even after receiving a status code of 1",
          "type": "boolean"
        },
        "platforms": {
          "description": "Specifies which platforms the command should be run on.",
          "$ref": "#/definitions/platforms"
        }
      },
      "additionalProperties": false,
      "required": ["cmd"]
    },
    "defer_task_call": {
      "type": "object",
      "properties": {
        "defer": {
          "description": "Run a command when the task completes. This command will run even when the task fails",
          "anyOf": [
            {
              "$ref": "#/definitions/task_call"
            }
          ]
        }
      },
      "additionalProperties": false,
      "required": ["defer"]
    },
    "defer_cmd_call": {
      "type": "object",
      "properties": {
        "defer": {
          "description": "Name of the command to defer",
          "type": "string"
        },
        "silent": {
          "description": "Hides task name and command from output. The command's output will still be redirected to `STDOUT` and `STDERR`.",
          "type": "boolean"
        }
      },
      "additionalProperties": false,
      "required": ["defer"]
    },
    "for_cmds_call": {
      "type": "object",
      "properties": {
        "for": {
          "$ref": "#/definitions/for"
        },
        "cmd": {
          "description": "Command to run",
          "type": "string"
        },
        "silent": {
          "description": "Silent mode disables echoing of command before Task runs it",
          "type": "boolean"
        },
        "task": {
          "description": "Task to run",
          "type": "string"
        },
        "vars": {
          "description": "Values passed to the task called",
          "$ref": "#/definitions/vars"
        },
        "platforms": {
          "description": "Specifies which platforms the command should be run on.",
          "$ref": "#/definitions/platforms"
        }
      },
      "oneOf": [{ "required": ["cmd"] }, { "required": ["task"] }],
      "additionalProperties": false,
      "required": ["for"]
    },
    "for_deps_call": {
      "type": "object",
      "properties": {
        "for": {
          "$ref": "#/definitions/for"
        },
        "silent": {
          "description": "Silent mode disables echoing of command before Task runs it",
          "type": "boolean"
        },
        "task": {
          "description": "Task to run",
          "type": "string"
        },
        "vars": {
          "description": "Values passed to the task called",
          "$ref": "#/definitions/vars"
        }
      },
      "oneOf": [{ "required": ["cmd"] }, { "required": ["task"] }],
      "additionalProperties": false,
      "required": ["for"]
    },
    "for": {
      "anyOf": [
        {
          "$ref": "#/definitions/for_list"
        },
        {
          "$ref": "#/definitions/for_attribute"
        },
        {
          "$ref": "#/definitions/for_var"
        },
        {
          "$ref": "#/definitions/for_matrix"
        }
      ]
    },
    "for_list": {
      "description": "A list of values to iterate over",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "for_attribute": {
      "description": "The task attribute to iterate over",
      "type": "string",
      "enum": ["sources", "generates"]
    },
    "for_var": {
      "description": "Which variables to iterate over. The variable will be split using any whitespace character by default. This can be changed by using the `split` attribute.",
      "type": "object",
      "properties": {
        "var": {
          "description": "Name of the variable to iterate over",
          "type": "string"
        },
        "split": {
          "description": "String to split the variable on",
          "type": "string"
        },
        "as": {
          "description": "What the loop variable should be named",
          "default": "ITEM",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": ["var"]
    },
    "for_matrix": {
      "description": "A matrix of values to iterate over",
      "type": "object",
      "additionalProperties": true,
      "required": ["matrix"]
    },
    "precondition": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "$ref": "#/definitions/precondition_obj"
        }
      ]
    },
    "precondition_obj": {
      "type": "object",
      "properties": {
        "sh": {
          "description": "Command to run. If that command returns 1, the condition will fail",
          "type": "string"
        },
        "msg": {
          "description": "Failure message to display when the condition fails",
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "glob": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "$ref": "#/definitions/glob_obj"
        }
      ]
    },
    "glob_obj": {
      "type": "object",
      "properties": {
        "exclude": {
          "description": "File or glob pattern to exclude from the list",
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "run": {
      "type": "string",
      "enum": ["always", "once", "when_changed"]
    },
    "outputString": {
      "type": "string",
      "enum": ["interleaved", "prefixed", "group"],
      "default": "interleaved"
    },
    "outputObject": {
      "type": "object",
      "properties": {
        "group": {
          "type": "object",
          "properties": {
            "begin": {
              "type": "string"
            },
            "end": {
              "type": "string"
            },
            "error_only": {
              "description": "Swallows command output on zero exit code",
              "type": "boolean",
              "default": false
            }
          }
        }
      },
      "additionalProperties": false
    },
    "requires_obj": {
      "type": "object",
      "properties": {
        "vars": {
          "description": "List of variables that must be defined for the task to run",
          "type": "array",
          "items": {
            "oneOf": [
              { "type": "string" },
              {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "enum": { "type": "array", "items": { "type": "string" } }
                },
                "required": ["name", "enum"],
                "additionalProperties": false
              }
            ]
          }
        }
      },
      "additionalProperties": false
    }
  },
  "allOf": [
    {
      "type": "object",
      "properties": {
        "version": {
          "description": "Specify the Taskfile format that this file conforms to.",
          "oneOf": [
            {
              "type": "string",
              "pattern": "^(0|[1-9]\\d*)(?:\\.(0|[1-9]\\d*))?(?:\\.(0|[1-9]\\d*))?(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$"
            },
            {
              "type": "number",
              "enum": [3]
            }
          ]
        },
        "output": {
          "description": "Defines how the STDOUT and STDERR are printed when running tasks in parallel. The interleaved output prints lines in real time (default). The group output will print the entire output of a command once, after it finishes, so you won't have live feedback for commands that take a long time to run. The prefix output will prefix every line printed by a command with [task-name] as the prefix, but you can customize the prefix for a command with the prefix: attribute.",
          "anyOf": [
            { "$ref": "#/definitions/outputString" },
            { "$ref": "#/definitions/outputObject" }
          ]
        },
        "method": {
          "description": "Defines which method is used to check the task is up-to-date. (default: checksum)",
          "type": "string",
          "enum": ["none", "checksum", "timestamp"],
          "default": "checksum"
        },
        "includes": {
          "description": "Imports tasks from the specified taskfiles. The tasks described in the given Taskfiles will be available with the informed namespace.",
          "type": "object",
          "patternProperties": {
            "^.*$": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "object",
                  "properties": {
                    "taskfile": {
                      "description": "The path for the Taskfile or directory to be included. If a directory, Task will look for files named `Taskfile.yml` or `Taskfile.yaml` inside that directory. If a relative path, resolved relative to the directory containing the including Taskfile.",
                      "type": "string"
                    },
                    "dir": {
                      "description": "The working directory of the included tasks when run.",
                      "type": "string"
                    },
                    "optional": {
                      "description": "If `true`, no errors will be thrown if the specified file does not exist.",
                      "type": "boolean"
                    },
                    "flatten": {
                      "description": "If `true`, the tasks from the included Taskfile will be available in the including Taskfile without a namespace. If a task with the same name already exists in the including Taskfile, an error will be thrown.",
                      "type": "boolean"
                    },
                    "internal": {
                      "description": "Stops any task in the included Taskfile from being callable on the command line. These commands will also be omitted from the output when used with `--list`.",
                      "type": "boolean"
                    },
                    "aliases": {
                      "description": "Alternative names for the namespace of the included Taskfile.",
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "excludes": {
                      "description": "A list of tasks to be excluded from inclusion.",
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "vars": {
                      "description": "A set of variables to apply to the included Taskfile.",
                      "$ref": "#/definitions/vars"
                    },
                    "checksum": {
                      "description": "The checksum of the file you expect to include. If the checksum does not match, the file will not be included.",
                      "type": "string"
                    }
                  }
                }
              ]
            }
          }
        },
        "vars": {
          "description": "A set of global variables.",
          "$ref": "#/definitions/vars"
        },
        "env": {
          "description": "A set of global environment variables.",
          "$ref": "#/definitions/env"
        },
        "tasks": {
          "description": "A set of task definitions.",
          "$ref": "#/definitions/tasks"
        },
        "silent": {
          "description": "Default 'silent' options for this Taskfile. If `false`, can be overridden with `true` in a task by task basis.",
          "type": "boolean"
        },
        "set": {
          "description": "Enables POSIX shell options for all commands in the Taskfile. See https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html",
          "type": "array",
          "items": {
            "$ref": "#/definitions/set"
          }
        },
        "shopt": {
          "description": "Enables Bash shell options for all commands in the Taskfile. See https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html",
          "type": "array",
          "items": {
            "$ref": "#/definitions/shopt"
          }
        },
        "dotenv": {
          "type": "array",
          "description": "A list of `.env` file paths to be parsed.",
          "items": {
            "type": "string"
          }
        },
        "run": {
          "description": "Default 'run' option for this Taskfile. Available options: `always`, `once` and `when_changed`.",
          "$ref": "#/definitions/run"
        },
        "interval": {
          "description": "Sets a different watch interval when using `--watch`, the default being 100 milliseconds. This string should be a valid Go duration: https://pkg.go.dev/time#ParseDuration.",
          "type": "string",
          "pattern": "^[0-9]+(?:m|s|ms)$"
        }
      },
      "additionalProperties": false,
      "required": ["version"],
      "anyOf": [
        {
          "required": ["includes"]
        },
        {
          "required": ["tasks"]
        },
        {
          "required": ["includes", "tasks"]
        }
      ]
    }
  ]
}