Skip to content

Commit 01f235e

Browse files
effigieseffigies
authored
Merge pull request #199 from effigies/doc/issues
doc: Describe the issue model
2 parents 3e75668 + 820d370 commit 01f235e

File tree

6 files changed

+167
-0
lines changed

6 files changed

+167
-0
lines changed

‎changelog.d/20250417_154622_markiewicz_issues.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
<!--
2+
A new scriv changelog fragment.
3+
4+
Uncomment the section that is right (remove the HTML comment wrapper).
5+
For top level release notes, leave all the headers commented out.
6+
-->
7+
8+
### Added
9+
10+
- Explain the issue data fields in the documentation. ([#199])
11+
12+
[#199]: https://github.com/bids-standard/bids-validator/pull/199
13+
14+
<!--
15+
### Changed
16+
17+
- A bullet item for the Changed category.
18+
19+
-->
20+
<!--
21+
### Fixed
22+
23+
- A bullet item for the Fixed category.
24+
25+
-->
26+
<!--
27+
### Deprecated
28+
29+
- A bullet item for the Deprecated category.
30+
31+
-->
32+
<!--
33+
### Removed
34+
35+
- A bullet item for the Removed category.
36+
37+
-->
38+
<!--
39+
### Security
40+
41+
- A bullet item for the Security category.
42+
43+
-->
44+
<!--
45+
### Infrastructure
46+
47+
- A bullet item for the Infrastructure category.
48+
49+
-->

‎docs/_static/example_error_dark.png‎

28.6 KB
Loading

‎docs/_static/example_error_light.png‎

27 KB
Loading

‎docs/_static/example_warning_dark.png‎

24.7 KB
Loading

‎docs/_static/example_warning_light.png‎

23.2 KB
Loading

‎docs/user_guide/issues.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,119 @@
11
# Understanding issues
2+
3+
BIDS Validator issues are structured results that describe problems or potential
4+
problems in the dataset.
5+
Issues can either be warnings or errors.
6+
7+
Errors are emitted when a violation of the BIDS specification is detected,
8+
or, in some cases, the validator is unable to read part of the dataset.
9+
Errors must be resolved in order for a dataset to be considered valid.
10+
11+
Warnings are emitted when BIDS specification recommendations are not followed,
12+
as well as cases where a common problem may be present, and user attention
13+
is needed to verify the validity of the dataset.
14+
15+
## Issue model
16+
17+
Every issue has a code indicating the issue type, a location indicating
18+
the file where the issue was detected, and a severity field that can
19+
either be "warning" or "error".
20+
If some issues are configured to be ignored, in JSON output mode they would still be listed and
21+
have severity "ignore".
22+
23+
| `code` | `location` | `severity` |
24+
| ------------------------- | -------------------------------- | ---------- |
25+
| `NIFTI_HEADER_UNREADABLE` | `/sub-01/anat/sub-01_T1w.nii.gz` | `error` |
26+
| `README_FILE_SMALL` | `/README` | `warning` |
27+
28+
In the web validator, these issues appear as:
29+
30+
![A NIFTI_HEADER_UNREADABLE error in the web validator. (Dark theme)
31+
](../_static/example_error_dark.png){.only-dark align=center}
32+
![A NIFTI_HEADER_UNREADABLE error in the web validator. (Light theme)
33+
](../_static/example_error_light.png){.only-light align=center}
34+
35+
![A README_FILE_SMALL warning in the web validator. (Dark theme)
36+
](../_static/example_warning_dark.png){.only-dark align=center}
37+
![A README_FILE_SMALL warning in the web validator. (Light theme)
38+
](../_static/example_warning_light.png){.only-light align=center}
39+
40+
In the command-line validator, these would be rendered as:
41+
42+
```console
43+
[WARNING] README_FILE_SMALL The recommended file '/README' is very small.
44+
Please consider expanding it with additional information about the dataset.
45+
46+
/README
47+
48+
[ERROR] NIFTI_HEADER_UNREADABLE We were unable to parse header data from this NIfTI file.
49+
Please ensure it is not corrupted or mislabeled.
50+
/sub-01/anat/sub-01_T1w.nii.gz
51+
/sub-02/anat/sub-02_T1w.nii.gz
52+
```
53+
54+
### Subcodes
55+
56+
Some classes of issue can be found many times, even in the same file.
57+
For example, invalid sidecar metadata,
58+
such as using `"MagneticFieldStrength": "3T"` instead of `"MagneticFieldStrength": 3`,
59+
triggers a `JSON_SCHEMA_VALIDATION_ERROR` because the value must be numeric rather
60+
than textual.
61+
62+
Consider the following issues:
63+
64+
| `code` | `subcode` | `location` | `severity` |
65+
| ------------------------------ | ----------------------- | ---------------------------------------- | ---------- |
66+
| `JSON_SCHEMA_VALIDATION_ERROR` | `MagneticFieldStrength` | `/T1w.json` | `error` |
67+
| `JSON_KEY_REQUIRED` | `BIDSVersion` | `/dataset_description.json` | `error` |
68+
| `JSON_KEY_RECOMMENDED` | `GeneratedBy` | `/dataset_description.json` | `warning` |
69+
| `SIDECAR_KEY_REQUIRED` | `RepetitionTime` | `/sub-01/func/sub-01_task-rest_bold.nii` | `error` |
70+
| `SIDECAR_KEY_RECOMMENDED` | `EchoTime` | `/sub-01/func/sub-01_task-rest_bold.nii` | `warning` |
71+
72+
Each of these issue codes are general, and the subcode indicates the specific
73+
JSON field that is missing or invalid.
74+
75+
Note that, when a value is absent or invalid in a specific file,
76+
the location is the JSON file can be listed.
77+
For example, the invalid `MagneticFieldStrength` may affect many `*_T1w.nii.gz` files,
78+
but it can be found in a single file.
79+
On the other hand, for missing sidecar keys, the [inheritance principle](../validation-model/index.md)
80+
permits the data to be defined in multiple files.
81+
82+
### All fields
83+
84+
The validator defines the following fields for issues:
85+
86+
| Field | Type | Description |
87+
| -------------- | ---------- | ------------------------------------------------------------------------ |
88+
| `code` | `string` | The type of issue detected |
89+
| `subCode` | `string` | For some `code`s, additional information to narrow the issue type |
90+
| `severity` | `string` | `"error"`, `"warning"` or `"ignore"` |
91+
| `location` | `string` | A path to the file in the dataset where the error occurs. |
92+
| `issueMessage` | `string` | A human-readable description of the issue. |
93+
| `suggestion` | `string` | A suggestion for a plausible fix. |
94+
| `affects` | `string[]` | A list of files affected by the error, if more than `location`. |
95+
| `rule` | `string` | The rule ID in the BIDS schema that failed to pass. |
96+
| `line` | `number` | The line number (0-indexed) in `location` that triggered the issue. |
97+
| `character` | `number` | The character column (0-indexed) in `location` that triggered the issue. |
98+
99+
All fields except `code`, `severity` and `location` are optional and may be
100+
absent from any issue.
101+
102+
## External validators
103+
104+
BIDS reuses many other data standards (see e.g. [BIDS Philosophy](https://bids.neuroimaging.io/index.html#philosophy) section).
105+
Where feasible, the BIDS Validator will call an external validator and
106+
expose its issues as BIDS issues.
107+
108+
### Hierarchical Event Descriptors (HED)
109+
110+
The HED validator produces issues of the following form:
111+
112+
| Field | Type | Description |
113+
| -------------- | ---------- | ------------------------------------------------------------------- |
114+
| `code` | `string` | `HED_WARNING` or `HED_ERROR` |
115+
| `subCode` | `string` | The `"hedCode"` emitted by the HED validator. |
116+
| `severity` | `string` | `"error"` or `"warning"` |
117+
| `location` | `string` | A path to the file in the dataset where the error occurs. |
118+
| `issueMessage` | `string` | A human-readable description of the issue. |
119+
| `line` | `number` | The line number (0-indexed) in `location` that triggered the issue. |

0 commit comments

Comments
 (0)