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, commonly step_id/output_id. 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.
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.
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.