diff --git a/versions/development/SPEC.md b/versions/development/SPEC.md index 8315e11a..2ceb52c8 100644 --- a/versions/development/SPEC.md +++ b/versions/development/SPEC.md @@ -2600,11 +2600,31 @@ In this example, `i`, and `f` are inputs to this task even though `i` is not dir ## Computing Workflow Inputs -Workflows have inputs that must be satisfied to run them, just like tasks. Inputs to the workflow are provided as a key/value map where the key is of the form `workflow_name.input_name`. - -* If a workflow is to be used as a sub-workflow it must ensure that all of the inputs to its calls are satisfied. -* If a workflow will only ever be submitted as a top-level workflow, it may optionally leave its tasks' inputs unsatisfied. This then forces the engine to additionally supply those inputs at run time. In this case, the inputs' names must be qualified in the inputs as `workflow_name.task_name.input_name`. - +Workflows have inputs that must be satisfied to run them, just like tasks. +Inputs to the workflow are provided as a key/value map where the key is of the +form `workflow_name.input_name`. + +* A task usually has its inputs supplied when called by a workflow. + * Example: `call my_task { input: my_task_input=... }` +* A workflow is allowd not to specify all inputs in this block. In this case, + the inputs bubble up to become an input to the workflow instaead. + * Example: an unsupplied input might have the fully-qualified name + `my_workflow.my_task.my_task_input.` +* If that workflow is used as a subworkflow, the input is allowed to bubble up + again with a further-qualified name. + * Example: my_outer_workflow.my_workflow.my_task.my_task_input. +* There is currently no way to supply a bubbled-up input in an outer workflow's + call block. + * Example: one cannot say call my_workflow as subworkflow + `{ inputs: my_task.my_task_input=... }` +* All **required** inputs which bubble up like this must ultimately be provided + in the inputs set before the top-level workflow can be run. +* An engine must allow **optional** bubbled-up inputs to be filled in by end + users. These inputs are not required to be filled. +* Showing all optional inputs which are deeply nested in the workflow can lead + to a very large number of inputs. Therefore, it is up to the engine how many + layers of nesting it chooses to make visible in the UI. + Any declaration that appears outside the `input` section is considered an intermediate value and **not** a workflow input. Any declaration can always be moved inside the `input` block to make it overridable. Consider the following workflow: