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 ``...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 ``...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 ``...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 ``...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: .. code-block:: json { "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.