nf-schema sample sheet validation gaps in Galaxy

Use this note when nextflow-summary-to-galaxy-interface casts a Nextflow sample-sheet input to a Galaxy sample_sheet* collection input. It enumerates which nf-schema validation features survive, which degrade, and which are wholly lost; flags concrete Galaxy code paths to extend; and gives the cast Mold a vocabulary for recording validation losses.

Evidence quality:

• Corpus-observed (CO) — pinned fixtures under workflow-fixtures/pipelines/.
• Galaxy source (GS) — file paths in lib/galaxy/... from the dev branch.
• gxformat2 source (FS) — gxformat2/....
• External-doc (ED) — nf-schema spec + nf-core component docs.
• Design inference (DI) — clearly marked.

TL;DR

• nf-schema sample sheets carry four classes of constraint: per-cell type/pattern, per-cell path semantics (format, exists, mimetype), per-row dependent-requiredness (dependentRequired, anyOf), and cross-row uniqueness (uniqueEntries). Galaxy column_definitions natively covers only the first class, partially covers pattern/enum, and has zero expression for the per-row and cross-row classes.
• Galaxy’s safe-validator allowlist is exactly three: regex, in_range, length (GS lib/galaxy/tool_util_models/parameter_validators.py:469-476). Anything richer (file existence, mimetype, conditional required, uniqueness) cannot be encoded — must downgrade to prose, drop, or promote out of the sample sheet.
• The [\w\-_ ?]* charset gate (GS lib/galaxy/model/dataset_collections/types/sample_sheet_util.py:117) silently rejects column values containing ;, ., :, ,, /, etc. Concrete blocker found in corpus: nf-core/taxprofiler db_type default "short;long" cannot be stored.
• Dataset-typed columns are validated only for presence and element-identifier shape — Galaxy does not sniff the dataset against a format, does not check exists, does not enforce a path regex against the dataset’s filename. Datatype filtering happens at upload, not at sample-sheet construction.
• gxformat2 has no formal column_definitions declaration in schema/v19_09/workflow.yml. Column metadata round-trips as additional state via FS gxformat2/normalized/_conversion.py:524-540. Adding strong validator support will likely require a gxformat2 schema rev and a Galaxy state-persistence rev.

nf-schema validation feature inventory

Per-cell (column-property) features

Per-row features

Cross-row features

Identifier / non-validation keywords

Params vs samplesheet vocabulary

ED docs/nextflow_schema/sample_sheet_schema_specification.md: most keys are shared. Divergences:

• meta is samplesheet-only.
• uniqueEntries is samplesheet-only.
• hidden, fa_icon, help_text are mostly params-only.

samplesheetToList(file, schema) materializes the sheet as a list of [meta_map, data_field_1, ...] tuples (ED). Schema property order, not CSV column order, is the source of truth for tuple order. Meta-annotated columns collapse into the leading map.

Galaxy column_definitions capability inventory

Column definition vocabulary

SampleSheetColumnDefinition (GS lib/galaxy/tool_util_models/sample_sheet.py:39-47):

Allowed validators

GS lib/galaxy/tool_util_models/parameter_validators.py:469-476 — three discriminated subclasses tagged _safe = True:

expression (Python eval) and all dataset-aware validators (metadata, dataset_metadata_in_data_table, dataset_ok, empty_dataset, …) are excluded (_safe: False or absent).

What is enforced and where

Variant-specific differences

Per galaxy-sample-sheet-collections, all four variants (sample_sheet, sample_sheet:paired, sample_sheet:paired_or_unpaired, sample_sheet:record) share column_definitions semantics. Variant axis controls element shape, not column validation. Practical consequence: a paired-end nf-core sheet with one R1 path and an optional R2 path becomes sample_sheet:paired or sample_sheet:paired_or_unpaired — the path columns vanish from column_definitions because they become the dataset payload, leaving only metadata columns.

Round-trip through gxformat2

• gxformat2 → Galaxy: import accepts column_definitions on data_collection inputs as additional state. gxformat2 v19_09 (FS schema/v19_09/workflow.yml) has no column_definitions field declaration. Field passes through FS gxformat2/normalized/_conversion.py:524-540.
• Galaxy → gxformat2 export: same code path round-trips it. No silent drop observed for the in-allowlist subset.
• DI: because gxformat2 has no schema-level declaration, additions like new validator types could in principle round-trip without a schema rev, but tooling that strict-validates against the SALAD schema (gxwf, IDE) will not understand them.
• Existing example: gxformat2/examples/format2/synthetic-sample-sheet-input.gxwf.yml — only uses restrictions, name, default_value, optional.

Gap matrix

Support: N=Native, P=Partial, L=Lossy, A=Absent. Loss observable: cast / import / invocation / runtime. Foundry recommendation: preserve / record / promote / drop / refuse.

Worked examples

nf-core/rnaseq assets/schema_input.json

Variant: sample_sheet:paired_or_unpaired (R2 optional, plus optional alt bam columns).

Items-level constraints: none — no cross-row losses for rnaseq.

nf-core/sarek assets/schema_input.json

Richest case in the corpus.

