summarize-cwl

---
type: research
title: "CWL workflow anatomy"
tags:
  - source/cwl
status: draft
created: 2026-05-10
revised: 2026-05-10
revision: 1
related_notes:
  - "[[summary-cwl]]"
  - "[[cwl-v1.2-schemas]]"
  - "[[galaxy-collection-semantics]]"
related_molds:
  - "[[summarize-cwl]]"
  - "[[cwl-summary-to-galaxy-interface]]"
  - "[[cwl-summary-to-galaxy-data-flow]]"
  - "[[cwl-summary-to-galaxy-template]]"
sources:
  - "https://www.commonwl.org/v1.2/Workflow.html"
  - "https://cwltool.readthedocs.io/en/stable/"
  - "https://github.com/common-workflow-language/cwl-utils#normalize-a-cwl-document"
  - "https://pypi.org/project/cwl-utils/"
  - "https://github.com/common-workflow-language/cwldep"
summary: "CWL structure relevant to summarize-cwl: normalized documents, steps, scatter, conditionals, requirements, and dependency handling."
---

# CWL Workflow Anatomy

CWL is a structured workflow language, not a pipeline framework that must be inferred from ecosystem conventions. The `summarize-cwl` Mold should therefore start from CWL's own validated object model and avoid recreating the heavy Nextflow extraction stack.

## Normalization Posture

Use `cwltool --validate` as the first gate. If validation fails, the summary should emit provenance plus validation diagnostics and stop before producing downstream-looking graph claims.

Use `cwl-normalizer` from `cwl-utils` as the default normalization surface. The cwl-utils README describes it as producing JSON CWL documents with dependencies packed together, upgrading to CWL v1.2 as needed, and optionally refactoring CWL expressions into separate steps. This is the right handoff for `summarize-cwl`: structured enough for extraction, still source-faithful, and not a Galaxy design.

Use `cwl-utils` for structured extraction when implementin
...

---
type: research
title: "CWL v1.2 schema documents"
tags:
  - source/cwl
status: draft
created: 2026-05-10
revised: 2026-05-10
revision: 1
related_notes:
  - "[[component-cwl-workflow-anatomy]]"
  - "[[summary-cwl]]"
related_molds:
  - "[[summarize-cwl]]"
companions:
  - "cwl-v1.2/cwl.yaml"
  - "cwl-v1.2/CommonWorkflowLanguage.yml"
  - "cwl-v1.2/Process.yml"
  - "cwl-v1.2/CommandLineTool.yml"
  - "cwl-v1.2/CommandLineTool-standalone.yml"
  - "cwl-v1.2/Workflow.yml"
  - "cwl-v1.2/Operation.yml"
sources:
  - "https://github.com/common-workflow-language/cwl-v1.2/tree/v1.2.1"
  - "https://www.commonwl.org/v1.2/Workflow.html"
summary: "Vendored official CWL v1.2.1 JSON/SALAD schema documents used as source-structure reference for CWL summarization."
---

# CWL v1.2 Schema Documents

Vendored from `common-workflow-language/cwl-v1.2` tag `v1.2.1`, pinned at SHA `ae6899d`. These files are reference material for [[summarize-cwl]] and [[component-cwl-workflow-anatomy]], not Mold IO schemas.

Vendored files under `cwl-v1.2/`, beside this note:

- `cwl.yaml` — generated JSON Schema for CWL v1.2.
- `CommonWorkflowLanguage.yml` — top-level SALAD schema imports.
- `Process.yml` — shared process, requirement, hint, and parameter definitions.
- `CommandLineTool.yml` — command-line tool schema.
- `CommandLineTool-standalone.yml` — standalone command-line tool import surface.
- `Workflow.yml` — workflow, step, scatter, link, and output-source schema.
- `Operation.yml` — abstract operation schema.

Re-sync:

```sh
pnpm sync:vendored
```

The vendored upstream manifest uses pinned raw GitHub URLs. Updating to a new CWL release should change the raw URLs and `pinned_ref` values together, then re-run `pnpm sync:vendored`.

## Foundry Role

Use these documents to check field names, enums, an
...

- $import: Process.yml
- $import: CommandLineTool.yml

saladVersion: v1.1
$base: "https://w3id.org/cwl/cwl#"

$namespaces:
  cwl: "https://w3id.org/cwl/cwl#"

$graph:

