Skip to content

CWL reference

This page covers CWL declarations used by AntFlow's process descriptions, execution forms, and launchers. For the language itself, use the CWL user guide and CWL v1.2 specification.

The examples below are fragments, not complete workflows. Add them at the appropriate location in your CWL document, then validate and test the package.

Input handling

AntFlow translates CWL input declarations into an OGC Process JSON Schema. Scalar types include string, boolean, int, long, float, and double. Structured types include arrays and records with named fields.

Use label for a readable field name and doc to explain the expected value. Declare defaults when appropriate rather than making users repeat fixed values.

File and Directory inputs

Keep File and Directory types in the CWL. The process interface represents them as string references. Supply references reachable from the execution environment; a path on the user's computer is not automatically available to a remote launcher.

Input-form annotations

Declare the JSON Schema namespace to add validation and presentation metadata:

$namespaces:
  js: https://json-schema.org/

The prefix can differ, but its namespace URI must match. Use prefixed attributes or a js:schema block on the input definition.

Numeric constraints

inputs:
  integer_input:
    label: Integer input
    type: int
    js:schema:
      minimum: 2
      maximum: 20

The UI renders numeric inputs with both bounds as sliders.

Dates and times

inputs:
  datetime_input:
    label: Date and time
    type: string
    js:format: date-time
  date_input:
    label: Date
    type: string
    js:schema:
      format: date
  time_input:
    label: Time
    type: string
    js:format: time

Array constraints

Put array and element constraints on the array type:

inputs:
  dates:
    label: Dates
    type:
      type: array
      items: string
      js:schema:
        maxItems: 5
        items:
          format: date

Records

inputs:
  coordinate:
    label: Geographic coordinate
    type:
      type: record
      fields:
        - name: latitude
          type: float
        - name: longitude
          type: float

OGC bounding boxes

Import the schema and reference its bounding-box type:

requirements:
  SchemaDefRequirement:
    types:
      - $import: https://raw.githubusercontent.com/eoap/schemas/0.2.0/ogc.yaml
inputs:
  bounding_box:
    label: Bounding box
    type: https://raw.githubusercontent.com/eoap/schemas/0.2.0/ogc.yaml#BBox

The schema must be retrievable during package validation and execution. Account for this dependency when targeting an offline environment.

Secret inputs

With Keycloak authentication, the cwltool:Secrets extension identifies string inputs whose values come from the user's vault.

When validating or testing this extension locally, enable it with cwltool's --enable-ext option.

$namespaces:
  cwltool: http://commonwl.org/cwltool#
hints:
  cwltool:Secrets:
    secrets: [api_key]
inputs:
  api_key:
    type: string

The execution form offers vault names for these inputs. An API execution request also supplies the vault alias, not the actual secret value; AntFlow resolves it for execution. Declare secrets on the consuming tools as well when needed by the runner's secret handling.

Users can manage their vault entries. A secret input does not require a GitLab CI/CD variable and is distinct from matching project-variable overrides.

Workflow code can disclose a secret

Do not print secrets, dump the environment, or include credentials in output files. The declaration alone does not prevent disclosure by your application.

Resource requirements

Declare resources on the tools that perform the processing:

class: CommandLineTool
requirements:
  ResourceRequirement:
    coresMin: 0.5
    coresMax: 1
    ramMin: 128
    ramMax: 256

CPU values are in cores and RAM values are in MiB. Maximums must not be smaller than the corresponding minimums. The runner and its deployment configuration determine how the allocation range is applied.

Dynamic requests

Tool inputs can provide resource values at execution time:

class: CommandLineTool
requirements:
  InlineJavascriptRequirement: {}
  ResourceRequirement:
    coresMin: $(inputs.cores)
    coresMax: $(inputs.cores)
    ramMin: $(inputs.ram)
    ramMax: $(inputs.ram)
inputs:
  cores:
    type: float
    default: 1
  ram:
    type: int
    default: 128

Expose and connect these tool inputs from the workflow if users need to set them in AntFlow's execution form.

Shared memory

The cwltool:ShmSize extension can increase /dev/shm for supported runners:

$namespaces:
  cwltool: http://commonwl.org/cwltool#
hints:
  cwltool:ShmSize:
    shmSize: 128m

Its effect depends on the runner and container configuration.

Execution flavors

AntFlow uses a FlavorInfo hint to restrict which launchers can run a workflow:

class: Workflow
hints:
  - class: FlavorInfo
    flavors: [gpu, high-memory]

A launcher must advertise all requested flavors. These labels do not allocate GPUs or memory by themselves. Coordinate the labels and infrastructure with your administrator; see Launcher capabilities.

Outputs

Declare output types and sources in the workflow. When STAC publication is enabled, workflow outputs become assets in the published results. Platform publication settings are described in Publish results to STAC.

For workflow-level publication properties and STAC metadata, see Results and publication.

Output names

AntFlow does not support @ in CWL workflow output names.

For portable runtime commands and image requirements, see Container portability.