Items-level (the meat of the gap):

• dependentRequired: {fastq_2: [fastq_1], spring_2: [spring_1]} — A. paired_or_unpaired makes R2-without-R1 unrepresentable; spring_2-without-spring_1 would still be possible if both columns existed. Record loss_class: dependentRequired_partially_structural.
• anyOf: [{dependentRequired: {lane: [fastq_1]}}, {lane: [spring_1]}, {lane: [bam]}] — A. Encodes “lane requires one of the data branches.” Mitigation: a top-level scalar data_source: fastq|spring|bam enum input plus three sample-sheet inputs (gated by docs). Record loss_class: discriminated_union_required.
• required: ["patient","sample"] — N.
• uniqueEntries: ["lane","patient","sample"] — A. Composite key. Record loss_class: cross_row_unique_composite.

nf-core/taxprofiler assets/schema_database.json

Reference/database sheet — typically a separate Galaxy input from the biological samplesheet (see nextflow-params-to-galaxy-inputs §Reference data).

Items-level: uniqueEntries: ["tool","db_name"] — A. Record loss.

The db_type finding is the highest-impact concrete blocker discovered: a literal nf-core enum value cannot be stored in a Galaxy column_definition cell. It must be rewritten (short_long), promoted to a separate scalar, or the gate loosened (Galaxy work item W1 below).

Galaxy implementation roadmap

Prioritized by frequency-of-bite across the 8 nf-core fixtures.

W1. Loosen sample-sheet column-value charset to allow nf-core-canonical values

Problem. has_special_characters (GS lib/galaxy/model/dataset_collections/types/sample_sheet_util.py:116-119) rejects column values matching anything outside [\w\-_ ?]*. nf-core enums and free-text routinely contain ;, ., ,, :, /, =, ', ". Concrete blocker: db_type: "short;long" (taxprofiler default).

Fix shape. Distinguish three charset gates:

1. column name (current strict gate — keep, serializes into TSV header).
2. element_identifier value (must serialize cleanly into TSV — keep current gate).
3. arbitrary cell value (relax to “no control characters, no embedded newline/tab; CSV-escapable”) — strip_control_characters plus a CSV-escapability check, not the current word-boundary regex.

Touch points:

• GS lib/galaxy/model/dataset_collections/types/sample_sheet_util.py:116-129,155-162 — split validate_no_special_characters into validate_identifier_charset and validate_value_charset; only call the strict one for element_identifier.
• GS lib/galaxy/tools/sample_sheet_to_tabular.xml — verify TSV escapes \t, \n correctly (introduce CSV-mode or quote rule).

Risk. Medium. Touches collection-build-time validation and downstream TSV writers.

Size. S–M. gxformat2 rev? No. Existing PRs. None found; Galaxy issue #20831 (Sample Sheets follow-up) is the umbrella.

W2. Add unique column-level flag and unique_entries items-level flag

Problem. Cross-row uniqueness is the second-most-common nf-core constraint. sarek ["lane","patient","sample"], taxprofiler-input ["fastq_1"]/["fastq_2"]/["fasta"]/["sample","run_accession"], taxprofiler-database ["tool","db_name"].

Fix shape.

• Single-column unique: extend SampleSheetColumnDefinition with unique: bool = False (GS lib/galaxy/tool_util_models/sample_sheet.py).
• Composite unique: add a top-level unique_entries: List[List[str]] to the collection’s column_definitions envelope (currently flat list — wrap as {"columns": [...], "unique_entries": [...]} or attach a sibling JSON column on dataset_collection). The wrapper option is more future-proof.
• Validation: in validate_row only the current row is visible; cross-row check runs after all rows are collected. Plug into SampleSheetDatasetCollectionType.generate_elements (GS types/sample_sheet.py:18-40) — accumulate seen tuples, raise on duplicate.
• Workbook parser (GS types/sample_sheet_workbook.py) needs the same check at upload.

Risk. Medium — schema migration touches dataset_collection.column_definitions shape; backwards compat required (accept both list and {columns, unique_entries} envelope).

Size. M. gxformat2 rev? Yes for typed authoring tools.

W3. Express conditional / dependent required at the column-definitions level

Problem. Sarek’s dependentRequired and anyOf-of-dependentRequired are routine; without them the cast Mold either over-promotes columns to required (creating impossible workflows) or under-promotes (silent runtime errors).

Fix shape. Two options.

• (a) Rule-based — add requires: [column_name] on a column for dependentRequired. Validate in validate_row. Covers sarek’s R2→R1 and spring2→spring1.
• (b) Discriminator-based — add envelope-level discriminator: {column: "data_source", branches: {fastq: [fastq_1], spring: [spring_1], bam: [bam]}}. Covers sarek’s anyOf-of-dependentRequired. Closer to JSON-Schema’s oneOf but constrained to a single discriminator column, which is the only shape nf-core uses.

Touch points:

• GS lib/galaxy/tool_util_models/sample_sheet.py — extend model.
• GS lib/galaxy/model/dataset_collections/types/sample_sheet_util.py:97-113 — extend validate_row.
• GS lib/galaxy/tools/parameters/basic.py:2585-2588 (column_definitions_compatible) — decide whether dependent-required participates in compatibility.

