module-spec-schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/nextflow-io/schemas/main/module/v1/schema.json",
  "title": "Nextflow Module Schema",
  "description": "Schema for Nextflow module meta.yml files, supporting both nf-core community patterns and the Nextflow module system",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Module name. Can be a simple identifier (e.g., 'fastqc', 'bwa_mem') for local/nf-core modules, or a fully qualified scoped name (e.g., 'nf-core/fastqc', 'myorg/custom') for registry modules.",
      "examples": ["fastqc", "bwa_mem", "nf-core/fastqc", "myorg/salmon-quant"],
      "pattern": "^([a-z0-9][a-z0-9-]*/)?[a-z][a-z0-9_-]*$"
    },
    "version": {
      "type": "string",
      "description": "Semantic version of the module (MAJOR.MINOR.PATCH). Required for registry publication",
      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(-[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?(\\+[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?$",
      "examples": ["1.0.0", "2.1.3", "1.0.0-beta.1"]
    },
    "description": {
      "type": "string",
      "description": "Brief description of what the module does",
      "minLength": 10,
      "maxLength": 500
    },
    "keywords": {
      "type": "array",
      "description": "Keywords for discovery and categorization",
      "items": {
        "type": "string",
        "minLength": 2
      },
      "minItems": 1,
      "uniqueItems": true
    },
    "license": {
      "type": "string",
      "description": "SPDX license identifier for the module code itself",
      "examples": ["MIT", "Apache-2.0", "GPL-3.0-or-later"]
    },
    "authors": {
      "type": "array",
      "description": "Original authors of the module (GitHub handles preferred)",
      "items": {
        "type": "string",
        "pattern": "^@?[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$"
      },
      "minItems": 1
    },
    "maintainers": {
      "type": "array",
      "description": "Current maintainers of the module (GitHub handles preferred)",
      "items": {
        "type": "string",
        "pattern": "^@?[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?$"
      }
    },
    "requires": {
      "type": "object",
      "description": "Runtime requirements for the module",
      "properties": {
        "nextflow": {
          "type": "string",
          "description": "Nextflow version constraint using comparison operators",
          "examples": [">=24.04.0", ">=24.04.0,<25.0.0"],
          "pattern": "^[<>=!]+[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9]+)?(,\\s*[<>=!]+[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9]+)?)*$"
        }
      },
      "additionalProperties": false
    },
    "input": {
      "type": "array",
      "description": "Inputs of the module",
      "items": {
        "$ref": "#/$defs/structuredParameter"
      }
    },
    "params": {
      "type": "array",
      "description": "Module parameter specifications",
      "items": {
        "$ref": "#/$defs/paramSpec"
      }
    },
    "output": {
      "type": "array",
      "description": "Outputs of the module",
      "items": {
        "$ref": "#/$defs/structuredParameter"
      }
    },
    "topics": {
      "type": "array",
      "description": "Topics of the module",
      "items": {
        "$ref": "#/$defs/structuredParameter"
      }
    },
    "tools": {
      "type": "array",
      "description": "Software tools wrapped by this module with their metadata",
      "items": {
        "type": "object",
        "minProperties": 1,
        "maxProperties": 1,
        "patternProperties": {
          "^[a-zA-Z][a-zA-Z0-9_-]*$": {
            "$ref": "#/$defs/toolSpec"
          }
        }
      }
    }
  },
  "required": ["name", "description"],
  "$defs": {
    "toolSpec": {
      "type": "object",
      "description": "Specification for a software tool used by the module",
      "properties": {
        "description": {
          "type": "string",
          "description": "Description of the tool and its purpose"
        },
        "homepage": {
          "type": "string",
          "format": "uri",
          "description": "Tool's homepage URL",
          "pattern": "^https?://.*$"
        },
        "documentation": {
          "type": "string",
          "format": "uri",
          "description": "Documentation URL",
          "pattern": "^(https?|ftp)://.*$"
        },
        "tool_dev_url": {
          "type": "string",
          "format": "uri",
          "description": "Development/source code URL",
          "pattern": "^https?://.*$"
        },
        "doi": {
          "description": "Digital Object Identifier for the tool's publication",
          "oneOf": [
            {
              "type": "string",
              "pattern": "^10\\.\\d{4,9}/[^,]+$"
            },
            {
              "type": "string",
              "const": "no DOI available"
            }
          ]
        },
        "arxiv": {
          "type": "string",
          "description": "arXiv identifier",
          "pattern": "^arXiv:\\d{4}\\.\\d{4,5}(v\\d+)?$"
        },
        "licence": {
          "type": "array",
          "description": "SPDX license identifier(s) for the tool",
          "items": {
            "type": "string"
          },
          "minItems": 1,
          "uniqueItems": true
        },
        "identifier": {
          "description": "bio.tools identifier or empty string",
          "oneOf": [
            {
              "type": "string",
              "pattern": "^biotools:[a-zA-Z0-9_-]+$"
            },
            {
              "type": "string",
              "maxLength": 0
            }
          ]
        },
        "manual": {
          "type": "string",
          "format": "uri",
          "description": "Manual/user guide URL"
        }
      },
      "required": ["description"],
      "anyOf": [
        {
          "required": ["homepage"]
        },
        {
          "required": ["documentation"]
        },
        {
          "required": ["tool_dev_url"]
        },
        {
          "required": ["doi"]
        }
      ]
    },
    "structuredParameter": {
      "type": "array",
      "items": {
        "oneOf": [
          {
            "$ref": "#/$defs/paramSpec"
          },
          {
            "type": "array",
            "items": {
              "$ref": "#/$defs/paramSpec"
            }
          }
        ]
      }
    },
    "paramSpec": {
      "type": "object",
      "description": "Specification for a module parameter",
      "properties": {
        "name": {
          "type": "string",
          "description": "Parameter identifier",
          "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
        },
        "type": {
          "type": "string",
          "description": "Data type of the parameter value",
          "enum": [
            "boolean",
            "float",
            "integer",
            "string",
            "list",
            "map",
            "file",
            "directory"
          ]
        },
        "description": {
          "type": "string",
          "description": "Human-readable description of the parameter"
        },
        "pattern": {
          "type": "string",
          "description": "Glob pattern for file/directory parameters"
        },
        "optional": {
          "type": "boolean",
          "description": "Whether this parameter is optional",
          "default": false
        },
        "enum": {
          "type": "array",
          "description": "List of allowed values",
          "uniqueItems": true
        },
        "ontologies": {
          "type": "array",
          "description": "Ontology annotations (e.g., EDAM)",
          "items": {
            "type": "object",
            "patternProperties": {
              "^[a-zA-Z]+$": {
                "type": "string",
                "format": "uri",
                "description": "Ontology URI"
              }
            }
          },
          "uniqueItems": true
        }
      },
      "required": ["name", "type", "description"]
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "name": {
            "pattern": "^[a-z0-9][a-z0-9-]*/"
          }
        },
        "required": ["name"]
      },
      "then": {
        "required": ["name", "description", "version"],
        "properties": {
          "version": {
            "description": "Version is required for scoped/registry modules (scope/name format)"
          }
        }
      }
    }
  ],
  "examples": [
    {
      "name": "fastqc",
      "description": "Run FastQC on sequenced reads",
      "keywords": ["quality control", "qc", "adapters", "fastq"],
      "tools": [
        {
          "fastqc": {
            "description": "FastQC gives general quality metrics about your reads.",
            "homepage": "https://www.bioinformatics.babraham.ac.uk/projects/fastqc/",
            "documentation": "https://www.bioinformatics.babraham.ac.uk/projects/fastqc/Help/",
            "licence": ["GPL-2.0-only"],
            "identifier": "biotools:fastqc"
          }
        }
      ],
      "input": [
        [
          {
            "meta": {
              "type": "map",
              "description": "Groovy Map containing sample information"
            }
          },
          {
            "reads": {
              "type": "file",
              "description": "Input FastQ files",
              "ontologies": []
            }
          }
        ]
      ],
      "output": {
        "html": [
          [
            {
              "meta": {
                "type": "map",
                "description": "Sample information"
              }
            },
            {
              "*.html": {
                "type": "file",
                "description": "FastQC report",
                "pattern": "*_{fastqc.html}",
                "ontologies": []
              }
            }
          ]
        ],
        "versions": [
          {
            "versions.yml": {
              "type": "file",
              "description": "File containing software versions",
              "pattern": "versions.yml"
            }
          }
        ]
      },
      "authors": ["@drpatelh", "@ewels"],
      "maintainers": ["@drpatelh", "@ewels"]
    },
    {
      "name": "nf-core/bwa-align",
      "version": "1.2.4",
      "description": "Align reads using BWA-MEM algorithm",
      "keywords": ["alignment", "bwa", "mapping", "fastq", "bam"],
      "license": "MIT",
      "authors": ["@nf-core"],
      "maintainers": ["@nf-core"],
      "requires": {
        "nextflow": ">=24.04.0"
      },
      "tools": [
        {
          "bwa": {
            "description": "BWA aligner",
            "homepage": "http://bio-bwa.sourceforge.net/",
            "licence": ["GPL-3.0-or-later"]
          }
        },
        {
          "samtools": {
            "description": "SAMtools",
            "homepage": "http://www.htslib.org/",
            "licence": ["MIT"]
          }
        }
      ],
      "params": [
        {
          "name": "batch_size",
          "type": "integer",
          "description": "Process INT input bases in each batch",
          "example": 100000000
        },
        {
          "name": "use_soft_clipping",
          "type": "boolean",
          "description": "Use soft clipping for supplementary alignments"
        },
        {
          "name": "output_format",
          "type": "string",
          "description": "Output format (sam, bam, or cram)"
        }
      ],
      "input": [
        [
          {
            "meta": {
              "type": "map",
              "description": "Sample metadata map"
            }
          },
          {
            "reads": {
              "type": "file",
              "description": "Input FastQ files",
              "ontologies": [
                { "edam": "http://edamontology.org/format_1930" }
              ]
            }
          }
        ],
        {
          "index": {
            "type": "directory",
            "description": "BWA index directory"
          }
        }
      ],
      "output": {
        "bam": [
          [
            {
              "meta": {
                "type": "map",
                "description": "Sample metadata"
              }
            },
            {
              "*.bam": {
                "type": "file",
                "description": "Aligned BAM file",
                "pattern": "*.bam",
                "ontologies": [
                  { "edam": "http://edamontology.org/format_2572" }
                ]
              }
            }
          ]
        ],
        "versions": [
          {
            "versions.yml": {
              "type": "file",
              "description": "Software versions"
            }
          }
        ]
      }
    }
  ]
}