Schema for Nextflow pipeline specs¶

Title: Schema for Nextflow pipeline specs

Description: Schema to validate Nextflow pipeline specs

$schema¶

Title: schema

$id¶

Title: ID URI

title¶

Title: Title

description¶

Title: Description

type¶

Title: Top level type

Specific value: "object"

$defs¶

Title: Parameter groups

Description: A slightly strange use of a JSON schema standard that we use for Nextflow schema is $defs.

JSON schema can group variables together in an object, but then the validation expects this structure to exist in the data that it is validating. In reality, we have a very long "flat" list of parameters, all at the top level of params.foo.

In order to give some structure to log outputs, documentation and so on, we group parameters into $defs. Each def is an object with a title, description and so on. However, as they are under $defs scope they are effectively ignored by the validation and so their nested nature is not a problem. We then bring the contents of each definition object back to the "flat" top level for validation using a series of allOf statements at the end of the schema, which reference the specific definition keys.

^.*$¶

All properties whose name matches the regular expression ^.*$ (Test) must respect the following conditions

title¶

type¶

Specific value: "object"

fa_icon¶

description¶

required¶

Description: Any parameters that must be specified should be set as required in the schema.

This is not done with a property key like other things described below, but rather by naming the parameter in the required array in the definition object / top-level object.

For more information, see the JSON schema documentation.

properties¶

^.*$¶

All properties whose name matches the regular expression ^.*$ (Test) must respect the following conditions

standardKeywords¶

Description: Allowed standard JSON Schema properties.

type¶

Description: Variable type, taken from the JSON schema keyword vocabulary:

• string
• number (float)
• integer
• boolean (true / false)
• object (currently only supported for file validation)
• array (currently only supported for file validation)

Validation checks that the supplied parameter matches the expected type, and will fail with an error if not.

This JSON schema type is not supported:

• null

typeAnnotation¶

Must be one of:

• "string"
• "boolean"
• "integer"
• "number"
• "null"

item 1¶

typeAnnotation¶

format¶

Description: Formats can be used to give additional validation checks against string values for certain properties.

Example usage is as follows:

{
  "type": "string",
  "format": "file-path"
}

The available format types are below:

file-path

States that the provided value is a file. Does not check its existence, but it does check if the path is not a directory.

directory-path

States that the provided value is a directory. Does not check its existence, but if it exists, it does check that the path is not a file.

path

States that the provided value is a path (file or directory). Does not check its existence.

file-path-pattern

States that the provided value is a glob pattern that will be used to fetch files. Checks that the pattern is valid and that at least one file is found.

Must be one of:

• "file-path"
• "directory-path"
• "path"
• "file-path-pattern"
• "date-time"
• "date"
• "time"
• "email"
• "uri"
• "regex"

pattern¶

Description: Regular expression which the string must match in order to pass validation.

• See the JSON schema docs for details.
• Use https://regex101.com/ for help with writing regular expressions.

For example, this pattern only validates if the supplied string ends in .fastq, .fq, .fastq.gz or .fq.gz:

{
  "type": "string",
  "pattern": ".*.f(ast)?q(.gz)?$"
}

description¶

Description: A short description of what the parameter does, written in markdown. Printed in docs and terminal help text. Should be maximum one short sentence.

default¶

Description: Default value for the parameter.

Should match the type and validation patterns set for the parameter in other fields.

examples¶

Description: A list of examples for the current parameter

allTypes¶

deprecated¶

Description: !!! example "Extended key"

A boolean JSON flag that instructs anything using the schema that this parameter/field is deprecated and should not be used. This can be useful to generate messages telling the user that a parameter has changed between versions.

JSON schema states that this is an informative key only, but in nf-schema this will cause a validation error if the parameter/field is used.

minLength¶

Description: Specify a minimum / maximum string length with minLength and maxLength.

• See the JSON schema docs for details.

{
  "type": "string",
  "minLength": 2,
  "maxLength": 3
}

maxLength¶

Description: Specify a minimum / maximum string length with minLength and maxLength.

• See the JSON schema docs for details.

{
  "type": "string",
  "minLength": 2,
  "maxLength": 3
}

minimum¶

Description: Specify a minimum / maximum value for an integer or float number length with minimum and maximum.