Risk. Medium-high. Affects compatibility matching, which gates editor-time wiring.

Size. M. gxformat2 rev? Yes. Existing PRs. None found.

W4. Add a path column type with optional datatype enforcement

Problem. nf-schema format: file-path columns become Galaxy datasets, but the path-pattern regex (^\S+\.bam$ etc.) is lost.

Fix shape.

• (a, smaller) For path-bearing columns, record a format (Galaxy datatype) hint on column_definitions; have DataCollectionToolParameter filter compatible collections by it (GS tools/parameters/basic.py:2585-2588). Piggybacks on existing Galaxy datatype machinery.
• (b, larger) Promote nf-schema pattern on path columns to a Galaxy datatype lookup at cast time and assert at upload — out of scope for Galaxy; cast Mold concern via nextflow-path-glob-to-galaxy-datatype.

Risk. Low for (a). Size. S. gxformat2 rev? Optional.

W5. Carry errorMessage and description end-to-end

Problem. nf-core authors write errorMessage on every column. Galaxy’s only landing slot is column_definition.description; safe-allowlist validators don’t accept user-supplied messages — regex/in_range/length models have no message field (GS parameter_validators.py:160-245).

Fix shape. Add message: Optional[str] to RegexParameterValidatorModel, InRangeParameterValidatorModel, LengthParameterValidatorModel. Plumb through default_message override.

Risk. Low. Size. S. gxformat2 rev? No.

W6. Distinguish “directory” vs “file” path columns

Problem. nf-schema format: directory-path and format: path (file-or-dir). Galaxy has no directory dataset. taxprofiler db_path is the routine case.

Fix shape. No Galaxy code change recommended now — cast-time refusal and documented loss. Galaxy roadmap item only if directory support arrives via something like CWL Directory inputs.

W7. Aggregate-row error reporting

Problem. validate_row short-circuits on first failure (GS sample_sheet_util.py:104-112). Users uploading a 200-row sheet get one error at a time. nf-schema reports all errors per row.

Fix shape. Collect errors into a list; raise a single RequestParameterInvalidException with structured payload (row index → field → message).

Risk. Low (backward compatible if message text preserved). Size. S.

Priority summary

Cast Mold loss-recording guidance

Cast Mold should write a per-column entry into the interface brief whenever an nf-schema feature is mapped to Galaxy column_definitions. Record shape:

column_loss_records:
  - source_column: db_type
    nf_schema_features:
      type: string
      enum: ["short", "long", "short;long"]
      default: "short;long"
      meta: ["db_type"]
    galaxy_column_definition:
      name: db_type
      type: string
      restrictions: ["short", "long", "short;long"]
      default_value: "short;long"
      optional: true
    loss_class: galaxy_value_charset_overrestrictive
    loss_severity: blocking
    mitigation: rename canonical value "short;long" to "short_long" and remap upstream; record CLI mismatch

loss_class enum

loss_severity enum

Refuse vs map-and-warn

Refuse mapping (push back to interface brief as a question) when:

• A format: directory-path column is required.
• A format: file-path-pattern column would be the dataset payload.
• A discriminated anyOf-of-dependentRequired cannot be modeled by a single sample-sheet variant.
• Column value charset is fundamentally incompatible (e.g. nf-schema enum value contains ;).
• The sheet uses a nested schema: reference to validate a per-row file (a sheet of sheets).

Map-and-warn (record loss, proceed) when:

• multipleOf, exclusive*, minLength/maxLength.
• pattern (regex anchoring caveat).
• errorMessage, description, help_text (cosmetic until W5).
• uniqueEntries (record behavioral; user discipline).
• dependentRequired already structurally satisfied by the variant.

Open questions

• gxformat2 schema authority for column_definitions. Today round-trips as additional state. Should W2/W3 trigger a real v19_09 rev plus IDE bindings, or remain in additional state? Punt: small-rev once W2 lands.
• column_definitions_compatible (GS sample_sheet_util.py:177-212) compares only name + type. Should validators participate in compatibility? Tightening would break editor wiring of legacy sample sheets.
• RegexParameterValidatorModel uses regex.match, not fullmatch — should the sample-sheet caller force fullmatch semantics by appending $? Cast Mold could do this transparently and record under regex_anchor_drift.
• nf-schema meta mapping: is every meta-marked column promoted to element_identifier, or only meta: id? Convention is meta: ["id"] for primary key, others as ordinary metadata. Confirm with sarek (six meta columns).
• For sample sheets that mix multiple “branches” (sarek: fastq vs spring vs bam vs cram vs vcf), should the cast Mold always split into multiple Galaxy inputs gated by a scalar mode, or attempt sample_sheet:record? Likely a per-pipeline interface decision.
• Should W3’s “discriminator” be added as gxformat2 schema or as a Galaxy-only extension? Affects portability to CWL.
• Galaxy issue #20541 (Custom Tabular Inputs for Workflows) — long-term home for richer column-validation, or extend sample_sheet codepath?