docs: document defer task options (#1907)

Author: mjpieters

website/docs/changelog.mdx

@@ -5,6 +5,11 @@ sidebar_position: 14
 
 # Changelog
 
+## Unreleased
+
+- Document deferred tasks in the schema reference and fix an error in the JSON
+  schema for such tasks (#1907 by @mjpieters).
+
 ## v3.40.1 - 2024-12-06
 
 - Fixed a security issue in `git-urls` by switching to the maintained fork `chainguard-dev/git-urls` (#1917 by

website/docs/reference/schema.mdx

@@ -140,7 +140,7 @@ tasks:
 | `silent`       | `bool`                             | `false`       | Skips some output for this command. Note that STDOUT and STDERR of the commands will still be redirected.                                                                                          |
 | `vars`         | [`map[string]Variable`](#variable) |               | Optional additional variables to be passed to the referenced task. Only relevant when setting `task` instead of `cmd`.                                                                             |
 | `ignore_error` | `bool`                             | `false`       | Continue execution if errors happen while executing the command.                                                                                                                                   |
-| `defer`        | `string`                           |               | Alternative to `cmd`, but schedules the command to be executed at the end of this task instead of immediately. This cannot be used together with `cmd`.                                            |
+| `defer`        | [`Defer`](#defer)                  |               | Alternative to `cmd`, but schedules the command or a task to be executed at the end of this task instead of immediately. This cannot be used together with `cmd`.                                  |
 | `platforms`    | `[]string`                         | All platforms | Specifies which platforms the command should be run on. [Valid GOOS and GOARCH values allowed](https://github.com/golang/go/blob/master/src/internal/syslist/syslist.go). Command will be skipped otherwise. |
 | `set`          | `[]string`                         |               | Specify options for the [`set` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html).                                                                                  |
 | `shopt`        | `[]string`                         |               | Specify option for the [`shopt` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html).                                                                               |
@@ -180,6 +180,17 @@ tasks:
 
 :::
 
+### Defer
+
+The `defer` parameter defines a shell command to run, or a task to trigger, at the end of the current task instead of immediately.
+If defined as a string this is a shell command, otherwise it is a map defining a task to call:
+
+| Attribute | Type                               | Default | Description                                                       |
+| --------- | ---------------------------------- | ------- | ----------------------------------------------------------------- |
+| `task`    | `string`                           |         | The deferred task to trigger.                                     |
+| `vars`    | [`map[string]Variable`](#variable) |         | Optional additional variables to be passed to the deferred task.  |
+| `silent`  | `bool`                             | `false` | Hides task name and command from output. The command's output will still be redirected to `STDOUT` and `STDERR`. |
+
 ### For
 
 The `for` parameter can be defined as a string, a list of strings or a map. If

website/static/schema.json

@@ -360,14 +360,7 @@
               "type": "string"
             },
             {
-              "type": "object",
-              "properties": {
-                "task": {
-                  "description": "Name of the task to defer",
-                  "type": "string"
-                }
-              },
-              "additionalProperties": false
+              "$ref": "#/definitions/task_call"
             }
           ]
         }