Galaxy native workflow structural schema
Galaxy’s native .ga JSON represents workflow inputs as steps and connects steps through numeric identifiers. For new workflow authoring, use the gxformat2 YAML vocabulary in gxformat2-schema. gxwf convert translates between these representations.
The companion native-galaxy-workflow.schema.json is a vendored Draft-07 schema generated from @galaxy-tool-util/schema at 7ae4ecd. Casting carries it with this note. Foundry targets gxwf 1.13.1 or newer, but upgrading the CLI does not refresh this companion.
Read steps and connections
The root identifies a native workflow with a_galaxy_workflow: "true" and format-version: "0.1". Both values are strings. Its steps object contains step records keyed by identifiers.
The schema admits these step types:
Step type | Role |
|---|---|
data_input | Exposes a dataset input. |
data_collection_input | Exposes a collection input. See galaxy-collection-semantics. |
parameter_input | Exposes a scalar parameter input. |
tool | Runs the tool identified by tool_id and tool_version. |
subworkflow | Invokes a nested workflow. |
pause, pick_value | Represents a pause or value-selection step. |
A step’s input_connections maps its receiving input names to connections. Each connection requires a numeric upstream id and an output_name. A receiving input accepts one connection or an array. Inside a receiving step:
"input_connections": {
"input": {"id": 0, "output_name": "output"}
}This connects input input to step 0’s output port. The schema cannot establish that this step or port exists.
Step tool_state accepts a JSON string, an object, or null. Its contents need validation against the selected wrapper.
Step outputs describes output ports. Step workflow_outputs exposes selected ports as public results, with output_name identifying the port and label naming the result. post_job_actions records output actions separately.
Validate with the current tooling
Run gxwf validate on the actual workflow:
gxwf validate workflow.ga --jsonResolve reported errors before runtime testing. Tool-state checks need tool metadata. Validation does not establish that a representative Galaxy workflow test passes. See galaxy-workflow-testability-design.
The pinned companion has three limits that matter when interpreting it:
- It requires
class: NativeGalaxyWorkflowat the root and in nested workflows. Galaxy exports can omit that field. Current gxwf validation handles exports withoutclass, so a failure against this artifact alone does not establish a Galaxy import failure. - It makes
stepsoptional and requires no fields within a step. A structurally accepted record can still lack the tool identity, input configuration, or connections needed to run. - It omits field descriptions and repeats
$id: "/schemas/unknown"on opaque values. Ajv rejects these duplicate identifiers even withstrict: false, so that setting does not make the companion directly usable as an Ajv validator.
Keep the companion unchanged when investigating those limits. The structural schema generated by gxwf 1.13.1 still has the class and duplicate-identifier limits. Maintainers refresh vendored artifacts through pnpm sync:vendored --update, which builds the upstream package and runs gxwf structural-schema --format native before copying the result.