nf-core Pipeline Schema Management

Manage the nextflow_schema.json file that defines pipeline parameters following JSONSchema Draft 7 specification.

Quick Commands

bash

# Build/update schema from nextflow.config
conda run -n nf-core nf-core pipelines schema build

# Build with web interface only (no prompts)
conda run -n nf-core nf-core pipelines schema build --web-only

# Lint schema for errors
conda run -n nf-core nf-core pipelines schema lint

# Validate a params file against schema
conda run -n nf-core nf-core pipelines schema validate <pipeline> params.json

# Generate documentation from schema
conda run -n nf-core nf-core pipelines schema docs nextflow_schema.json --output params.md
conda run -n nf-core nf-core pipelines schema docs nextflow_schema.json --output params.md --format markdown

Process

•Define Parameters: Add params to nextflow.config
•Build Schema: Run nf-core pipelines schema build to generate/update
•Organize in Web UI: Use the web interface to organize into groups
•Add Descriptions: Document each parameter
•Lint: Validate schema structure
•Test: Validate sample params files

Schema Structure

json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/nf-core/mypipeline/master/nextflow_schema.json",
  "title": "nf-core/mypipeline pipeline parameters",
  "description": "Pipeline description",
  "type": "object",
  "defs": {
    "input_output_options": {
      "title": "Input/output options",
      "type": "object",
      "fa_icon": "fas fa-terminal",
      "description": "Define input and output paths",
      "required": ["input", "outdir"],
      "properties": {
        "input": {
          "type": "string",
          "format": "file-path",
          "exists": true,
          "mimetype": "text/csv",
          "pattern": "^\\S+\\.csv$",
          "description": "Path to samplesheet",
          "fa_icon": "fas fa-file-csv"
        },
        "outdir": {
          "type": "string",
          "format": "directory-path",
          "description": "Output directory",
          "fa_icon": "fas fa-folder-open",
          "default": "./results"
        }
      }
    }
  },
  "allOf": [
    { "$ref": "#/defs/input_output_options" }
  ]
}

Parameter Types

Type	Example	Use Case
`string`	`"value"`	Text, paths, enums
`integer`	`10`	Whole numbers
`number`	`0.05`	Decimals
`boolean`	`true/false`	Flags
`object`	`{}`	Complex structures
`array`	`[]`	Lists

Parameter Formats

For string types, use formats:

json

{
  "input": {
    "type": "string",
    "format": "file-path",
    "exists": true
  },
  "outdir": {
    "type": "string",
    "format": "directory-path"
  },
  "email": {
    "type": "string",
    "format": "email"
  }
}

Common Parameter Groups

Standard nf-core parameter organization:

•Input/output options: --input, --outdir
•Reference genome options: --genome, --fasta
•Analysis options: Pipeline-specific params
•Process skipping options: --skip_* flags
•Institutional config options: --config_profile_*
•Max job request options: --max_cpus, --max_memory, --max_time
•Generic options: --help, --version, --publish_dir_mode

Naming Conventions

•snake_case: input_file not inputFile
•Boolean negatives: skip_qc not run_qc
•Descriptive: min_read_length not minlen

Adding a New Parameter

•

Add to nextflow.config:

nextflow

params {
    // Analysis options
    min_quality = 20
}

•

Run schema build:

bash

conda run -n nf-core nf-core pipelines schema build

•
Answer prompts or use web UI to:
- •Set type (integer)
- •Add description
- •Set minimum/maximum values
- •Choose icon
- •Assign to group

•

Resulting schema entry:

json

"min_quality": {
  "type": "integer",
  "default": 20,
  "minimum": 0,
  "maximum": 40,
  "description": "Minimum base quality score",
  "fa_icon": "fas fa-chart-bar"
}

Validation with nf-schema

In your workflow, validate params:

nextflow

include { validateParameters; paramsSummaryLog } from 'plugin/nf-schema'

// Validate parameters
validateParameters()

// Log parameter summary
log.info paramsSummaryLog(workflow)

Samplesheet Schema

Define samplesheet columns in a separate schema file referenced from the parameter:

json

"input": {
  "type": "string",
  "format": "file-path",
  "schema": "assets/schema_input.json",
  "description": "Path to samplesheet"
}

Common Issues

Parameter Not in Schema

Run nf-core pipelines schema build to add new params

Type Mismatch

Ensure config default matches schema type

Missing Required Fields

Add "required": ["param1", "param2"] to definitions

Validation Failure

Check param values against schema constraints (min, max, enum, pattern)