Merge remote-tracking branch 'upstream/main' into dev

Author: effigies

CHANGELOG.md

@@ -1,3 +1,26 @@
+
+<a id='changelog-"2.0.6"'></a>
+# "2.0.6" — 2025-05-23
+
+## Added
+
+- Explain the issue data fields in the documentation. ([#199])
+
+[#199]: https://github.com/bids-standard/bids-validator/pull/199
+
+## Changed
+
+- Validator now returns exit code 16 instead of 1 for validation of a dataset with errors.
+
+- Rely on `schema.meta.associations` to load context associations instead of relying on list maintained in validator.
+
+## Fixed
+
+- Sidecar checks are skipped for text files that should not have sidecars.
+  This resolves a problem in derivative datasets, where BIDS specifies a
+  RECOMMENDED field of `Description` in all derivative files. ([#202])
+
+[#202]: https://github.com/bids-standard/bids-validator/issues/202
 <a id='changelog-2.0.4'></a>
 # 2.0.5 — 2025-03-31
 

deno.json

@@ -28,7 +28,7 @@
   },
   "imports": {
     "@ajv": "npm:[email protected]",
-    "@bids/schema": "jsr:@bids/[email protected].12+78213dcf",
+    "@bids/schema": "jsr:@bids/schema@^1.1.0-dev.16+a7dd34ad",
     "@cliffy/command": "jsr:@effigies/[email protected]",
     "@cliffy/table": "jsr:@effigies/[email protected]",
     "@hed/validator": "npm:[email protected]",

deno.lock

@@ -1 +1,119 @@
 # Understanding issues
+
+BIDS Validator issues are structured results that describe problems or potential
+problems in the dataset.
+Issues can either be warnings or errors.
+
+Errors are emitted when a violation of the BIDS specification is detected,
+or, in some cases, the validator is unable to read part of the dataset.
+Errors must be resolved in order for a dataset to be considered valid.
+
+Warnings are emitted when BIDS specification recommendations are not followed,
+as well as cases where a common problem may be present, and user attention
+is needed to verify the validity of the dataset.
+
+## Issue model
+
+Every issue has a code indicating the issue type, a location indicating
+the file where the issue was detected, and a severity field that can
+either be "warning" or "error".
+If some issues are configured to be ignored, in JSON output mode they would still be listed and
+have severity "ignore".
+
+| `code`                    | `location`                       | `severity` |
+| ------------------------- | -------------------------------- | ---------- |
+| `NIFTI_HEADER_UNREADABLE` | `/sub-01/anat/sub-01_T1w.nii.gz` | `error`    |
+| `README_FILE_SMALL`       | `/README`                        | `warning`  |
+
+In the web validator, these issues appear as:
+
+![A NIFTI_HEADER_UNREADABLE error in the web validator. (Dark theme)
+](../_static/example_error_dark.png){.only-dark align=center}
+![A NIFTI_HEADER_UNREADABLE error in the web validator. (Light theme)
+](../_static/example_error_light.png){.only-light align=center}
+
+![A README_FILE_SMALL warning in the web validator. (Dark theme)
+](../_static/example_warning_dark.png){.only-dark align=center}
+![A README_FILE_SMALL warning in the web validator. (Light theme)
+](../_static/example_warning_light.png){.only-light align=center}
+
+In the command-line validator, these would be rendered as:
+
+```console
+	[WARNING] README_FILE_SMALL The recommended file '/README' is very small.
+    Please consider expanding it with additional information about the dataset.
+
+		/README
+
+	[ERROR] NIFTI_HEADER_UNREADABLE We were unable to parse header data from this NIfTI file.
+    Please ensure it is not corrupted or mislabeled.
+		/sub-01/anat/sub-01_T1w.nii.gz
+		/sub-02/anat/sub-02_T1w.nii.gz
+```
+
+### Subcodes
+
+Some classes of issue can be found many times, even in the same file.
+For example, invalid sidecar metadata,
+such as using `"MagneticFieldStrength": "3T"` instead of `"MagneticFieldStrength": 3`,
+triggers a `JSON_SCHEMA_VALIDATION_ERROR` because the value must be numeric rather
+than textual.
+
+Consider the following issues:
+
+| `code`                         | `subcode`               | `location`                               | `severity` |
+| ------------------------------ | ----------------------- | ---------------------------------------- | ---------- |
+| `JSON_SCHEMA_VALIDATION_ERROR` | `MagneticFieldStrength` | `/T1w.json`                              | `error`    |
+| `JSON_KEY_REQUIRED`            | `BIDSVersion`           | `/dataset_description.json`              | `error`    |
+| `JSON_KEY_RECOMMENDED`         | `GeneratedBy`           | `/dataset_description.json`              | `warning`  |
+| `SIDECAR_KEY_REQUIRED`         | `RepetitionTime`        | `/sub-01/func/sub-01_task-rest_bold.nii` | `error`    |
+| `SIDECAR_KEY_RECOMMENDED`      | `EchoTime`              | `/sub-01/func/sub-01_task-rest_bold.nii` | `warning`  |
+
+Each of these issue codes are general, and the subcode indicates the specific
+JSON field that is missing or invalid.
+
+Note that, when a value is absent or invalid in a specific file,
+the location is the JSON file can be listed.
+For example, the invalid `MagneticFieldStrength` may affect many `*_T1w.nii.gz` files,
+but it can be found in a single file.
+On the other hand, for missing sidecar keys, the [inheritance principle](../validation-model/index.md)
+permits the data to be defined in multiple files.
+
+### All fields
+
+The validator defines the following fields for issues:
+
+| Field          | Type       | Description                                                              |
+| -------------- | ---------- | ------------------------------------------------------------------------ |
+| `code`         | `string`   | The type of issue detected                                               |
+| `subCode`      | `string`   | For some `code`s, additional information to narrow the issue type        |
+| `severity`     | `string`   | `"error"`, `"warning"` or `"ignore"`                                     |
+| `location`     | `string`   | A path to the file in the dataset where the error occurs.                |
+| `issueMessage` | `string`   | A human-readable description of the issue.                               |
+| `suggestion`   | `string`   | A suggestion for a plausible fix.                                        |
+| `affects`      | `string[]` | A list of files affected by the error, if more than `location`.          |
+| `rule`         | `string`   | The rule ID in the BIDS schema that failed to pass.                      |
+| `line`         | `number`   | The line number (0-indexed) in `location` that triggered the issue.      |
+| `character`    | `number`   | The character column (0-indexed) in `location` that triggered the issue. |
+
+All fields except `code`, `severity` and `location` are optional and may be
+absent from any issue.
+
+## External validators
+
+BIDS reuses many other data standards (see e.g. [BIDS Philosophy](https://bids.neuroimaging.io/index.html#philosophy) section).
+Where feasible, the BIDS Validator will call an external validator and
+expose its issues as BIDS issues.
+
+### Hierarchical Event Descriptors (HED)
+
+The HED validator produces issues of the following form:
+
+| Field          | Type       | Description                                                         |
+| -------------- | ---------- | ------------------------------------------------------------------- |
+| `code`         | `string`   | `HED_WARNING` or `HED_ERROR`                                        |
+| `subCode`      | `string`   | The `"hedCode"` emitted by the HED validator.                       |
+| `severity`     | `string`   | `"error"` or `"warning"`                                            |
+| `location`     | `string`   | A path to the file in the dataset where the error occurs.           |
+| `issueMessage` | `string`   | A human-readable description of the issue.                          |
+| `line`         | `number`   | The line number (0-indexed) in `location` that triggered the issue. |

docs/_static/example_error_dark.png

@@ -27,6 +27,9 @@ def pdm_build_initialize(context):
             "compile",
             "-ERNW",
             "--allow-run",
+            # Types are checked elsewhere. Type checking at wheel build
+            # is painful if some platforms have newer typescript than others.
+            "--no-check",
             "-o",
             str(target),
             "src/bids-validator.ts",

docs/_static/example_error_light.png

@@ -4,5 +4,5 @@ const result = await main()
 
 const errors = result.issues.get({ severity: 'error' })
 if (errors.length) {
-  Deno.exit(1)
+  Deno.exit(16)
 }