• See the JSON schema docs for details.

If x is the value being validated, the following must hold true:

• x ≥ minimum
• x ≤ maximum

{
  "type": "number",
  "minimum": 0,
  "maximum": 100
}

exclusiveMinimum¶

Description: Specify a minimum / maximum value for an integer or float number length with minimum and maximum.

• See the JSON schema docs for details.

If x is the value being validated, the following must hold true:

• x ≥ minimum
• x ≤ maximum

{
  "type": "number",
  "minimum": 0,
  "maximum": 100
}

maximum¶

Description: Specify a minimum / maximum value for an integer or float number length with minimum and maximum.

• See the JSON schema docs for details.

If x is the value being validated, the following must hold true:

• x ≥ minimum
• x ≤ maximum

{
  "type": "number",
  "minimum": 0,
  "maximum": 100
}

exclusiveMaximum¶

Description: Specify a minimum / maximum value for an integer or float number length with minimum and maximum.

• See the JSON schema docs for details.

If x is the value being validated, the following must hold true:

• x ≥ minimum
• x ≤ maximum

{
  "type": "number",
  "minimum": 0,
  "maximum": 100
}

multipleOf¶

Description: The 'integer' or 'number' parameter value should be a multiple of this value

enum¶

Description: An array of enumerated values: the parameter must match one of these values exactly to pass validation.

• See the JSON schema docs for details.
• Available for strings, numbers and integers.

{
  "enum": ["red", "amber", "green"]
}

allTypes¶

const¶

Description: The parameter value should be equal to this value

customKeywords¶

Description: Additional custom JSON Schema properties.

errorMessage¶

Description:

If validation fails, an error message is printed to the terminal, so that the end user knows what to fix. However, these messages are not always very clear - especially to newcomers.

To improve this experience, pipeline developers can set a custom errorMessage for a given parameter in a the schema. If validation fails, this errorMessage is printed after the original error message to guide the pipeline users to an easier solution.

For example, instead of printing:

* --input (samples.yml): "samples.yml" does not match regular expression [^\S+\.csv$]

We can set

"input": {
  "type": "string",
  "pattern": "^\S+\.csv$",
  "errorMessage": "File name must end in '.csv' cannot contain spaces"
}

and get:

* --input (samples.yml): "samples.yml" does not match regular expression [^\S+\.csv$] (File name must end in '.csv' cannot contain spaces)

exists¶

Description: When a format is specified for a value, you can provide the key exists set to true in order to validate that the provided path exists. Set this to false to validate that the path does not exist.

Example usage is as follows:

{
  "type": "string",
  "format": "file-path",
  "exists": true
}

schema¶

Description: Path to a JSON schema file used to validate the supplied file.

Should only be set when format is file-path.

These schema files are typically stored in the pipeline assets directory, but can be anywhere.

{
  "type": "string",
  "format": "file-path",
  "schema": "assets/foo_schema.json"
}

help_text¶

Description:

A longer text with usage help for the parameter, written in markdown. Can include newlines with multiple paragraphs and more complex markdown structures.

Typically hidden by default in documentation and interfaces, unless explicitly clicked / requested.

fa_icon¶

Description:

A text identifier corresponding to an icon from Font Awesome. Used for easier visual navigation of documentation and pipeline interfaces.

Should be the font-awesome class names, for example:

"fa_icon": "fas fa-file-csv"

hidden¶

Description:

A boolean JSON flag that instructs anything using the schema that this is an unimportant parameter.

Typically used to keep the pipeline docs / UIs uncluttered with common parameters which are not used by the majority of users. For example, --plaintext_email and --monochrome_logs.

"hidden": true

mimetype¶

Description: MIME type for a file path. Setting this value informs downstream tools about what kind of file is expected.

Should only be set when format is file-path.

• See a list of common MIME types

{
  "type": "string",
  "format": "file-path",
  "mimetype": "text/csv"
}

The following properties are required¶

• type
• description

dependentRequired¶

additionalProperties¶

additionalProperties items¶

properties¶

dependentRequired¶

additionalProperties¶

additionalProperties items¶

allOf¶

Title: Combine definition groups

allOf items¶

$ref¶

Generated using json-schema-for-humans