- name: CommandLineToolDoc
  type: documentation
  doc:
    - |
      # Common Workflow Language (CWL) Command Line Tool Description, v1.2

      This version:
        * https://w3id.org/cwl/v1.2/

      Latest stable version:
        * https://w3id.org/cwl/
    - "\n\n"
    - {$include: contrib.md}
    - "\n\n"
    - |
      # Abstract

      A Command Line Tool is a non-interactive executable program that reads
      some input, performs a computation, and terminates after producing some
      output.  Command line programs are a flexible unit of code sharing and
      reuse, unfortunately the syntax and input/output semantics among command
      line programs is extremely heterogeneous. A common layer for describing
      the syntax and semantics of programs can reduce this incidental
      complexity by providing a consistent way to connect programs together.
      This specification defines the Common Workflow Language (CWL) Command
      Line Tool Description, a vendor-neutral standard for describing the
      syntax and input/output semantics of command line programs.

    - {$include: intro.md}

    - |
      ## Introduction to the CWL Command Line Tool standard v1.2.1

      There are no new features nor behavior changes in CWL v1.2.1
      as compared to CWL v1.2.0. v1.2.1 fixes only typos, adds clarifications,
      and adds additional conformance tests. Some changes to the schema defining
      CWL are to aid the auto-generation of libraries for the reading and
      writing of CWL documents.

      Documents should continue to specify `cwlVersion: v1.2`. However, when
      reporting results from running the CWL conformance tests, please do repor
...

saladVersion: v1.1
$base: "https://w3id.org/cwl/cwl#"

$namespaces:
  cwl: "https://w3id.org/cwl/cwl#"
  sld: "https://w3id.org/cwl/salad#"

$graph:

- $import: Process.yml
- $import: CommandLineTool.yml
- $import: Workflow.yml

$schema: "http://json-schema.org/draft-07/schema#"
$author: "Francis Charette-Migneault <francis.charette.migneault@gmail.com>"
$id: "https://raw.githubusercontent.com/common-workflow-language/cwl-v1.2/1.2.1_proposed/json-schema/cwl.yaml"

