Skip to content

Commit 6105b71

Browse files
rwblairrwblair
authored
Merge branch 'main' into enh/use_association_selectors
2 parents 926c6bc + 01f235e commit 6105b71

File tree

8 files changed

+221
-1
lines changed

8 files changed

+221
-1
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+
-->

‎changelog.d/20250509_080014_markiewicz_bad_sidecars.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
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+
<!--
9+
### Added
10+
11+
- A bullet item for the Added category.
12+
13+
-->
14+
<!--
15+
### Changed
16+
17+
- A bullet item for the Changed category.
18+
19+
-->
20+
### Fixed
21+
22+
- Sidecar checks are skipped for text files that should not have sidecars.
23+
This resolves a problem in derivative datasets, where BIDS specifies a
24+
RECOMMENDED field of `Description` in all derivative files. ([#202])
25+
26+
[#202]: https://github.com/bids-standard/bids-validator/issues/202
27+
28+
<!--
29+
### Deprecated
30+
31+
- A bullet item for the Deprecated category.
32+
33+
-->
34+
<!--
35+
### Removed
36+
37+
- A bullet item for the Removed category.
38+
39+
-->
40+
<!--
41+
### Security
42+
43+
- A bullet item for the Security category.
44+
45+
-->
46+
<!--
47+
### Infrastructure
48+
49+
- A bullet item for the Infrastructure category.
50+
51+
-->

‎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. |

‎src/schema/applyRules.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -181,7 +181,9 @@ function evalJsonCheck(
181181
const sidecarRule = schemaPath.match(/rules\.sidecar/)
182182
// Sidecar rules apply specifically to data files, as JSON files cannot have sidecars
183183
// Count on other JSON rules to use selectors to match the correct files
184-
if (context.extension === '.json' && sidecarRule) return
184+
// Text files at the root do not have sidecars. We might want a cleaner
185+
// or more schematic way to identify them in the future.
186+
if (sidecarRule && (['.json', '', '.md', '.txt', '.rst', '.cff'].includes(context.extension))) return
185187

186188
const json: Record<string, any> = sidecarRule ? context.sidecar : context.json
187189
for (const [key, requirement] of Object.entries(rule.fields)) {

0 commit comments

Comments
 (0)