UI JSON specifications

RAFT uses four related JSON contracts. They serve different purposes and should not be treated as interchangeable.

Machine-readable schema files are packaged with RAFT under src/raft/ui/static/schemas/:

manifest-ui.schema.json
report-ui.schema.json
workflow-definition.schema.json
workflow-config.schema.json

RAFT also performs lightweight runtime validation before serving remote manifest/report templates or workflow definitions to the browser. Invalid remote templates are ignored and RAFT falls back to packaged defaults where possible.

Workflow configuration JSON

Files named <workflow>.<species>.<input>.json are execution contracts used by RAFT project generation. They live next to the workflow .config file in a workflow configuration repository.

Observed public examples include lens.human.fastqs.json, gene-fusions.human.fastqs.json, somatic_vars.human.fastqs.json, germline_vars.human.bams.json, pmhcs.human.fastas.json, and clens.human.demo.json.

Required fields:

modules: Array of module names to load into the RAFT project.
steps: Object mapping workflow step names to the module that provides the step.

Optional fields:

references: Array of reference filenames or URLs that RAFT should stage.
references_postproc: Object mapping staged reference helper filenames to post-processing commands.
find_and_replace: Object mapping literal workflow text to replacement text.
fastqs: Demo-only array of FASTQ URLs to stage.

Config-generator workflow definition JSON

The config generator consumes a workflow definition index. RAFT ships a local static/workflows/index.json and can synthesize equivalent definitions from workflow config repositories.

Required top-level field:

workflows: Array of workflow objects.

Workflow object fields:

id: Stable workflow identifier, such as lens or gene-fusions.
label: Human-readable name.
default_version: Version selected by default in the UI.
versions: Non-empty array of version objects.

Version object fields:

id: Version or branch identifier, such as lens-v1.9-dev.
species: Non-empty array of supported species values.
starting_data: Non-empty array of supported input modes, such as fastqs, bams, fastas, or junctions.
config: Relative path to the workflow .config template.
ui: Optional config-generator hints. Currently supported hints include workflow_param_names, sections, labels, and tooltips. These hints shape display behavior; the underlying .config remains the source of parameter truth.

Manifest UI template

Files named manifest-ui.json or <workflow>.<species>.<input>.manifest-ui.json customize the manifest generator.

Required field:

columns: Non-empty array of column definitions. Each column requires name.

Column fields:

name: Manifest column name written to the TSV.
label: Human-readable label.
required: Boolean used by the UI validator.
type: Optional UI type: text, string, select, boolean, number, or integer.
allowed_values: Optional list used for select-like validation.

Optional top-level fields:

sample_types: Array of sample type definitions. Each sample type requires id and may specify label, prefix, normal, sequencing_method, and defaults.
requirements: Array of workflow-level requirements. Each requirement requires id and may specify sample_type, min, max, and required.

Report UI template

Files named report-ui.json or <workflow>.<species>.<input>.report-ui.json customize the report viewer and portable report bundle contents.

Required field:

sections: Non-empty array of report section definitions. Each section requires id and label.

Section fields:

renderer: Supported values are table, lens_antigen_report, qc_summary, and file_index.
source: Supported values are reports, report, lens, qc, and files. New workflow templates should use reports for primary workflow report sections. lens is retained for older templates.
preload.reports: Optional array of report directories relative to the project directory. raft generate-reports checks these directories, in order, to decide which workflow reports to preload into the viewer. Entries may be strings or objects with path and optional label. For example, LENS fastqs uses outputs/samples because patient report TSVs are written below that tree.
preload.qc: Optional array of QC directories relative to the project directory. Entries follow the same format as preload.reports.
patterns: File glob patterns for report/table sections. These patterns are important for headless report bundles: RAFT uses them to decide which files under the configured report directory should be included. LENS templates should include ["*.report.tsv", "*report*.tsv"] unless the workflow uses a different final report naming convention.
default: Boolean indicating the initially selected section.
controls: Optional renderer controls. LENS supports show_filters, show_visualizations, show_table, and show_cards.
table.columns: Optional array of table columns. Each column requires key and may specify label and format.

Workflow status config

Files named status.json or <workflow>.<species>.<input>.status.json customize raft project-status checks for a workflow. These files should live beside the workflow .config, workflow metadata JSON, manifest UI template, and report UI template.

Required fields are intentionally minimal. A status config may define expected paths, table summaries, or both.

expected_paths: Optional array of paths to check relative to the project directory. Each item requires path and may specify label, type (any, file, or dir), required, and min_count. Paths may contain glob patterns such as outputs/samples/**/*.json.
tables: Optional array of delimited table checks. Each item requires id and patterns. root is relative to the project directory and defaults to outputs. patterns are glob patterns under root.

Table fields:

count_by: Optional array of columns to summarize as value counts.
required_columns: Optional array of columns that should be present. Missing columns become project-status warnings.
all_blank_warning_columns: Optional array of columns that should warn when present but blank in every row.

Example:

{
  "schema_version": "1.0",
  "name": "LENS",
  "expected_paths": [
    {"path": "outputs/lens", "label": "LENS outputs", "type": "dir", "required": true}
  ],
  "tables": [
    {
      "id": "final_report",
      "label": "Final report",
      "root": "outputs/lens",
      "patterns": ["**/*.report.tsv"],
      "count_by": ["antigen_source"],
      "required_columns": ["candidate_id", "antigen_source", "final_tier"]
    }
  ]
}

Stability notes

The workflow configuration JSON is the strongest contract because RAFT uses it to create executable projects. The config-generator workflow definition is also structural and validated.

Manifest, report, and status templates are display/status contracts. They are validated for required structure, but unknown optional fields are allowed so workflow maintainers can add future UI hints without breaking older RAFT releases.

For new workflows, use the narrowest useful report patterns. Avoid broad patterns like *.tsv unless every matching file is safe to upload to the hosted viewer and small enough for a browser bundle.