$defs:
  CWL:
    oneOf:
      - $ref: '#/$defs/CWLAtomic'
      - $ref: '#/$defs/CWLGraph'
      - $ref: '#/$defs/CWLWorkflow'
  CWLKeywordList:
    type: array
    title: KeywordList
    description: Keywords applied to the process for search and categorization purposes.
    items:
      type: string
      title: keyword
      minLength: 1
  CWLTextPatternID:
    $comment: |
      Identifier with text pattern that can allow additional non-ASCII characters depending on regex implementation.
      The identifier allows a '#' or a relative 'sub/part#ref' prefix, to support references to other definitions
      in the CWL document, such as when using 'SchemaDefRequirement'.

      JSON spec regex does not include '\w' in its default subset to allow all word-like unicode characters
      (see reference: https://json-schema.org/understanding-json-schema/reference/regular_expressions.html).

      Since support is implementation specific, add both the ASCII-only and '\w' representation simultaneously
      and let the parser reading this document apply whichever is more relevant or supported
      (see discussion: https://github.com/common-workflow-language/cwl-v1.2/pull/256#discussion_r1234037814).
    # TODO: implement specific characters supported by CWL
    # (https://github.com/common-workflow-language/common-workflow-language/issues/429)
    pattern: '^([A-Za-z0-9\w]+(/[A-Za-z0-9\w]+)*)?[#.]?[A-Za-z0-9\w]+(?:[-_.][A-Za-z0-9\w]+)*$'
    type: string
    description: Generic identifier name pattern.
  CWLIdentifier:
    anyOf:
    - ty
...

saladVersion: v1.1
$base: "https://w3id.org/cwl/cwl#"

$namespaces:
  cwl: "https://w3id.org/cwl/cwl#"

$graph:

- name: OperationInputParameter
  type: record
  extends: InputParameter
  docParent: "#Operation"
  doc: |
    Describe an input parameter of an operation.
  fields:
    - name: type
      type:
        - CWLType
        - InputRecordSchema
        - InputEnumSchema
        - InputArraySchema
        - string
        - type: array
          items:
            - CWLType
            - InputRecordSchema
            - InputEnumSchema
            - InputArraySchema
            - string
      jsonldPredicate:
        "_id": "sld:type"
        "_type": "@vocab"
        refScope: 2
        typeDSL: True
      doc: |
        Specify valid types of data that may be assigned to this parameter.

- name: OperationOutputParameter
  type: record
  extends: OutputParameter
  docParent: "#Operation"
  doc: |
    Describe an output parameter of an operation.
  fields:
    - name: type
      type:
        - CWLType
        - OutputRecordSchema
        - OutputEnumSchema
        - OutputArraySchema
        - string
        - type: array
          items:
            - CWLType
            - OutputRecordSchema
            - OutputEnumSchema
            - OutputArraySchema
            - string
      jsonldPredicate:
        "_id": "sld:type"
        "_type": "@vocab"
        refScope: 2
        typeDSL: True
      doc: |
        Specify valid types of data that may be assigned to this parameter.

- type: record
  name: Operation
  extends: Process
  documentRoot: true
  specialize:
    - specializeFrom: InputParameter
      specializeTo: OperationInputParameter
    - specializeFrom: OutputParameter
      specializeTo: OperationOutputParameter
  doc: |
    This record describes an a
...

saladVersion: v1.1
$base: "https://w3id.org/cwl/cwl#"

$namespaces:
  cwl: "https://w3id.org/cwl/cwl#"
  sld: "https://w3id.org/cwl/salad#"
  rdfs: "http://www.w3.org/2000/01/rdf-schema#"

$graph:

- name: "Common Workflow Language, v1.2"
  type: documentation
  doc: {$include: concepts.md}

- $import: "salad/schema_salad/metaschema/metaschema_base.yml"

- name: BaseTypesDoc
  type: documentation
  doc: |
    ## Base types
  docChild:
    - "#CWLType"
    - "#Process"

- type: enum
  name: CWLVersion
  doc: "Version symbols for published CWL document versions."
  symbols:
    - cwl:draft-2
    - cwl:draft-3.dev1
    - cwl:draft-3.dev2
    - cwl:draft-3.dev3
    - cwl:draft-3.dev4
    - cwl:draft-3.dev5
    - cwl:draft-3
    - cwl:draft-4.dev1
    - cwl:draft-4.dev2
    - cwl:draft-4.dev3
    - cwl:v1.0.dev4
    - cwl:v1.0
    - cwl:v1.1.0-dev1   # a dash is required by the semver 2.0 rules
    - cwl:v1.1
    - cwl:v1.2.0-dev1
    - cwl:v1.2.0-dev2
    - cwl:v1.2.0-dev3
    - cwl:v1.2.0-dev4
    - cwl:v1.2.0-dev5
    - cwl:v1.2

- name: CWLType
  type: enum
  extends: "sld:PrimitiveType"
  symbols:
    - cwl:File
    - cwl:Directory
  doc:
    - "Extends primitive types with the concept of a file and directory as a builtin type."
    - "File: A File object"
    - "Directory: A Directory object"

- name: File
  type: record
  docParent: "#CWLType"
  doc: |
    Represents a file (or group of files when `secondaryFiles` is provided) that
    will be accessible by tools using standard POSIX file system call API such as
    open(2) and read(2).

    Files are represented as objects with `class` of `File`.  File objects have
    a number of properties that provide metadata about the file.

    The `location` property of a File is a IRI that uniquely identifies the
    file.  I
...

saladVersion: v1.1
$base: "https://w3id.org/cwl/cwl#"

$namespaces:
  cwl: "https://w3id.org/cwl/cwl#"
  rdfs: "http://www.w3.org/2000/01/rdf-schema#"

$graph:

- name: "WorkflowDoc"
  type: documentation
  doc:
    - |
      # Common Workflow Language (CWL) Workflow Description, v1.2

      This version:
        * https://w3id.org/cwl/v1.2/

      Latest stable version:
        * https://w3id.org/cwl/
    - "\n\n"
    - {$include: contrib.md}
    - "\n\n"
    - |
      # Abstract

      This specification defines the Common Workflow Language (CWL)
      Workflow description, a vendor-neutral standard for representing
      analysis tasks where a sequence of operations are described
      using a directed graph of operations to transform input to
      output.  CWL is portable across a variety of computing
      platforms.

    - {$include: intro.md}

    - |
      ## Introduction to the CWL Workflow standard v1.2.1

      There are no new features nor behavior changes in CWL v1.2.1
      as compared to CWL v1.2.0. v1.2.1 fixes only typos, adds clarifications,
      and adds additional conformance tests. Some changes to the schema defining
      CWL have been made to aid the auto-generation of libraries for the reading
      and writing of CWL documents.

      Documents should continue to specify `cwlVersion: v1.2`. However, when
      reporting results from running the CWL conformance tests, please do report
      all three components; for example "99% of CWL v1.2.0 required tests" or
      "100% of CWL v1.2.1 required tests".

      See also the [CommandLineTool v1.2.1 changelog](CommandLineTool.html#Changelog_for_v1.2.1)
      and the [Schema-Salad v1.2.1 changelog](SchemaSalad.html#Changelog_for_v1.2.1).

      ## Changelog for v1.2.1

      * CWL has been assigned
...