# Checklist for JSON schema improvements (hackathon March 2025)

- Go to the [project board](https://github.com/orgs/nf-core/projects/99/views/4?sliceBy%5Bvalue%5D=JSON+schema+improvements)
- Choose an issue for a specific pipeline (e.g. `JSON schema: Sarek`)
- Assign yourself to that issue (Click on `Add Assignees...`). You need to be part of the nf-core organization in order to do this. Please request an invite in the #github-invitations Slack channel if you are not in the Github organization.
- Set the issue status to `In Progress`
- Edit the issue and copy paste the next code block into it:

- [ ] Fork the pipeline to your user account, if you have not done so before (Make sure you deselect `Copy the master branch only`)
- [ ] Go to the `dev` branch and sync the upstream changes (`Sync fork` -> `Update branch`)
- [ ] Create a branch called `json-schema-improvements` with the `dev` branch as base in the fork
- [ ] Open the `json-schema-improvements` branch of the fork either locally (`git clone`) or online (via Github Codespaces, GitPod...)
- [ ] Open the `nextflow_schema.json` file
- [ ] Check that the value in `"$schema"` is `"https://json-schema.org/draft/2020-12/schema"`. The pipeline should be updated to nf-schema if this is not the case. See the [migration guide](https://nextflow-io.github.io/nf-schema/latest/migration_guide/) on how to do this
- [ ] Check the schema for insufficient validation keywords and error messages. See the [guide](https://hackmd.io/YXDnZVulTiGjOFw2EsdebA#Checking-the-validation-keywords) for more information on this
- [ ] Do the same thing for `assets/schema_input.json`
- [ ] Run `nextflow run main.nf -profile test,docker --outdir results -stub` to check for any failures in validation with the basic test setup
- [ ] Update the changelog of the pipeline
- [ ] Push all changes to your fork (if you have not done so yet)
- [ ] Open a pull request to the `dev` branch of the nf-core repository
- [ ] Request a review in #hackathon-mar-2025-json-schema-improvements or in the pipeline channel (e.g. #sarek for nf-core/sarek) and set the issue status to `Ready to review` (PR: <ADD A LINK TO THE PR HERE>)
- [ ] Wait for approval and merge the pull request once everything works again
- [ ] Set the issue status to `Done`

- Go over the checklist in the issue.

An example issue can be found here: https://github.com/orgs/nf-core/projects/99/views/4?sliceBy%5Bvalue%5D=JSON+schema+improvements&pane=issue&itemId=101126918

An example PR can be found here: https://github.com/nf-core/pacvar/pull/28

## Checking the validation keywords

This section contains options for each type of parameter (the type can be found in the `"type"` keyword)

IMPORTANT: If an `errorMessage` is present, please update it so that it covers all possible validation errors for the type (the more it covers the better)

ALSO IMPORTANT: Check that the `help_text` and `description` keywords are clear enough

### Type-independent keywords

- [enum](https://nextflow-io.github.io/nf-schema/latest/nextflow_schema/nextflow_schema_specification/#enum): A list of allowed values for the value
- [default](https://nextflow-io.github.io/nf-schema/latest/nextflow_schema/nextflow_schema_specification/#default): The default value, make sure this is filled in if the default value is not `null`, `""` or `false`
- [required](https://json-schema.org/understanding-json-schema/reference/object#required): A list of required parameters for each section

### `string`

- [minLength](https://json-schema.org/understanding-json-schema/reference/string#length) and [maxLength](https://json-schema.org/understanding-json-schema/reference/string#length): specify the minimal and/or maximum length of the `string` value
- [pattern](https://json-schema.org/understanding-json-schema/reference/string#regexp): A regular expression the `string` value has to adhere to
- [format](https://nextflow-io.github.io/nf-schema/latest/nextflow_schema/nextflow_schema_specification/#format): This is mainly used to define if a value should be a `"file-path"`, `"directory-path"`, `"path"` or `"file-path-pattern"`. Other formats are allowed that are part of the official JSON schema specs, but are rarely used in Nextflow JSON schemas
- [exists](https://nextflow-io.github.io/nf-schema/latest/nextflow_schema/nextflow_schema_specification/#exists): Make sure this is `true` if the file should exist (Be careful, some times files or directories do not have to exist for a pipeline to succesfully start e.g. `--outdir`)
- [schema](https://nextflow-io.github.io/nf-schema/latest/nextflow_schema/nextflow_schema_specification/#schema): The relative path from the root of the pipeline to another schema to validate the file specified by that value. Please also check this schema very carefully

### `number` and `integer`

- [multipleOf](https://json-schema.org/understanding-json-schema/reference/numeric#multiples): The value needs to be a multiple of this number
- [minimum, exclusiveMinimum, maximum and exclusiveMaximum](https://json-schema.org/understanding-json-schema/reference/numeric#range): Specify a specific range in which the numeric value should be

### `boolean`

The boolean type has no type-specific keywords

### `array`

WARNING: This type is not supported in `nextflow_schema.json`, but is supported in other schemas

- [uniqueEntries](https://nextflow-io.github.io/nf-schema/latest/nextflow_schema/nextflow_schema_specification/#uniqueentries): A list of keys that need to be unique in the objects present in this array
- [uniqueItems](https://nextflow-io.github.io/nf-schema/latest/nextflow_schema/nextflow_schema_specification/#uniqueitems): Set to `true` if you want each entry in the array to be unique

### `object`

WARNING: This type is not supported in `nextflow_schema.json` (apart from the root `"type"` keyword of the file and of each section in `"$defs"`), but is supported in other schemas

This type can be very complex and will not be used in 99% of the cases. You can take a look at the official [object documentation](https://json-schema.org/understanding-json-schema/reference/object#object) or ask for help in #hackathon-mar-2025-json-schema-improvements if you need to check `object` types