# Template Schemas [Version: 2023-09] This document contains the formal specifications for the Open Job Description Template schemas. There are two schemas defined in this document: 1. The Job Template describes the shape of a Job, its runtime environment, and all the processes that will run as part of it. Jobs are created from Job Templates by providing a value for each of the Job Parameters defined in the Template, and instantiating the template with those values. 2. The Environment Template describes an Environment that is defined outside a Job. This can be used in render management systems to allow users to define Environments that are automatically applied to Job Templates that are submitted for rendering. Reading the broad overviews in [How Jobs Are Constructed](How-Jobs-Are-Constructed) and [How Jobs Are Run](How-Jobs-Are-Run) might provide an easier introduction and broader context prior to reading the schema in entirety. Both Templates are expressed as UTF-8 documents in either [ECMA-404 JavaScript Object Notation (JSON)](https://www.json.org/json-en.html) or [YAML Ain't Markup Language (YAML) 1.2](https://yaml.org/) interchange format. Notations used in this document to annotate aspects of the schema definition: * `@fmtstring` - The value of the annotated property is a Format String. See [Format Strings](#73-format-strings). * `@fmtstring[host]` - The value is evaluated at runtime on the worker host on which the job is running. The value is otherwise evaluated when the job template is submitted and the render manager is constructing a job. * `@optional` - The annotated property is optional. * `@extension EXTENSION_NAME` - The annotated property is available only when extension EXTENSION_NAME is requested in the `extensions` list of the template. Implementations can choose which extensions to support. * `@incompatible PROPERTY_NAME` - The annotated property cannot be used in combination with PROPERTY_NAME. ## 1. Root elements ### 1.1. Job Template ```yaml specificationVersion: "jobtemplate-2023-09" $schema: # @optional extensions: [ , ... ] # @optional name: # @fmtstring description: # @optional parameterDefinitions: [ , ... ] # @optional jobEnvironments: [ , ... ] # @optional steps: [, ...] ``` Where: 1. *specificationVersion* — A literal that identifies the document as adhering to this schema. 2. *$schema* — Ignored. This property is allowed for compatibility with JSON-editing IDEs. 3. *extensions* — If provided, is a non-empty list of extensions to the schema. Introduced in [RFC 0002](https://github.com/OpenJobDescription/openjd-specifications/blob/mainline/rfcs/0002-model-extensions.md). * Extensions available for specification version 2023-09: [TASK_CHUNKING](https://github.com/OpenJobDescription/openjd-specifications/blob/mainline/rfcs/0001-task-chunking.md), [REDACTED_ENV_VARS](https://github.com/OpenJobDescription/openjd-specifications/blob/mainline/rfcs/0003-redacted-env-vars.md), [FEATURE_BUNDLE_1](https://github.com/OpenJobDescription/openjd-specifications/blob/mainline/rfcs/0004-enhanced-limits-and-capabilities.md), [EXPR](https://github.com/OpenJobDescription/openjd-specifications/blob/mainline/rfcs/0005-expression-language.md), [WRAP_ACTIONS](https://github.com/OpenJobDescription/openjd-specifications/blob/mainline/rfcs/0008-environment-wrap-actions.md) 4. *name* — The name to give to a Job that is created from the template. See: [<JobName>](#111-jobname). 5. *description* — A description to apply to all Jobs that are created from the template. It has no functional purpose, but may appear in UI elements. See: [<Description>](#72-description). 6. *parameterDefinitions* — A list of the Job Parameters that are available within the Job Template. Values for Job Parameters are defined when submitting the Job Template to create a Job to a render management system. The values of Job Parameters can be referenced in Format Strings. See: [<JobParameterDefinition>](#2-jobparameterdefinition). * Minimum number of elements: If provided, then this list must contain at least one element. * Maximum number of elements: The list must not contain more than 50 elements or 200 elements with the `FEATURE_BUNDLE_1` extension. 7. *jobEnvironments* — An ordered list of the environments that are required to run Tasks in the Jobs created by this Job Template. These are entered in the order provided at the start of every Session for Tasks in the Job, and exited in the reverse order at the end of those Sessions. See: [<Environment>](#4-environment). Constraints: 1. No two Environments in this list may have the same value for the `name` property. 2. The Environments defined in this list must not have the same `name` as an Environment defined in any Step within the same Job Template. 8. *steps* — A list of the Steps in the Job. See: [<StepTemplate>](#3-steptemplate). #### 1.1.1. `` A [Format String](#73-format-strings) subject to the following constraints: 1. Allowed characters: Any unicode character except those in the Cc unicode character category. 2. Minimum length: 1 character. 3. Maximum length: 128 characters, after the format string has been resolved. 512 characters, after the format string has been resolved if using the `FEATURE_BUNDLE_1` extension. #### 1.1.2. `` A literal string matching the following character regex: `[A-Z_0-9]{3,128}`. ### 1.2. Environment Template ```yaml specificationVersion: environment-2023-09 parameterDefinitions: [ , ... ] # @optional environment: ``` 1. *specificationVersion* — A literal that identifies the document as adhering to this schema. 2. *parameterDefinitions* — A list of the Job Parameters that are available within the Environment Template. Values for Job Parameters are defined when submitting a Job Template to create a Job to a render management system. Both the Job Template and Environment Template(s) for a submission are allowed to contain definitions for the same job parameter name, but the submission must be rejected if any of the definitions of the same job parameter name have unresolvable conflicts (See: [Merging Environment Template Parameter Definitions](#121-merging-environment-template-parameter-definitions)). The values of Job Parameters can be referenced in Format Strings. See: [<JobParameterDefinition>](#2-jobparameterdefinition). * Minimum number of elements: If provided, then this list must contain at least one element. * Maximum number of elements: The list must not contain more than 50 elements. 3. *environment* — The definition of the Environment that the Environment Template defines. See [<Environment>](#4-environment). #### 1.2.1. Merging Environment Template Parameter Definitions When submitting a job using a Job Template and one or more Environment Templates, then two or more of the given Templates may contain job parameter definitions with the same job parameter name. This section describes how we determine whether those definitions are in conflict, and how the constraints that they define are merged to derive the constraints on the job parameters' values. Job Parameter Definitions for the same parameter name are in conflict if: 1. They have differing values for the `type` property of the job parameter definition; or 2. The parameter type is "PATH" and either the `objectType` or `dataFlow` properties are defined with different values. Properties in a Job Parameter Definition such as the `minLength` and `allowedValues` define constraints on the value for the job parameter. These constraints do not need to be identical in every Job Parameter Definition for the same parameter name, but each constraint must become more constrained as a subsequent definition is merged with the previous ones in processing order -- the Environment Templates are processed in an order defined by the render management system or submission, and the Job Template is always processed last. The exception to this rule is the `default` property of a Job Parameter Definition; the default value for a job parameter is always the last `default` value defined in the template processing order. The merged job parameter definition that results from this process must be internally consistent to be considered valid -- for example, the value of the `default` property must adhere to the constraints in the definition. ## 2. `` ```bnf ::= | | | | | # @extension EXPR | # @extension EXPR | # @extension EXPR | # @extension EXPR | # @extension EXPR | # @extension EXPR | # @extension EXPR # @extension EXPR ``` When the `EXPR` extension is enabled, job parameter and task parameter type names become case-insensitive. For example, `INT`, `Int`, and `int` are all equivalent, as are `LIST[STRING]`, `List[String]`, and `list[string]`. See [RFC 0007](https://github.com/OpenJobDescription/openjd-specifications/blob/mainline/rfcs/0007-extend-parameter-types.md) for the design rationale. The `userInterface` property on parameter definitions provides hints to user interface implementations. Its fields are suggestions for how to present the parameter, not validation constraints. If a field does not apply to the chosen UI element, it should be ignored. Properties outside of `userInterface`, such as `allowedValues`, `minValue`, and `maxValue`, are constraints that must be enforced during validation. ### 2.1. `` Defines a job parameter that allows input of a single string value to a Job Template. The value of a Job Parameter of this type referenced in format strings as both: 1. `Param.` and 2. `RawParam.` A `` is the object: ```yaml name: type: "STRING" description: # @optional default: # @optional allowedValues: [ , ... ] # @optional minLength: ,# @optional maxLength: # @optional userInterface: # @optional control: enum("LINE_EDIT", "MULTILINE_EDIT", "DROPDOWN_LIST", "CHECK_BOX", "HIDDEN") # @optional label: # @optional groupLabel: # @optional ``` Where: 1. *name* — The name by which the parameter is referenced. See: [<Identifier>](#71-identifier). 2. *description* — A description to apply to the parameter. It has no functional purpose, but may appear in UI elements. See: [<Description>](#72-description). 3. *default* — Default value to use for the parameter if the submission does not include a value for it. See: [<JobParameterStringValue>](#25-jobparameterstringvalue). 4. *allowedValues* — An array of the values that the parameter is allowed to be. It is an error to provide a value that is not in this list, if the list is defined. See: [<JobParameterStringValue>](#25-jobparameterstringvalue). 5. *minLength* — The minimum allowable length of the parameter string value. 6. *maxLength* — The maximum allowable length of the parameter string value. 7. *userInterface* — User interface hints for this parameter. See [§2](#2-jobparameterdefinition) for how implementations should treat these fields. 1. *control* — The user interface control to use when editing this parameter. The default, if not provided, is "LINE_EDIT" when *allowedValues* is not provided, "DROPDOWN_LIST" when it is. 1. "LINE_EDIT" — This is a freeform string line edit control. Cannot be used when *allowedValues* is provided. 2. "MULTILINE_EDIT" — This is a freeform string multi-line edit control. It uses a fixed width font, intended for editing script code. The vertical size of this control is set to grow to fit the available space. Cannot be used when *allowedValues* is provided. 3. "DROPDOWN_LIST" — This is a dropdown list, for selecting from a fixed set of values. It requires that *allowedValues* is also provided. 4. "CHECK_BOX" — This is a checkbox control. It requires that *allowedValues* is also provided, and contains two values, case-insensitive, one representing true and another representing false. * Valid pairs are ["true", "false"], ["yes", "no"], ["on", "off"], and ["1", "0"]. 5. "HIDDEN" — This hides the parameter from the user interface. 2. *label* — The user interface label to use when displaying the parameter's edit control. If not provided, the implementation should default to using the parameter *name*. See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). 3. *groupLabel* — Parameters with the same *groupLabel* value should be placed together in a grouping control with the value of *groupLabel* as its label. See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). With the EXPR extension, the value of a Job Parameter of this type is referenced in format strings as `Param.`, returning a `string` type value. ### 2.2. `` Defines a job parameter that allows input to a Job Template of a single string value that represents a file or directory path on a filesystem, or a URI. This parameter type differs from a [``](#21-jobstringparameterdefinition) in that the value of the parameter automatically has defined and matching path mapping rules applied to it. The value of a Job Parameter of this type referenced in format strings as both: 1. `Param.` — the value of the parameter with applicable path mapping applied to it; and 2. `RawParam.` — the value of the parameter exactly as it was input to the job, with no path mapping applied to it. **`@extension EXPR` — URI values**: When the EXPR extension is enabled, PATH parameter values may be URIs (values with a `scheme://` prefix, e.g. `s3://bucket/key`). URI values are not subject to relative path resolution — they are not joined with the job template directory or the current working directory. If no path mapping rule matches a URI value, it passes through to `Param.` unchanged. See the [Expression Language path type description](2026-02-Expression-Language#121-types) for how path operations handle URIs. A `` is the object: ```yaml name: type: "PATH" description: # @optional default: # @optional allowedValues: [ , ... ] # @optional minLength: # @optional maxLength: # @optional objectType: enum("FILE", "DIRECTORY") # @optional dataFlow: enum("NONE", "IN", "OUT", "INOUT") # @optional userInterface: # @optional control: enum("CHOOSE_INPUT_FILE", "CHOOSE_OUTPUT_FILE", "CHOOSE_DIRECTORY", "DROPDOWN_LIST", "HIDDEN") # @optional label: # @optional groupLabel: # @optional fileFilters: [ , ... ] # @optional fileFilterDefault: # @optional ``` Where: 1. *name* — The name by which the parameter is referenced. See: [<Identifier>](#71-identifier). 2. *description* — A description to apply to the parameter. It has no functional purpose, but may appear in UI elements. See: [<Description>](#72-description). 3. *default* — Default value to use for the parameter if the submission does not include a value for it. See: [<JobParameterStringValue>](#25-jobparameterstringvalue). 4. *allowedValues* — An array of the values that the parameter is allowed to be. It is an error to provide a value that is not in this list, if the list is defined. See: [<JobParameterStringValue>](#25-jobparameterstringvalue). 5. *minLength* — The minimum allowable length of the parameter string value. 6. *maxLength* — The maximum allowable length of the parameter string value. 7. *objectType* — The type of object the path represents; either a FILE or a DIRECTORY. Default is DIRECTORY. 8. *dataFlow* — Whether the object the path represented serves as input, output or both for the Job. Default is NONE. 9. *userInterface — User interface properties for this parameter* 1. *control* — The user interface control to use when editing this parameter. The default, if not provided, depends on *objectType*, *dataFlow*, and *allowedValues*. If *objectType* is FILE, then if *dataFlow* is "OUT", it is "CHOOSE_OUTPUT_FILE", otherwise it is "CHOOSE_INPUT_FILE". If *objectType* is not "FILE", then it is "CHOOSE_DIRECTORY". If *allowedValues* is provided, then the default is instead "DROPDOWN_LIST". 1. "CHOOSE_INPUT_FILE" — This is a combination of a line edit and a button that uses the system's input file dialog. Cannot be used when *allowedValues* is provided. 2. "CHOOSE_OUTPUT_FILE" — This is a combination of a line edit and a button that uses the system's output/save file dialog. Cannot be used when *allowedValues* is provided. 3. "CHOOSE_DIRECTORY" — This is a combination of a line edit and a button that uses the system's directory dialog. Cannot be used when *allowedValues* is provided. 4. "DROPDOWN_LIST" — This is a dropdown list, for selecting from a fixed set of values. It requires that *allowedValues* is also provided. 5. "HIDDEN" — This hides the parameter from the user interface. 2. *label* — The user interface label to use when displaying the parameter's edit control. If not provided, the implementation should default to using the parameter *name*. See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). 3. *groupLabel* — Parameters with the same *groupLabel* value should be placed together in a grouping control with the value of *groupLabel* as its label. See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). 4. fileFilters — Can be provided when the *uiControl* is "CHOOSE_INPUT_FILE" or "CHOOSE_OUTPUT_FILE". Defines the file filters that are shown in the file choice dialog. Maximum of 20 filters. 5. fileFilterDefault — Can be provided when the *uiControl* is "CHOOSE_INPUT_FILE" or "CHOOSE_OUTPUT_FILE". The default file filter that's shown in the file choice dialog. With the EXPR extension, the value of a Job Parameter of this type is referenced in format strings as `Param.`, returning a `path` type value. ### 2.3 `` Defines a job parameter that allows input to a Job Template of a single integer value. The value of a Job Parameter of this type referenced in format strings as both: 1. `Param.` and 2. `RawParam.` A `` is the object: ```yaml name: type: "INT" description: # @optional default: | # @optional allowedValues: [ | ,... ] # @optional minValue: | # @optional maxValue: | # @optional userInterface: # @optional control: enum("SPIN_BOX", "DROPDOWN_LIST", "HIDDEN") # @optional label: # @optional groupLabel: # @optional singleStepDelta: # @optional ``` Where `` is a string whose value is the string representation of an integer value in base-10, and: 1. *name* — The name by which the parameter is referenced. See: [<Identifier>](#71-identifier). 2. *description* — A description to apply to the parameter. It has no functional purpose, but may appear in UI elements. See: [<Description>](#72-description). 3. *default* — Default value to use for the parameter if the submission does not include a value for it. 4. *allowedValues* — An array of the values that the parameter is allowed to be. It is an error to provide a value that is not in this list, if the list is defined. 5. *minValue* — Minimum allowable value for the parameter. It is an error to provide a value for the parameter that is less than this. 6. *maxValue* — Maximum allowable value for the parameter. It is an error to provide a value for the parameter that is greater than this. 7. *userInterface — User interface properties for this parameter* 1. *control* — The user interface control to use when editing this parameter. The default, if not provided, is "SPIN_BOX" when *allowedValues* is not provided, "DROPDOWN_LIST" when it is. 1. "SPIN_BOX" — This is an integer editing control. Cannot be used when *allowedValues* is provided. 2. "DROPDOWN_LIST" — This is a dropdown list, for selecting from a fixed set of values. It requires that *allowedValues* is provided. 3. "HIDDEN" — This hides the parameter from the user interface. 2. *label* — The user interface label to use when displaying the parameter's edit control. If not provided, the implementation should default to using the parameter *name*. See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). 3. *groupLabel* — Parameters with the same *groupLabel* value should be placed together in a grouping control with the value of *groupLabel* as its label. See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). 4. *singleStepDelta* — How much the value changes for a single step modification, such as selecting an up or down arrow in the user interface control. With the EXPR extension, the value of a Job Parameter of this type is referenced in format strings as `Param.`, returning an `int` type value. ### 2.4. `` Defines a job parameter that allows input to a Job Template of a single floating point or integer value. The value of a Job Parameter of this type referenced in format strings as both: 1. `Param.` and 2. `RawParam.` A `` is the object: ```yaml name: type: "FLOAT" description: # @optional default: | # @optional allowedValues: [ | ,... ] # @optional minValue: | # @optional maxValue: | # @optional userInterface: # @optional control: enum(SPIN_BOX, DROPDOWN_LIST, HIDDEN) # @optional label: # @optional groupLabel: # @optional decimals: # @optional singleStepDelta: # @optional ``` Where `` is a string whose value is the string representation of a floating point or integer value in base-10, and: 1. *name* — The name by which the parameter is referenced. See: [<Identifier>](#71-identifier). 2. *description* — A description to apply to the parameter. It has no functional purpose, but may appear in UI elements. See: [<Description>](#72-description). 3. *default* — Default value to use for the parameter if the submission does not include a value for it. 4. *allowedValues* — An array of the values that the parameter is allowed to be. It is an error to provide a value that is not in this list, if the list is defined. 5. *minValue* — Minimum allowable value for the parameter. It is an error to provide a value for the parameter that is less than this. 6. *maxValue* — Maximum allowable value for the parameter. It is an error to provide a value for the parameter that is greater than this. 7. *userInterface — User interface properties for this parameter* 1. *control* — The user interface control to use when editing this parameter. The default, if not provided, is "SPIN_BOX" when *allowedValues* is not provided, "DROPDOWN_LIST" when it is. 1. "SPIN_BOX" — This is a floating point editing control. Cannot be used when *allowedValues* is provided. 2. "DROPDOWN_LIST" — This is a dropdown list, for selecting from a fixed set of values. It requires that *allowedValues* is provided. 3. "HIDDEN" — This hides the parameter from the user interface. 2. *label* — The user interface label to use when displaying the parameter's edit control. If not provided, the implementation should default to using the parameter *name*. See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). 3. *groupLabel* — Parameters with the same *groupLabel* value should be placed together in a grouping control with the value of *groupLabel* as its label. See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). 4. *decimals* — This is the number of places editable after the decimal point. If *decimals* is not provided then an adaptive decimal mode will be used. 5. *singleStepDelta* — How much the value changes for a single step modification, such as selecting an up or down arrow in the user interface control. If *decimals* is provided, this is an absolute value, otherwise it is the fraction of the current value to use as an adaptive step. With the EXPR extension, the value of a Job Parameter of this type is referenced in format strings as `Param.`, returning a `float` type value. ### 2.5. `` *This is a supplemental value type referenced by the parameter definitions in sections 2.1–2.4 and 2.9+.* A string value subject to the following constraints: 1. Allowable characters: Any. 2. Minimum length: There is no minimum length. 3. Maximum length: 1024 characters. ### 2.6. `` *This is a supplemental value type referenced by the parameter definitions in sections 2.1–2.4 and 2.9+.* A string value subject to the following constraints: 1. Allowable characters: Any unicode character except those in the Cc unicode character category. 2. Minimum length: 1 character. 3. Maximum length: 64 characters. ### 2.7. `` *This is a supplemental value type referenced by the parameter definitions in sections 2.1–2.4 and 2.9+.* Represents one named file type for an input or output file choice dialog. For example: `{"label": "Image Files", "patterns": ["*.png", "*.jpg", "*.exr"]}` or `{"label": "All Files", "patterns": ["*"]}`. A `` is the object: ```yaml label: patterns: [ , ... ] ``` ### 2.8. `` *This is a supplemental value type referenced by the parameter definitions in sections 2.1–2.4 and 2.9+.* A string value subject to the following constraints: 1. Allowable values: "*", "*.*", and "*.[:file-extension-chars:]+". The characters that :file-extension-chars: can take on are any unicode character except 1. The Cc unicode character category. 2. Path separators "\" and "/". 3. Wildcard characters "*", "?", "[", "]". 4. Characters commonly disallowed in paths: "#", "%", "&", "{", "}", "<", ">", "$", "!", "'", "\"", ":", "@", "`", "|", and "=". 2. Minimum length: 1 character. 3. Maximum length: 20 characters. ### 2.9. `` `@extension EXPR` Defines a job parameter that accepts a boolean value. ```yaml name: type: "BOOL" description: # @optional default: # @optional userInterface: # @optional control: enum("CHECK_BOX", "HIDDEN") # @optional label: # @optional groupLabel: # @optional ``` Accepted values are: - JSON/YAML boolean literals: `true`, `false` - Integer or float `1` or `1.0` (true), `0` or `0.0` (false) - Case-insensitive strings representing true: `"true"`, `"yes"`, `"on"`, `"1"` - Case-insensitive strings representing false: `"false"`, `"no"`, `"off"`, `"0"` Where: 1. *name* — The name by which the parameter is referenced. See: [<Identifier>](#71-identifier). 2. *description* — A description to apply to the parameter. It has no functional purpose, but may appear in UI elements. See: [<Description>](#72-description). 3. *default* — Default value to use for the parameter if the submission does not include a value for it. 4. *userInterface* — User interface properties for this parameter. 1. *control* — The user interface control to use when editing this parameter. The default, if not provided, is "CHECK_BOX". 1. "CHECK_BOX" — A checkbox control for boolean input. 2. "HIDDEN" — This hides the parameter from the user interface. 2. *label* — The user interface label to use when displaying the parameter's edit control. If not provided, the implementation should default to using the parameter *name*. See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). 3. *groupLabel* — Parameters with the same *groupLabel* value should be placed together in a grouping control with the value of *groupLabel* as its label. See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). The value of a Job Parameter of this type is referenced in format strings as `Param.`, returning a `bool` type value. Note: Unlike other parameter types, `BOOL` does not support `allowedValues` because restricting to only `true` or only `false` does not provide meaningful value. ### 2.10. `` `@extension EXPR` Defines a job parameter that accepts a range expression string conforming to the [``](#34111-intrangeexpr) grammar. ```yaml name: type: "RANGE_EXPR" description: # @optional default: # @optional, must be valid minLength: # @optional maxLength: # @optional userInterface: # @optional control: enum("LINE_EDIT", "HIDDEN") # @optional label: # @optional groupLabel: # @optional ``` Where: 1. *name* — The name by which the parameter is referenced. See: [<Identifier>](#71-identifier). 2. *description* — A description to apply to the parameter. It has no functional purpose, but may appear in UI elements. See: [<Description>](#72-description). 3. *default* — Default value to use for the parameter if the submission does not include a value for it. Must be a valid ``. 4. *minLength* — Minimum string length of the range expression. Must be >= 1 if provided. 5. *maxLength* — Maximum string length of the range expression. Default is 1024. 6. *userInterface* — User interface properties for this parameter. 1. *control* — The user interface control to use when editing this parameter. The default, if not provided, is "LINE_EDIT". 1. "LINE_EDIT" — A single-line text input for entering range expressions. 2. "HIDDEN" — This hides the parameter from the user interface. 2. *label* — The user interface label to use when displaying the parameter's edit control. If not provided, the implementation should default to using the parameter *name*. See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). 3. *groupLabel* — Parameters with the same *groupLabel* value should be placed together in a grouping control with the value of *groupLabel* as its label. See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). The value of a Job Parameter of this type is referenced in format strings as: 1. `Param.` — Returns a `range_expr` type value. 2. `RawParam.` — Returns a `range_expr` type value (identical to `Param.`). 3. `list(Param.)` — Returns a `list[int]` with the expanded values. ### 2.11. `` `@extension EXPR` Defines a job parameter that accepts a list of string values. ```yaml name: type: "LIST[STRING]" description: # @optional default: [ , ... ] # @optional minLength: # @optional maxLength: # @optional item: # @optional allowedValues: [ , ... ] # @optional minLength: # @optional maxLength: # @optional userInterface: # @optional control: enum("LINE_EDIT_LIST", "HIDDEN") # @optional label: # @optional groupLabel: # @optional ``` Where: 1. *name* — The name by which the parameter is referenced. See: [<Identifier>](#71-identifier). 2. *description* — A description to apply to the parameter. It has no functional purpose, but may appear in UI elements. See: [<Description>](#72-description). 3. *default* — Default value to use for the parameter if the submission does not include a value for it. 4. *minLength*/*maxLength* — Constrain the number of items in the list. 5. *item* — Constraints for each item in the list. 1. *allowedValues* — An array of the values that each item is allowed to be. 2. *minLength*/*maxLength* — Constrain the string length of each item. 6. *userInterface* — User interface properties for this parameter. 1. *control* — The user interface control to use when editing this parameter. The default, if not provided, is "LINE_EDIT_LIST". 1. "LINE_EDIT_LIST" — A list of line edit controls. 2. "HIDDEN" — This hides the parameter from the user interface. 2. *label* — See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). 3. *groupLabel* — See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). The value of a Job Parameter of this type is referenced in format strings as: 1. `Param.` — Returns a `list[string]` type value. 2. `Param.[i]` — Returns the i-th element as `string`. 3. `len(Param.)` — Returns the count of elements. ### 2.12. `` `@extension EXPR` Defines a job parameter that accepts a list of path values. ```yaml name: type: "LIST[PATH]" description: # @optional objectType: enum("FILE", "DIRECTORY") # @optional dataFlow: enum("IN", "OUT", "INOUT", "NONE") # @optional default: [ , ... ] # @optional minLength: # @optional maxLength: # @optional item: # @optional allowedValues: [ , ... ] # @optional minLength: # @optional maxLength: # @optional userInterface: # @optional control: enum("CHOOSE_INPUT_FILE_LIST", "CHOOSE_OUTPUT_FILE_LIST", "CHOOSE_DIRECTORY_LIST", "HIDDEN") # @optional label: # @optional groupLabel: # @optional fileFilters: [ , ... ] # @optional fileFilterDefault: # @optional ``` Where: 1. *name* — The name by which the parameter is referenced. See: [<Identifier>](#71-identifier). 2. *description* — A description to apply to the parameter. It has no functional purpose, but may appear in UI elements. See: [<Description>](#72-description). 3. *objectType* — The type of object the paths represent; either FILE or DIRECTORY. Default is DIRECTORY. 4. *dataFlow* — Whether the objects the paths represent serve as input, output or both for the Job. Default is NONE. 5. *default* — Default value to use for the parameter if the submission does not include a value for it. 6. *minLength*/*maxLength* — Constrain the number of paths in the list. 7. *item* — Constraints for each item in the list. 1. *allowedValues* — An array of the values that each item is allowed to be. 2. *minLength*/*maxLength* — Constrain the string length of each path. 8. *userInterface* — User interface properties for this parameter. 1. *control* — The user interface control to use. The default depends on *objectType* and *dataFlow*: If *objectType* is FILE and *dataFlow* is "OUT", default is "CHOOSE_OUTPUT_FILE_LIST". If *objectType* is FILE otherwise, default is "CHOOSE_INPUT_FILE_LIST". If *objectType* is DIRECTORY, default is "CHOOSE_DIRECTORY_LIST". 1. "CHOOSE_INPUT_FILE_LIST" — A list of input file choice controls. 2. "CHOOSE_OUTPUT_FILE_LIST" — A list of output file choice controls. 3. "CHOOSE_DIRECTORY_LIST" — A list of directory choice controls. 4. "HIDDEN" — This hides the parameter from the user interface. 2. *label* — See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). 3. *groupLabel* — See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). 4. *fileFilters* — File filters for the file choice dialog (only for CHOOSE_INPUT_FILE_LIST/CHOOSE_OUTPUT_FILE_LIST). 5. *fileFilterDefault* — Default file filter for the file choice dialog. The value of a Job Parameter of this type is referenced in format strings as: 1. `Param.` — Returns a `list[path]` type value with path mapping applied. 2. `RawParam.` — Returns a `list[string]` type value without path mapping. 3. `Param.[i]` — Returns the i-th element as `path`. 4. `len(Param.)` — Returns the count of elements. ### 2.13. `` `@extension EXPR` Defines a job parameter that accepts a list of integer values. ```yaml name: type: "LIST[INT]" description: # @optional default: [ , ... ] # @optional minLength: # @optional maxLength: # @optional item: # @optional allowedValues: [ , ... ] # @optional minValue: # @optional maxValue: # @optional userInterface: # @optional control: enum("SPIN_BOX_LIST", "HIDDEN") # @optional label: # @optional groupLabel: # @optional singleStepDelta: # @optional ``` Where: 1. *name* — The name by which the parameter is referenced. See: [<Identifier>](#71-identifier). 2. *description* — A description to apply to the parameter. It has no functional purpose, but may appear in UI elements. See: [<Description>](#72-description). 3. *default* — Default value to use for the parameter if the submission does not include a value for it. 4. *minLength*/*maxLength* — Constrain the number of items in the list. 5. *item* — Constraints for each item in the list. 1. *allowedValues* — An array of the values that each item is allowed to be. 2. *minValue*/*maxValue* — Constrain the value of each integer item. 6. *userInterface* — User interface properties for this parameter. 1. *control* — The user interface control to use when editing this parameter. The default, if not provided, is "SPIN_BOX_LIST". 1. "SPIN_BOX_LIST" — A list of integer editing controls. 2. "HIDDEN" — This hides the parameter from the user interface. 2. *label* — See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). 3. *groupLabel* — See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). 4. *singleStepDelta* — How much the value changes for a single step modification. The value of a Job Parameter of this type is referenced in format strings as: 1. `Param.` — Returns a `list[int]` type value. 2. `Param.[i]` — Returns the i-th element as `int`. 3. `len(Param.)` — Returns the count of elements. ### 2.14. `` `@extension EXPR` Defines a job parameter that accepts a list of floating-point values. ```yaml name: type: "LIST[FLOAT]" description: # @optional default: [ , ... ] # @optional minLength: # @optional maxLength: # @optional item: # @optional allowedValues: [ , ... ] # @optional minValue: # @optional maxValue: # @optional userInterface: # @optional control: enum("SPIN_BOX_LIST", "HIDDEN") # @optional label: # @optional groupLabel: # @optional decimals: # @optional singleStepDelta: # @optional ``` Where: 1. *name* — The name by which the parameter is referenced. See: [<Identifier>](#71-identifier). 2. *description* — A description to apply to the parameter. It has no functional purpose, but may appear in UI elements. See: [<Description>](#72-description). 3. *default* — Default value to use for the parameter if the submission does not include a value for it. 4. *minLength*/*maxLength* — Constrain the number of items in the list. 5. *item* — Constraints for each item in the list. 1. *allowedValues* — An array of the values that each item is allowed to be. 2. *minValue*/*maxValue* — Constrain the value of each float item. 6. *userInterface* — User interface properties for this parameter. 1. *control* — The user interface control to use when editing this parameter. The default, if not provided, is "SPIN_BOX_LIST". 1. "SPIN_BOX_LIST" — A list of floating point editing controls. 2. "HIDDEN" — This hides the parameter from the user interface. 2. *label* — See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). 3. *groupLabel* — See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). 4. *decimals* — The number of places editable after the decimal point. 5. *singleStepDelta* — How much the value changes for a single step modification. The value of a Job Parameter of this type is referenced in format strings as: 1. `Param.` — Returns a `list[float]` type value. 2. `Param.[i]` — Returns the i-th element as `float`. 3. `len(Param.)` — Returns the count of elements. ### 2.15. `` `@extension EXPR` Defines a job parameter that accepts a list of boolean values. ```yaml name: type: "LIST[BOOL]" description: # @optional default: [ , ... ] # @optional minLength: # @optional maxLength: # @optional userInterface: # @optional control: enum("CHECK_BOX_LIST", "HIDDEN") # @optional label: # @optional groupLabel: # @optional ``` Each list item accepts the same values as [``](#29-jobboolparameterdefinition): - JSON/YAML boolean literals: `true`, `false` - Integer or float `1` or `1.0` (true), `0` or `0.0` (false) - Case-insensitive strings representing true: `"true"`, `"yes"`, `"on"`, `"1"` - Case-insensitive strings representing false: `"false"`, `"no"`, `"off"`, `"0"` Where: 1. *name* — The name by which the parameter is referenced. See: [<Identifier>](#71-identifier). 2. *description* — A description to apply to the parameter. It has no functional purpose, but may appear in UI elements. See: [<Description>](#72-description). 3. *default* — Default value to use for the parameter if the submission does not include a value for it. 4. *minLength*/*maxLength* — Constrain the number of items in the list. 5. *userInterface* — User interface properties for this parameter. 1. *control* — The user interface control to use when editing this parameter. The default, if not provided, is "CHECK_BOX_LIST". 1. "CHECK_BOX_LIST" — A list of checkbox controls. 2. "HIDDEN" — This hides the parameter from the user interface. 2. *label* — See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). 3. *groupLabel* — See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). The value of a Job Parameter of this type is referenced in format strings as: 1. `Param.` — Returns a `list[bool]` type value. 2. `Param.[i]` — Returns the i-th element as `bool`. 3. `len(Param.)` — Returns the count of elements. ### 2.16. `` `@extension EXPR` Defines a job parameter that accepts a nested list of integer values. This enables use cases like representing graph adjacency lists for task-task dependencies. ```yaml name: type: "LIST[LIST[INT]]" description: # @optional default: [ [ , ... ], ... ] # @optional minLength: # @optional maxLength: # @optional item: # @optional minLength: # @optional maxLength: # @optional item: # @optional allowedValues: [ , ... ] # @optional minValue: # @optional maxValue: # @optional userInterface: # @optional control: enum("HIDDEN") # @optional label: # @optional groupLabel: # @optional ``` Where: 1. *name* — The name by which the parameter is referenced. See: [<Identifier>](#71-identifier). 2. *description* — A description to apply to the parameter. It has no functional purpose, but may appear in UI elements. See: [<Description>](#72-description). 3. *default* — Default value to use for the parameter if the submission does not include a value for it. 4. *minLength*/*maxLength* — Constrain the number of inner lists. 5. *item* — Constraints for each inner list. 1. *minLength*/*maxLength* — Constrain the size of each inner list. 2. *item* — Constraints for each integer in the inner list. 1. *allowedValues* — An array of the values that each integer is allowed to be. 2. *minValue*/*maxValue* — Constrain the value of each integer. 6. *userInterface* — User interface properties for this parameter. 1. *control* — The only supported control is "HIDDEN", which hides the parameter from the user interface. 2. *label* — See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). 3. *groupLabel* — See: [<UserInterfaceLabelStringValue>](#26-userinterfacelabelstringvalue). The value of a Job Parameter of this type is referenced in format strings as: 1. `Param.` — Returns a `list[list[int]]` type value. 2. `Param.[i]` — Returns the i-th element as `list[int]`. 3. `Param.[i][j]` — Returns the j-th element of the i-th list as `int`. 4. `len(Param.)` — Returns the count of outer list elements. 5. `len(Param.[i])` — Returns the count of inner list elements. ## 3. `` A `` defines a single Step in the Job; the action(s) that it takes, its dependencies, the parameter space that maps to the Step's Tasks, and its runtime environment and requirements. A `` is the object: ```yaml name: description: # @optional let: # @optional @extension EXPR dependencies: [ , ... ] # @optional stepEnvironments: [ , ... ] # @optional hostRequirements: # @optional parameterSpace: # @optional script: ``` Where: 1. *name* — The name to identify the Step within the Job. Each Step within a Job Template must have name that differs from the names of all other Steps in the same Job Template. See: [<StepName>](#31-stepname). 2. *description* — A description to apply to the step. It has no functional purpose, but may appear in UI elements. See: [<Description>](#72-description). 3. *let* — An ordered list of expression bindings evaluated once per step. Bound names are available in *stepEnvironments*, *hostRequirements*, *parameterSpace*, and *script* fields. See: [<LetBindings>](#36-letbindings). 4. *dependencies* — A list of the dependencies of this Step. These dependencies must be resolved before the Tasks of the Step may be scheduled. See: [<StepDependency>](#32-stepdependency) * Minimum number of elements: If provided, then this list must contain at least one element. * Maximum number of elements: There is no maximum defined, though implementations may choose to constrain the number of dependencies. 5. *stepEnvironments* — An ordered list of the environments that are required to run Tasks in this Step. These are entered in the order provided at the start of every Session for Tasks in the Step, and exited in the reverse order at the end of those Sessions. See: [<Environment>](#4-environment). * Constraints: 1. No two Environments in this list may have the same value for the `name` property. 2. The Environments defined in this list must not have the same `name` as a Job Environment defined in the same Job Template. 6. *hostRequirements* — Describes the requirements on Worker host's capabilities that must be satisfied for the Task(s) of the Step to be scheduled to the host. See: [<HostRequirements>](#33-hostrequirements). 7. *parameterSpace* — Defines the parameterization of the Step's action; the available parameters, the values that they take on, and how those parameters' values are combined to produce the Tasks of the Step. Absent this property the Step is run a single time. 8. *script* — The action that is taken by this Step's Tasks when they are run on a Worker host. ### 3.1. `` A string subject to the following constraints: 1. Allowed characters: Any unicode character except those in the Cc unicode character category. 2. Minimum length: 1 character. 3. Maximum length: 64 characters. 512 characters if using the `FEATURE_BUNDLE_1` extension. ### 3.2. `` This entity is used by the template author to specify a Step in the same Job that a Step depends upon. A `` is the object: ```yaml dependsOn: "" ``` Where: 1. *dependsOn* — Provides the name of another step in the same job upon which this step depends. The Task(s) of this Step may be scheduled only when the depended-upon Step has fully completed successfully. ### 3.3. `` This entity is used by the template author to describe the requirements on Worker host and/or render manager's available capabilities that must be satisfied for the Task(s) of the Step to be scheduled to the host. Each requirement corresponds to an attribute of a host or render manager that must be satisfied to allow the Step to be scheduled to the host. Some examples of concrete attributes include processor architecture (x86_64, arm64, etc), the number of CPU cores, the amount of system memory, or available floating licenses for an application. We also allow for user-defined whose meaning is defined by the customer; a "SoftwareConfig" requirement whose values could be "Option1" or "Option2", for example. There are two types of requirements: attribute and amount. A `` is the object: ```yaml amounts: [ , ... ] # @optional attributes: [ , ... ] # @optional ``` Where: 1. *amounts* — Defines a set of quantifiable requirements on the host that must be met and reserved for a Session running Tasks from this Step to be scheduled to the host. See: [<AmountRequirement>](#331-amountrequirement). 2. *attributes* — Defines a set of attributes that a host must have for a Session running Tasks from this Step to be scheduled to the host. See: [<AttributeRequirement>](#332-attributerequirement). With the constraints: 1. If this object is provided in a Job Template, then at least one of the *amounts* or *attributes* properties must be defined. 2. The sum of the lengths of the *amounts* and *attributes* arrays must not exceed 50 elements. 3. No two elements in the *amounts* array may have the same value for the *name* property. 4. No two elements in the *attributes* array may have the same value for the *name* property. #### 3.3.1. `` Amount requirements are the mechanism for defining a quantity of something that the Worker host or render manager needs to have for a Step to run. They represent quantifiable things that need to be reserved to do the work — vCPUs, memory, licenses, etc. They are always non-negative floating point valued, and a Step can require a certain amount of that capability to be able to run — "at least 4 CPU cores" for example. Further, a quantity of each amount required are logically allocated to a Session while that session is running on a host. A Step requiring, say, "at least 4 CPU cores", might result in a Session with 4 CPU cores allocated to it being created on a host. Those cores are reserved for that Session while that Session is running on the host; effectively making the number of available cores on the host 4 less for scheduling purposes during the duration of the Session. Logically allocating amounts to Sessions is the key mechanism by which system resources can be optimally utilized through bin packing multiple running Sessions onto hosts at the same time. An `` is the object: ```yaml name: min: # @optional min: | # @optional @fmtstring @extension FEATURE_BUNDLE_1 max: # @optional max: | # @optional @fmtstring @extension FEATURE_BUNDLE_1 ``` Where:`` is a string whose value is the string representation of a non-zero and positive floating point or integer value in base-10, `` is a string whose value is the string representation of a positive floating point or integer value in base-10, and: 1. *name* — Is a dotted name that identifies the specific host capability that is being required. 2. *min* — If provided, then the host must have at least the given amount of the named capability available and reserved for a Session running Tasks from this Step to be scheduled to the host. If not provided, then the default is 0 unless the specific host capability defines a minimum. Can only be a `` when using the extension `FEATURE_BUNDLE_1`. 3. *max* — If provided, then the host must have at least the given amount of the named capability available and reserved for a Session running Tasks from this Step to be scheduled to the host. Can only be a `` when using the extension `FEATURE_BUNDLE_1`. Subject to the constraint that at least one of *min* or *max* must be provided. ##### 3.3.1.1. `` A string subject to the following constraints. 1. Minimum length: 1 character. 2. Maximum length: 100 characters. 3. Its format matches the pattern `[:]amount.[.]*` where: 1. `[:]` denotes an optional vendor-specific prefix. 2. This specification has reserved specific values of the first `` after "amount." for use in this and future revisions. The reserved values are: "worker", "job", "step", and "task" 4. The value is not case-sensitive - All comparisons between strings of this type must be case-insensitive comparisons. See [<Identifier>](#71-identifier) for information on the `` substring. This specification defines the following amount capabilities, but an implementation is allowed, and encouraged, to allow users to define their own custom capabilities. |**Capability Name**|**Minimum Value**|**Description**| |---|---|---| |amount.worker.vcpu |1|A number of vCPUs/CPU-cores available on the host.| |amount.worker.memory |0|An amount of system memory available on the host. Units: MiB. | |amount.worker.gpu |0|A number of GPUs available on the host.| |amount.worker.gpu.memory |0|The lower bound of total memory provided by each GPU on the host. For example, if a host has one GPU with 4096 and one GPU with 2048, this value would be 2048. Units: MiB.| |amount.worker.disk.scratch|0|A static amount of disk storage installed on the host for use as scratch space. Units: GiB.| #### 3.3.2. `` Attribute requirements are the mechanism for defining an abstract or concrete attribute/property the host must have for a Step to run. They are always defined on a host as a set of strings. A Step can assert that it requires that a host have specific value(s) of the attribute for it to be scheduled to the host. An `` is the object: ```yaml name: anyOf: [ , ... ] # @optional @fmtstring allOf: [ , ... ] # @optional @fmtstring ``` Where: 1. *name* — Is a dotted name that identifies the specific host capability that is being required. 2. *anyOf* — For the Step to be scheduled to it, the host's value for the named capability must have **at least one** of the given values. This comparison is case-insensitive. * Minimum number of elements: If provided, then this list must contain at least one element. * Maximum number of elements: The list must not contain more than 50 elements. 3. *allOf* — For the Step to be scheduled to it, the host's value for the named capability must have **all** the given values. This comparison is case-insensitive. * Minimum number of elements: If provided, then this list must contain at least one element. * Maximum number of elements: The list must not contain more than 50 elements. Subject to the constraint that at least one of *anyOf* or *allOf* must be provided. ##### 3.3.2.1. `` A string subject to the following constraints. 1. Minimum length: 1 character. 2. Maximum length: 100 characters. 3. Its format matches the pattern `[:]attr.[.]*` where: 1. `[:]` denotes an optional vendor-specific prefix. 2. This specification has reserved specific values of the first `` after "amount." for use in this and future revisions. The reserved values are: "worker", "job", "step", and "task" 4. The value is not case-sensitive - All comparisons between strings of this type must be case-insensitive comparisons. See [<Identifier>](#71-identifier) for information on the `` substring. This specification defines the following attribute capabilities, but an implementation is allowed, and encouraged, to allow users to define their own custom capabilities. |**Capability Name**|**Values**|**Description**| |---|---|---| |attr.worker.os.family|linux, windows, macos|The family of operating system on the host.| |attr.worker.cpu.arch |x86_64, arm64|The architecture of the CPUs on the host.| ##### 3.3.2.2. `` A [Format String](#73-format-strings) subject to the following constraints: 1. Minimum length: 1 character. 2. After the format string has been resolved: 1. Max length: 100 characters 2. Unicode alphanumeric characters in the latin character set, plus the underscore and hyphen characters. 3. Must start with either a letter character or the underscore character. ### 3.4. `` The step parameter space defines the task parameters that are substituted into the `` to produce all the tasks to run. A `` is the object: ```yaml taskParameterDefinitions: [ , ... ] combination: # @optional ``` Where: 1. *taskParameterDefinitions* — This is a list that defines the task parameters over which the Step's script is parameterized. Each task parameter defines its name, type, and the range of values that it takes. When the `TASK_CHUNKING` is used, only one `CHUNK[INT]` parameter may be included. 1. Minimum number of elements: If provided, then this array must have at least one element in the list. 2. Maximum number of elements: The list must contain no more than 16 elements in the list. 2. *combination* — An expression that defines how the task parameters are combined to produce the parameter space that maps a Step to a set of Tasks. Each Task has a single value for each task parameter that specifies its coordinates in the defined space. If not provided, then the default is all possible combinations of task parameter values. #### 3.4.1. `` Definition of a single task parameter; its name, type, and the range of values that it takes. ```bnf ::= | | | | # @extension TASK_CHUNKING ``` ##### 3.4.1.1. `` An integer valued task parameter. An `` is the object: ```yaml name: type: "INT" range: | ``` With: ```bnf ::= [ | | , ... ] ``` Where `` is a string whose value is the string representation of an integer value in base-10, `` (See [<TaskParameterStringValue>](#342-taskparameterstringvalue)) must resolve to the string representation of an integer value in base-10, and: 1. *name* — The name of the parameter. 2. *type* — The literal "INT", defining this parameter as integer valued. 3. *range* — The list of values that the parameter takes on to define Tasks of the Step. 4. `` is subject to the constraints: * Minimum number of elements: If provided, then this list must contain at least one element. * Maximum number of elements: The list must not contain more than 1024 elements. The value of a task parameter of this type can be referenced in format strings that will be evaluated when running a Task using the following names: 1. `Task.Param.` and 2. `Task.RawParam.` ###### 3.4.1.1.1. `` This is a [Format String](#73-format-strings) with an expression for providing an array of integer values using a succinct string representation. The motivating use-case for this form is providing a succinct way to describe a frame range, but this has been generalized to apply to more than simple positive integer frame numbers. ```bnf ::= | , ::= ** | ** | ** ::= *-* ::= : ::= Any integer value (positive, negative, or zero) ::= base-10 non-zero number ::= whitespace character: tabs or spaces ``` With: 1. `` — The specific number given 2. `` = `x-y` — The set of values $`\{x\} \cup\{ x+m: m\in\mathbb{Z}^+, x+m\leq y\}`$ 3. `` = `x-y:n`— The set of values $`\{x\}\cup\{x+mn: m\in\mathbb{Z}^+, x+mn\leq y\textrm{ if }n>0, x+mn\geq y\textrm{ if }n<0\}`$ Subject to the constraint no two ranges in the expression are allowed to overlap. The elements of the range expression are combined to form a list of values in increasing order. For example: |``|**List of values**| |---|---| |"1 - 5"|`[1, 2, 3, 4, 5]`| |"1 - -1"|`[1]`| |"-1 - 1"|`[-1,0,1]`| |"1-5:2"|`[1,3,5]`| |"10-15:2,1-5"|`[1,2,3,4,5,10,12,14]`| |"1-10:4"|`[1,5,9]`| |"1-10:4,10-15"|Error: ranges overlap| ##### 3.4.1.2. `` A floating point valued task parameter. An `` is the object: ```yaml name: type: "FLOAT" range: ``` With: ```bnf ::= [ | | , ... ] ``` Where `` is a string whose value is the string representation of a floating point value in base-10, `` (See [<TaskParameterStringValue>](#342-taskparameterstringvalue)) must resolve to the string representation of a floating point value in base-10, and: 1. *name* — The name of the parameter. 2. *type* — The literal "FLOAT", defining this parameter as floating point valued. 3. *range* — The list of values that the parameter takes on to define Tasks of the Step. 4. `` is subject to the constraints: * Minimum number of elements: If provided, then this list must contain at least one element. * Maximum number of elements: The list must not contain more than 1024 elements. The value of a task parameter of this type can be referenced in format strings that will be evaluated when running a Task using the following names: 1. `Task.Param.` and 2. `Task.RawParam.` ##### 3.4.1.3. `` A string valued task parameter. A `` is the object: ```yaml name: type: "STRING" range: [ , ... ] # @fmtstring ``` 1. *name* — The name of the parameter. 2. *type* - The literal "STRING", defining this parameter as string valued. 3. *range* — The list of values that the parameter takes on to define tasks of the step. See: [<TaskParameterStringValue>](#342-taskparameterstringvalue). 1. Minimum list length: One element 2. Maximum list length: 1024 elements The value of a task parameter of this type can be referenced in format strings that will be evaluated when running a Task using the following names: 1. `Task.Param.` and 2. `Task.RawParam.` ##### 3.4.1.4. `` A string valued task parameter that represents an absolute path to a file or directory, and will automatically have any defined path mapping applied to it. A `` is the object: ```yaml name: type: "PATH" range: [ , ... ] # @fmtstring ``` 1. *name* — The name of the parameter. 2. *type* — The literal "PATH", defining this parameter as string valued path parameter. 3. *range* — The list of values that the parameter takes on to define tasks of the step. See: [<TaskParameterStringValue>](#342-taskparameterstringvalue). 1. Minimum list length: One element 2. Maximum list length: 1024 elements The value of a task parameter of this type can be referenced in format strings that will be evaluated when running a Task using the following names: 1. `Task.Param.` — the value of the parameter with relevant path mapping rules applied to it; and 2. `Task.RawParam.` — the value of the parameter as it was defined, with no path mapping rules applied. ##### 3.4.1.5. `` `@extension TASK_CHUNKING` An integer valued task parameter, processed as chunks instead of as individual elements. At most one `CHUNK[INT]` parameter can be specified in a step parameter space. When forming a chunk to run, all the non-chunked dimensions take on a single value, and the chunked dimension takes a set of values that satisfies the range constraint. A `` is the object: ```yaml name: type: "CHUNK[INT]" range: | chunks: defaultTaskCount: | # @fmtstring targetRuntimeSeconds: | # @optional @fmtstring rangeConstraint: "CONTIGUOUS" | "NONCONTIGUOUS" ``` See section `` for the definitions of `` and ``. 1. *name* — The name of the parameter. 2. *type* — The literal "CHUNK[INT]", defining this parameter as integer valued and processed as chunks. 3. *range* — The list of values that the parameter takes on to define Tasks of the Step. 4. *chunks* — Specifies how to form sets of values into chunks. 1. *defaultTaskCount* — How many tasks to combine into a single chunk by default. 1. Minimum value: 1 2. *targetRuntimeSeconds* — If provided and its value is greater than 0, the number of seconds to aim for when forming chunks. A scheduler can ignore this, or dynamically adjust the chunk task count to be closer to this value once some chunks have completed. When the value is 0, a scheduler should ignore this configuration and use `defaultTaskCount` for each chunk. 1. Minimum value: 0 3. *rangeConstraint* — If CONTIGUOUS, a chunk must always be a contiguous range of integers with two integers separated by "-" like a single "5-5" or interval "1-10". If NONCONTIGUOUS, a chunk can be an arbitrary set of integers following the `` syntax like "1,3,7-10:2". Frame ranges are inclusive, so "10-20" contains 11 frames. 5. `` is subject to the constraints: * Minimum number of elements: If provided, then this list must contain at least one element. * Maximum number of elements: The list must not contain more than 1024 elements. The value of a task parameter of this type can be referenced in format strings that will be evaluated when running a Task using the following names: 1. `Task.Param.` and 2. `Task.RawParam.` #### 3.4.2. `` A [Format String](#73-format-strings) subject to the following constraints: 1. Allowed characters: Any 2. Minimum length: 1 character. 3. Maximum length: 1024 characters after the format string has been resolved. #### 3.4.3. `` The combination expression defines how to combine the task parameters to define the parameter space of the Step. If not provided then the expression defaults to the product of all defined task parameters. The string takes the form: ```bnf ::= '*' | ::= | ::= '(' ')' ::= , | ``` Subject to the following constraints: 1. Allowed characters: Any allowed in an `` plus the space, `*`, `(`, and `)` characters. 2. Minimum length: 1 character. 3. Maximum length: 1280 characters. 4. Each `` in the expression must be the name of a defined task parameter, and each task parameter must occur exactly once in the entire expression. 5. Every comma-separated expression within an associative operator must have the exact same number of values defined in their range. 6. If a task parameter is chunked, for example it has type `CHUNK[INT]`, it must not be combined with any other task parameter using the associative operator. For example if `A` is chunked, then `A * B` is permitted but `(A, B)` is an error. For example, given the four Task Parameters named "A", "B", "C", and "D" with values: ```python A=[1,2,3] B=[10,11,12] C=[20,21] D=["a","b","c"] ``` The following table lists some expressions and the resulting parameter space. |**Expression**|**Parameter Space**| |---|---| |A * B |(A=1,B=10), (A=1,B=11), (A=1,B=12), (A=2,B=10), (A=2,B=11), ...| |(A,B) |(A=1,B=10), (A=2,B=11), (A=3,B=12)| |(A,B) * C |(A=1,B=10,C=20), (A=1,B=10,C=21), (A=2,B=11,C=20), (A=2,B=11,C=21), ...| |(A,B,D) |(A=1,B=10,D=a), (A=2,B-11,D=b), (A=3,B=10,D=c)| |(A,C) |Error: length mismatch (A and C have differing numbers of values)| |(A,B,A) |Error: each parameter may only appear once in the expression.| If `A` has type `CHUNK[INT]`, the parameter space is the same as if it had type `INT`, but each chunk provided to the `onRun` action specifies an integer range expression for `A` instead of a single value. The scheduler might select the following chunks when `rangeConstraint` is set to `CONTIGUOUS`: (A="1-1", B=10), (A="2-2", B=10), (A="3-3", B=10), (A="1-2", B=11), (A="3-3", B=11), (A="1-3", B=12) ### 3.5. `` The Script of a Step defines the properties of the action that the Step runs on a Worker host. A `` is the object: ```yaml let: # @optional @extension EXPR actions: # @incompatible python | bash | cmd | powershell | node embeddedFiles: [ , ... ] # @optional @incompatible python | bash | cmd | powershell | node python | bash | cmd | powershell | node: # @optional @fmtstring[host] @incompatible command embeddedFiles @extension FEATURE_BUNDLE_1 ``` Where: 1. *let* — An ordered list of expression bindings evaluated once per task. Bound names are available in *actions* and *embeddedFiles* fields, and can reference `Task.Param.*` values. See: [<LetBindings>](#36-letbindings). 2. *actions* — The Actions that are run by Tasks of the Step. 3. *embeddedFiles* — Files embedded into the Step that are materialized to a Session's working directory as the Step's Task is running within the Session. See: [<EmbeddedFile>](#6-embeddedfile). 1. Minimum number of items: If defined, then there must be at least one element in this list. 2. Maximum number of items: There is no limit on the number of elements in this list. 4. *bash | cmd | node | powershell | python* - Syntactic sugar for scripts, removes some commonly needed boilerplate for the given script interpreter. The format string scopes available to format strings within a `` are: 1. `Param.*` and `RawParam.*` — Values of Job Parameters. 2. `Session.*` — Values such as the Session's working directory. 3. `Task.*` — Values of embedded file locations defined within the ``, and Task Parameters. 4. Names bound by `let` in the enclosing `` and ``. Available with the `EXPR` extension. #### 3.5.1. `` The Actions of a Step are the set of commands that are run by the Worker Agent to accomplish the goal(s) of the Step. ```yaml onRun: ``` Where: 1. *onRun* — The action that is run when a Task for the Step is run on a host. See: [<Action>](#5-action). ### 3.6. `` Available when using the `EXPR` extension. A `` is an ordered array of `` strings: ```yaml let: - - ... ``` Bindings are evaluated in declaration order. Later bindings can reference names from earlier bindings in the same `let` block. A binding that shadows a previous binding in the same `let` block or any enclosing scope is an error. For example, a `let` binding in a `` cannot shadow a binding from the enclosing ``'s `let` block, and a `let` binding in a `