Galaxy Native Workflow Format (.ga) §

The Galaxy native workflow format is a JSON document (conventionally with `.ga`` extension) that fully describes a workflow's structure, tools, connections, metadata, and visual layout. It is the canonical serialization format used internally by Galaxy.

NativeGalaxyWorkflow §

A Galaxy native workflow document (.ga format). This is the canonical serialization format used internally by Galaxy.

The native format mirrors the database schema directly -- steps are keyed by numeric IDs, connections reference step IDs, and tool state is stored as double-encoded JSON strings.

The format version has been "0.1" since inception. New features are added without version bumps.

Fields

field
required
type
description
a_galaxy_workflow
required
string

Format marker. Always the string "true".

format-version
required
string

Format version. Always "0.1" currently. In the JSON document this field is written as format-version.

uuid
optional
string

UUID uniquely representing this element.

name
optional
string

Workflow display name.

annotation
optional
string

Human-readable workflow description.

tags
optional
array<string>

Classification tags for the workflow.

version
optional
int

Internal revision counter.

license
optional
string

SPDX license identifier (e.g. "MIT", "CC-BY-4.0").

release
optional
string

Semantic version for published workflows.

creator
optional
list[NativeCreatorPerson | NativeCreatorOrganization] | None

Creator(s) of this workflow. An array of schema.org NativeCreatorPerson or NativeCreatorOrganization objects, dispatched via the class field (Person or Organization).

report
optional
NativeReport

Workflow invocation report template.

readme
optional
string

Detailed workflow description in Markdown.

help
optional
string

Help text in Markdown.

logo_url
optional
string

URL to workflow logo image.

doi
optional
array<string>

Associated DOIs.

source_metadata
optional
NativeSourceMetadata

Provenance tracking metadata for workflows imported from TRS or URLs.

comments
optional
array<NativeComment>

Visual annotations in the workflow editor.

steps
optional
dict[str, NativeStep] | None

Step dictionary keyed by string integers ("0", "1", ...). Values are NativeStep objects. Steps are processed in sorted numeric order during import.

subworkflows
optional
dict[str, NativeGalaxyWorkflow] | None

Map of locally-defined subworkflow dicts, used during format conversion.

NativeTextComment §

A plain text annotation in the workflow editor.

Fields

field
required
type
description
id
required
int

Numeric identifier for this comment (order index).

type
required
string

Comment type (text).

position
optional
list[float] | None

Position on the editor canvas as [x, y] coordinates.

size
optional
list[float] | None

Size as [width, height].

color
optional
string

Display color (e.g. "none", "blue").

data
optional
NativeTextCommentData

Text content data: text, bold, italic, size.

Any §

The Any type validates for any non-null value.

Symbols

symboldescription
Any

NativeTextCommentData §

Data payload for a text comment.

Fields

field
required
type
description
text
optional
string

The text content.

bold
optional
boolean

Whether the text is displayed in bold.

italic
optional
boolean

Whether the text is displayed in italic.

size
optional
float | int

Font size of the text.

NativeMarkdownComment §

A Markdown-rendered annotation in the workflow editor.

Fields

field
required
type
description
id
required
int

Numeric identifier for this comment (order index).

type
required
string

Comment type (markdown).

position
optional
list[float] | None

Position on the editor canvas as [x, y] coordinates.

size
optional
list[float] | None

Size as [width, height].

color
optional
string

Display color (e.g. "none", "blue").

data
optional
NativeMarkdownCommentData

Markdown content data: text.

NativeMarkdownCommentData §

Data payload for a markdown comment.

Fields

field
required
type
description
text
optional
string

Markdown content.

NativeFrameComment §

A rectangular grouping box that visually contains steps and other comments.

Fields

field
required
type
description
id
required
int

Numeric identifier for this comment (order index).

type
required
string

Comment type (frame).

position
optional
list[float] | None

Position on the editor canvas as [x, y] coordinates.

size
optional
list[float] | None

Size as [width, height].

color
optional
string

Display color (e.g. "none", "blue").

data
optional
NativeFrameCommentData

Frame content data: title.

child_steps
optional
array<int>

Step IDs contained within this frame.

child_comments
optional
array<int>

Comment IDs contained within this frame.

NativeFrameCommentData §

Data payload for a frame comment.

Fields

field
required
type
description
title
optional
string

Title displayed on the frame header.

NativeFreehandComment §

A freehand drawn line on the editor canvas.

Fields

field
required
type
description
id
required
int

Numeric identifier for this comment (order index).

type
required
string

Comment type (freehand).

position
optional
list[float] | None

Position on the editor canvas as [x, y] coordinates.

size
optional
list[float] | None

Size as [width, height].

color
optional
string

Display color (e.g. "none", "blue").

data
optional
NativeFreehandCommentData

Freehand content data: line, thickness.

NativeFreehandCommentData §

Data payload for a freehand comment.

Fields

field
required
type
description
line
optional
list[list[float]] | None

Array of [x, y] coordinate pairs defining the freehand line path.

thickness
optional
float | int

Line thickness.

NativeComment §

A visual annotation in the workflow editor. Dispatches to the appropriate comment type based on the type field.

NativeStep §

A step in a native Galaxy workflow. Steps are keyed by string integers ("0", "1", ...) in the steps dictionary. The key serves as an external ID for connection wiring.

The type field determines the step's behavior. All step types share common fields; type-specific fields are optional and only relevant for their respective type.

Tool State §

The tool_state field contains the tool's parameter configuration. Traditionally this is a JSON-encoded string (double-encoded: each top-level value is itself a JSON string), but it may also be a plain dictionary when unencoded tool state is used. Connected parameters are represented as {"__class__": "ConnectedValue"}, runtime parameters as {"__class__": "RuntimeValue"}.

Fields

field
required
type
description
errors
optional
string

During Galaxy export there may be some problem validating the tool state, tool used, etc.. that will be indicated by this field. The Galaxy user should be warned of these problems before the workflow can be used in Galaxy.

This field should not be used in human written Galaxy workflow files.

A typical problem is the referenced tool is not installed, this can be fixed by installed the tool and re-saving the workflow and then re-exporting it.

position
optional
StepPosition
uuid
optional
string

UUID uniquely representing this element.

tool_id
optional
string

The tool ID used to run this step of the workflow (e.g. 'cat1' or 'toolshed.g2.bx.psu.edu/repos/nml/collapse_collections/collapse_dataset/4.0').

tool_shed_repository
optional
ToolShedRepository

The Galaxy Tool Shed repository that should be installed in order to use this tool.

tool_version
optional
string

The tool version corresponding used to run this step of the workflow. For tool shed installed tools, the ID generally uniquely specifies a version and this field is optional.

id
optional
int

Step ID. Matches the dictionary key in the steps object.

type
optional
NativeStepType

Step module type.

name
optional
string

Display name. For tool steps this is the tool's name; for input steps it is the generic type name (e.g. "Input dataset").

label
optional
string

User-friendly step label. Must be unique within the workflow.

annotation
optional
string

Human-readable step description.

when
optional
string

Conditional execution expression. Typically $(inputs.when) paired with a boolean input connection on the when key.

content_id
optional
string

Tool ID or content identifier. Same as tool_id for tool steps; may reference a subworkflow key for subworkflow steps.

tool_state
optional
string | str | dict[str, Any] | None

Tool parameter configuration. Traditionally a JSON-encoded string (double-encoded: each top-level value is itself a JSON string), but may also be a plain dict when encode_tool_state is disabled during Format2-to-native conversion.

tool_uuid
optional
string

UUID for dynamic (inline-defined) tools.

input_connections
optional
dict[str, NativeInputConnection | list[NativeInputConnection]] | None

Connection wiring from other steps' outputs to this step's inputs. Keys are input parameter names (using | for nested parameters). Values are a NativeInputConnection object or an array of them for multi-valued inputs.

inputs
optional
array<NativeStepInput>

Input parameter metadata (descriptions, not connections).

outputs
optional
array<NativeStepOutput>

Output declarations with names and datatypes.

workflow_outputs
optional
array<NativeWorkflowOutput>

Outputs designated as workflow-level outputs. Steps with an empty array have all their outputs hidden by default.

post_job_actions
optional
dict[str, NativePostJobAction] | None

Post-job actions applied to outputs after tool execution. Keys are compound strings of the form {ActionType}{OutputName}. Values are NativePostJobAction objects.

subworkflow
optional
NativeGalaxyWorkflow | None

Embedded subworkflow definition. A complete native workflow document (with a_galaxy_workflow, format-version, steps, etc.) nested inside this step.

tool_representation
optional
dict[str, Any] | None

Embedded tool definition for user-defined (dynamic) tools. Present when the step uses a GalaxyUserTool instead of a registered tool. Contains the full tool definition including class: GalaxyUserTool, name, command, inputs, and outputs. When present, tool_id and tool_uuid are typically null.

in
optional
dict[str, Any] | None

Default values for step inputs. Keys are parameter names, values are objects with a default key.

NativeStepInput §

Describes an input parameter on a step. This is metadata about the input, not the connection wiring (which is in input_connections).

Fields

field
required
type
description
name
required
string

Name of the input parameter.

description
optional
string

Human-readable description of this input.

NativeStepOutput §

Declares an output produced by a step, with its name and datatype.

Fields

field
required
type
description
name
required
string

Name of the output.

type
optional
string

Galaxy datatype extension for the output (e.g. bam, txt, tabular). The value input means the type is determined at runtime from the input data.

NativeWorkflowOutput §

Designates a step output as a workflow-level output. These appear in the workflow_outputs array on each step.

Fields

field
required
type
description
output_name
required
string

Name of the step output to expose as a workflow output.

label
optional
string

User-visible label for this workflow output. Must be unique across the workflow.

uuid
optional
string

UUID for this workflow output.

NativeInputConnection §

Describes a connection from one step's output to another step's input. These objects appear as values in the input_connections dictionary.

For multi-valued inputs, the value is an array of these objects rather than a single object.

Fields

field
required
type
description
id
required
int

Step ID of the source step providing the data.

output_name
required
string

Name of the output on the source step (typically "output" for input steps).

input_subworkflow_step_id
optional
int

For subworkflow steps, the internal step ID within the subworkflow that this connection routes to. Maps the parent connection to the correct input step inside the subworkflow.

NativePostJobAction §

An action applied to a step's output after tool execution. These objects appear as values in the post_job_actions dictionary, keyed by compound strings of the form {ActionType}{OutputName} (e.g. HideDatasetActionout_pairs).

Common action types: HideDatasetAction, RenameDatasetAction, DeleteIntermediatesAction, ChangeDatatypeAction, TagDatasetAction, ColumnSetAction.

Fields

field
required
type
description
action_type
required
string

The action type identifier (e.g. HideDatasetAction).

output_name
required
string | null

The step output this action applies to. Optional: action types that operate on the step as a whole (e.g. ValidateOutputsAction) omit this field.

action_arguments
optional
dict[str, Any] | None

Action-specific arguments. For RenameDatasetAction: {"newname": "..."}; for ChangeDatatypeAction: {"newtype": "tabular"}; for TagDatasetAction: {"tags": "name:tag"}. Empty object {} for actions without arguments.

StepPosition §

This field specifies the location of the step's node when rendered in the workflow editor.

Fields

field
required
type
description
top
required
float | int

Relative vertical position of the step's node when rendered in the workflow editor.

left
required
float | int

Relative horizontal position of the step's node when rendered in the workflow editor.

ToolShedRepository §

Fields

field
required
type
description
changeset_revision
required
string

The revision of the tool shed repository this tool can be found in.

name
required
string

The name of the tool shed repository this tool can be found in.

owner
required
string

The owner of the tool shed repository this tool can be found in.

tool_shed
required
string

The URI of the tool shed containing the repository this tool can be found in - typically this should be toolshed.g2.bx.psu.edu.

NativeStepType §

Step module types in the native Galaxy workflow format.

Symbols

symboldescription
data_input A single dataset input to the workflow.
data_collection_input A dataset collection input to the workflow.
parameter_input A typed parameter input (text, integer, float, boolean, color).
tool A Galaxy tool execution step.
subworkflow An embedded or referenced sub-workflow.
pause A manual pause point that halts execution until user intervention.
pick_value Select the first non-null value from multiple inputs.

NativeReport §

Workflow invocation report template.

Fields

field
required
type
description
markdown
required
string

Galaxy-flavored Markdown content for the invocation report. Supports template directives like history_dataset_as_image(output="...").

NativeCreatorPerson §

A person who created or contributed to the workflow. Corresponds to a schema.org Person <https://schema.org/Person>_.

Fields

field
required
type
description
class
required
NativeCreatorPersonType

Creator type discriminator (Person).

name
optional
string

Full name of the person or organization.

identifier
optional
string

Persistent identifier, typically an ORCID URL (e.g. https://orcid.org/0000-0001-2345-6789) or bare ORCID.

url
optional
string

Website or profile URL.

email
optional
string

Email address. May include a mailto: prefix.

image
optional
string

URL to an image or avatar.

address
optional
string

Physical or mailing address.

alternateName
optional
string

An alternate name or alias.

telephone
optional
string

Telephone number.

faxNumber
optional
string

Fax number.

givenName
optional
string

Given (first) name.

familyName
optional
string

Family (last) name.

honorificPrefix
optional
string

Honorific prefix (e.g. Dr, Prof).

honorificSuffix
optional
string

Honorific suffix (e.g. M.D., PhD).

jobTitle
optional
string

Job title or role.

NativeCreatorPersonType §

Discriminator for schema.org Person creators.

Symbols

symboldescription
Person

NativeCreatorOrganization §

An organization that created or contributed to the workflow. Corresponds to a schema.org Organization <https://schema.org/Organization>_.

Fields

field
required
type
description
class
required
NativeCreatorOrganizationType

Creator type discriminator (Organization).

name
optional
string

Full name of the person or organization.

identifier
optional
string

Persistent identifier, typically an ORCID URL (e.g. https://orcid.org/0000-0001-2345-6789) or bare ORCID.

url
optional
string

Website or profile URL.

email
optional
string

Email address. May include a mailto: prefix.

image
optional
string

URL to an image or avatar.

address
optional
string

Physical or mailing address.

alternateName
optional
string

An alternate name or alias.

telephone
optional
string

Telephone number.

faxNumber
optional
string

Fax number.

NativeCreatorOrganizationType §

Discriminator for schema.org Organization creators.

Symbols

symboldescription
Organization

NativeCreator §

A workflow creator, either a person or organization. Dispatched via the class field (Person or Organization).

NativeSourceMetadata §

Provenance tracking for workflows imported from external sources. Contains either a direct URL or TRS (Tool Registry Service) metadata, depending on how the workflow was imported.

For URL imports, only url is set. For TRS imports (Dockstore, WorkflowHub), trs_tool_id, trs_version_id, and trs_url are set, with trs_server optionally identifying the server.

Fields

field
required
type
description
url
optional
string

URL from which the workflow was directly imported.

trs_tool_id
optional
string

Tool identifier in the Tool Registry Service (e.g. "#workflow/github.com/user/repo/workflow" or "109").

trs_version_id
optional
string

Version identifier in the TRS (e.g. "master", "5").

trs_server
optional
string

TRS server name (e.g. "dockstore", "workflowhub"). Optional even for TRS imports.

trs_url
optional
string

Complete TRS API endpoint URL for this workflow version.