{"id":8209,"library":"gxformat2","title":"Galaxy Workflow Format 2 Descriptions","description":"gxformat2 defines a high-level, human-readable, and human-writable workflow description format for Galaxy, known as Format 2. This package facilitates the creation, parsing, and conversion of Galaxy workflows, addressing the limitations of the older `.ga` format and moving towards compatibility with standards like the Common Workflow Language (CWL). It is actively developed and supports Galaxy versions 19.09 and newer, though the format is still somewhat experimental and may undergo minor backward-incompatible changes. The current version is 0.24.0, with a somewhat regular release cadence.","status":"active","version":"0.24.0","language":"en","source_language":"en","source_url":"https://github.com/galaxyproject/gxformat2","tags":["galaxy","workflow","bioinformatics","cwl","yaml","data science"],"install":[{"cmd":"pip install gxformat2","lang":"bash","label":"Install latest stable version"}],"dependencies":[],"imports":[{"note":"Used for loading Format 2 workflows from YAML files.","symbol":"parse_yaml_workflow","correct":"from gxformat2.yaml import parse_yaml_workflow"},{"note":"Used for converting a Format 2 workflow model to the native Galaxy .ga format.","symbol":"dump_format2_workflow_to_native","correct":"from gxformat2.converter import dump_format2_workflow_to_native"},{"note":"Converts a Python dictionary representation of a Format 2 workflow into a typed workflow model.","symbol":"python_to_workflow","correct":"from gxformat2.converter import python_to_workflow"}],"quickstart":{"code":"from gxformat2.yaml import parse_yaml_workflow\nfrom gxformat2.converter import dump_format2_workflow_to_native\nimport yaml\n\n# Example Format 2 Workflow content (minimal example)\nworkflow_content = '''\nclass: GalaxyWorkflow\ninputs:\n  - id: input_file\n    type: File\nsteps:\n  - id: cat_tool\n    tool_id: cat1\n    in:\n      input1: input_file\noutputs:\n  - id: output_file\n    outputSource: cat_tool/out_file\n'''\n\n# 1. Parse a Format 2 YAML workflow string\n# In a real scenario, you'd load this from a .gxwf.yml file\nworkflow_path = '/tmp/my_workflow.gxwf.yml'\nwith open(workflow_path, 'w') as f:\n    f.write(workflow_content)\n\ntry:\n    workflow_model = parse_yaml_workflow(workflow_path)\n    print(f\"Successfully parsed workflow: {workflow_model.label or workflow_model.id}\")\n\n    # 2. Convert the Format 2 workflow model to native Galaxy .ga format\n    native_workflow_dict = dump_format2_workflow_to_native(workflow_model)\n    print(\"\\nConverted to native Galaxy workflow (excerpt):\")\n    print(yaml.dump(native_workflow_dict, indent=2, default_flow_style=False)[:200] + '...') # Print first 200 chars\n\n    # You can access properties of the parsed model\n    print(f\"\\nNumber of steps: {len(workflow_model.steps)}\")\n    print(f\"First step tool_id: {workflow_model.steps[0].tool_id}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n","lang":"python","description":"This quickstart demonstrates how to parse a Format 2 workflow from a YAML string into a Python object using `parse_yaml_workflow`, and then convert it to the native Galaxy `.ga` format using `dump_format2_workflow_to_native`. It also shows how to access basic properties of the parsed workflow model."},"warnings":[{"fix":"Stay updated with releases, consult the official documentation, and test workflows after upgrading the library or Galaxy.","message":"The Format 2 workflow description is still considered somewhat experimental. It may undergo small, potentially backward-incompatible changes, particularly until it is exported by Galaxy as the default format. Users should regularly review changelogs for updates.","severity":"gotcha","affected_versions":"All versions up to 0.24.0"},{"fix":"Ensure your environment uses Python 3.9 or newer. Upgrade your Python interpreter if necessary.","message":"Support for Python 3.5 was dropped, and Python 3.9 was added as the minimum required version in `gxformat2` v0.16.0.","severity":"breaking","affected_versions":"< 0.16.0 to >= 0.16.0"},{"fix":"Always use `label: Your Workflow Name` for workflow definitions in Format 2 YAML files to ensure proper validation.","message":"When defining workflows, use the `label` field instead of `name` for workflow validation against the schema. While Galaxy may still process `name` for legacy reasons, `label` is the correct attribute for adherence to the Format 2 schema.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Monitor future `gxformat2` releases for the official switch. When `ConversionOptions` is introduced, migrate any usage of `ImportOptions` to the new class.","message":"The `ImportOptions` class is being replaced by `ConversionOptions` for conversion and expansion layers, as part of an architectural refactor. Using `ImportOptions` might become deprecated or removed in future versions.","severity":"deprecated","affected_versions":"Future versions beyond 0.24.0 (as per recent GitHub discussions)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Check your `.gxwf.yml` file for proper indentation, colon usage, and valid YAML structure. Tools like `gxwf-lint` or VSCode extensions for YAML can help identify syntax errors.","cause":"Incorrect YAML syntax in the workflow definition file.","error":"YAMLError: while parsing a block mapping"},{"fix":"Consult the Format 2 schema documentation (available on the `gxformat2` GitHub repository) to ensure all required fields are present and correctly formatted for workflow inputs, steps, and outputs.","cause":"The workflow definition is missing a required field, or a field has an incorrect type/value, failing schema validation.","error":"ValidationError: 'tool_id' is a required field"},{"fix":"Install the library using `pip install gxformat2`.","cause":"The `gxformat2` library is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'gxformat2'"},{"fix":"Upgrade your Python interpreter to version 3.9 or newer. You might need to create a new virtual environment with a compatible Python version.","cause":"Attempting to run `gxformat2` with an unsupported Python version (older than 3.9).","error":"RuntimeError: Requires Python >= 3.9"}]}