gxformat2 structural schema
The companion gxformat2.schema.json is a vendored Draft-07 JSON Schema generated from the @galaxy-tool-util/schema Effect-TS model at 7ae4ecd. Casting carries it with this note. Use it to inspect the structural vocabulary of a gxformat2 workflow, then check connections, tool references, and runtime behavior with gxwf and Galaxy validation. The schema does not establish that an outputSource exists or that a tool state is valid for its wrapper.
The schema is regenerated by pnpm sync:vendored --update, which builds the upstream package and runs gxwf structural-schema --format format2 before copying it here. Do not edit the companion by hand.
Root and input fields
The root requires class: GalaxyWorkflow, inputs, outputs, and steps. Those sections accept arrays or keyed maps. The root also permits id, label, doc, uuid, report, tags, comments, creator, license, and release.
Input entries describe the public workflow interface. The array form exposes these fields:
| Field | Structural schema | Meaning and use |
|---|---|---|
id, label, doc | Optional | Identify or describe the input. Check the effective imported name before using it as a test job: key. |
type | Optional string, string array, or null | Enum members are null, boolean, int, long, float, double, string, integer, text, File, data, and collection. This is accepted vocabulary, not a list of preferred authoring spellings. |
format | Optional string array or null | Galaxy datatype extension filter. See galaxy-datatypes-conf. |
collection_type | Optional string or null | Collection shape such as list:paired. The schema does not enumerate valid shapes. See galaxy-collection-semantics. |
optional, default | Optional boolean or null, and opaque value, respectively | Control whether an input can be omitted and what value is supplied when absent. See gxformat2-workflow-inputs for runtime behavior. |
position | Optional {top, left} numeric coordinates or null | Workflow editor placement. |
The generated schema does not include all fields accepted by current gxformat2 input handling, including restrictions, suggestions, and restrictOnConnections. gxformat2-workflow-inputs distinguishes that implementation behavior from what this vendored schema can check.
Output names and connections
An output entry can carry id, label, doc, outputSource, and type. outputSource names the producing step output, written step/output. The output’s public name is not always its label: normalized gxformat2 export places a native Galaxy workflow-output label in id, and the pinned IWC SRA manifest workflow exports id: paired_output. Current gxformat2 import chooses label when present and otherwise id. Check the effective name after import or conversion before writing the sibling test’s outputs: key. See galaxy-workflow-testability-design.
The schema makes outputSource optional, even though a usable produced output needs a valid source. Its string type cannot prove that the referenced step and port exist. gxformat2 lint checks the step reference. Workflow validation must also check that the producing port exists.
The step part of a source or outputSource depends on how the workflow lists its steps. In list form it is the step’s label when one is present, otherwise its id. In map form, for a step with no label, it is the map key.
A step’s in: key addresses a parameter nested in a conditional or section with a |-joined path, and a repeat instance with _N. For example, input_type|i wires an input inside a conditional in genome_annotation/functional-annotation/functional-annotation-of-sequences/Functional_annotation_of_sequences, and style_cond|type_cond|pick_from_0|value wires the first instance of a repeat inside two conditionals in conditional-route-between-alternative-outputs. The key names the path, and the conditional’s selector value stays in state. Each _N connection also needs its own entry in the repeat in state. The repeat creates the input terminal, so without the entry the connection does nothing and the job can still succeed.
Step out: entries serve a different purpose. They can be output names or records with id and actions such as rename, change_datatype, add_tags, remove_tags, hide, delete_intermediate_datasets, and set_columns. These actions affect produced datasets or history presentation. They do not supply a top-level output’s public name.
A rename value is not a tool-XML label template. Galaxy’s RenameDatasetAction fills in two forms. #{input} becomes the name of the dataset bound to that tool input. Use the tool’s input name, with . for a nested one (e.g. queries_0.input2), and optional | basename, | upper or | lower. ${label} becomes the value of the workflow parameter input with that label. Write #{gtf_to_extend} BREW3R extended to name an output after its input. A ${name} with no matching parameter input is an informal, untyped parameter (get_informal_replacement_parameters). The run form asks for a free-text value, and an API or Planemo run that supplies no replacement_params leaves ${name} literal in the dataset name. The tool-XML variables ${on_string} and ${tool.name} work only in a wrapper’s <data label=...>; in a rename they fall into this case. This is what the workflow linters report as an “untyped parameter”; declare a parameter input instead.
Step fields and state
The structural step type enum is tool, subworkflow, pause, and pick_value, with null also admitted. gxformat2’s source schema defaults an omitted type to tool. A step can also carry id, label, doc, position, tool_id, tool_shed_repository, tool_version, in, out, state, tool_state, run, runtime_inputs, when, errors, and uuid. The structural schema does not require subtype-specific fields such as tool_id on a tool step, so validation must continue beyond JSON Schema.
For hand-authored tool steps, use state for typed nested YAML, including conditionals and repeats. A converted workflow may contain tool_state, as the pinned IWC SRA manifest example does. Treat that as the representation received, not an authoring recommendation. Current import accepts tool_state as a map or JSON string, but gives state precedence if both fields are present. The structural schema permits both, so use only one on a step. Preserve an exported representation when reading or carrying it forward, and use state when authoring a new step.
What schema validation leaves open
The root and array-form entries constrain their listed properties, but generated map-form inputs and outputs each include a permissive object branch. Passing this schema therefore does not prove that every map entry has only documented fields. In map form, the type enum and format shape can also escape the documented constraints. Every form still needs semantic checks for connections and tool configuration.
The generated JSON also omits field descriptions and repeats $id: "/schemas/unknown" on opaque values. Some strict Ajv configurations reject those duplicate identifiers. If that occurs, compile with the project’s supported non-strict configuration or remove duplicate markers in a validation copy. Keep the vendored companion unchanged. The upstream gxformat2 source schema supplies field documentation that this generated artifact lacks.