BIDS schema description¶
Portions of the BIDS specification are defined using YAML files in order to make the specification machine-readable.
Currently the portions of the specification that rely on this schema are:
the entity tables,
entity definitions,
filename templates,
metadata tables.
Any changes to the specification should be mirrored in the schema.
Organization and syntax¶
At the time of this writing, the schema has the following file layout:
├── meta
│ ├── ...
│ └── versions.yaml
├── objects
│ ├── ...
│ └── suffixes.yaml
├── rules
│ ├── checks
│ │ ├── ...
│ │ └── references.yaml
│ ├── files
│ │ ├── common
│ │ │ ├── core.yaml
│ │ │ └── tables.yaml
│ │ ├── deriv
│ │ │ ├── imaging.yaml
│ │ │ └── preprocessed_data.yaml
│ │ └── raw
│ │ ├── ...
│ │ └── task.yaml
│ ├── sidecars
│ │ ├── derivatives
│ │ │ └── common_derivatives.yaml
│ │ ├── ...
│ │ └── pet.yaml
│ ├── tabular_data
│ │ ├── derivatives
│ │ │ └── common_derivatives.yaml
│ │ ├── ...
│ │ └── task.yaml
│ ├── ...
│ └── modalities.yaml
├── BIDS_VERSION
└── SCHEMA_VERSION
The top-level organization includes objects
, where terms are defined;
rules
, where constraints (such as valid filenames or required metadata fields)
are defined;
and meta
, where definitions useful for interpreting the schema are defined.
Each file is made up of YAML data, most often an object.
For example, the file rules/checks/mri.yaml
contains the contents:
PhasePartUnits:
issue:
code: PHASE_UNITS
message: |
Phase images (with the `part-phase` entity) must have units
"rad" or "arbitrary".
level: error
selectors:
- modality == "mri"
- entities.part == "phase"
- '"Units" in sidecar'
checks:
- intersects([sidecar.Units], ["rad", "arbitrary"])
When we wish to refer to a file we might write rules/checks/mri.yaml
.
Alternately, we can use rules.checks.mri
to refer to the object contained by the
file.
Using this notation, the qualified name, the contents of an entire directory or a
portion of a file can be referred to unambiguously.
For example, the entire rules/checks/
directory is referred to as rules.checks
,
and rules.checks.mri.PhasePartUnits.issue
refers to the object:
{
"code": "PHASE_UNITS",
"message": "Phase images (with the `part-phase` [...]\n\"rad\" or \"arbitrary\".\n",
"level": "error"
}
These qualified names may be used in this README, as well as in references and expressions.
Description formatting¶
Many objects throughout the schema have a description
field,
which will typically be rendered somewhere in the specification.
Because the specification is written in Markdown,
these description
fields may also contain Markdown,
including links to other locations in the specification.
Because the same description may be used in multiple locations,
a mechanism is needed to ensure that the correct path is discovered
to render the description in each location.
To do this, the path should follow the form SPEC_ROOT/path/within/source.md#anchor
.
For example, to link to the
Definitions
section of
Common principles,
use the path SPEC_ROOT/common-principles.md#definitions
:
[Common principles - Definitions](SPEC_ROOT/common-principles.md#definitions)
Note that the Markdown extension .md
MUST be used for this to render correctly.
For more information please see the following pull request and linked discussions: #1096
References¶
Some schema entries take the form:
ObjectName:
$ref: objects.metadata.OtherObjectName
This object may be dereferenced by replacing the $ref
entry
with the object being referenced.
The following two prototypical examples are presented to clarify the semantics of
references (the cases in which they are used will be presented later):
In
objects.enums
:_GeneticLevelEnum: type: string enum: - $ref: objects.enums.Genetic.value - $ref: objects.enums.Genomic.value - $ref: objects.enums.Epigenomic.value - $ref: objects.enums.Transcriptomic.value - $ref: objects.enums.Metabolomic.value - $ref: objects.enums.Proteomic.value
and in
objects.metadata
:GeneticLevel: name: GeneticLevel display_name: Genetic Level description: | Describes the level of analysis. Values MUST be one of `"Genetic"`, `"Genomic"`, `"Epigenomic"`, `"Transcriptomic"`, `"Metabolomic"`, or `"Proteomic"`. anyOf: - $ref: objects.enums._GeneticLevelEnum - type: array items: $ref: objects.enums._GeneticLevelEnum
Here
_GeneticLevelEnum
is used to describe the valid values ofGeneticLevel
, (which are in turn references to individual values), and the references insideGeneticLevel.anyOf
indicate that there may be a single such value or a list of values.In
rules.files.deriv.preprocessed_data
:anat_nonparametric_common: $ref: rules.files.raw.anat.nonparametric entities: $ref: rules.files.raw.anat.nonparametric.entities space: optional description: optional
Here, the derivative datatype rule starts by copying the raw datatype rule
rules.files.raw.anat.nonparametric
. It then overrides theentities
portion of that rule with a new object. To extend the originalentities
, it again begins by referencingrules.files.raw.anat.nonparametric.entities
, and adding the new entitiesspace
anddescription
.
Expressions¶
Rules definitions make use of a limited language of expressions that always evaluate to true
or false
.
These expressions may be used as selectors
, determining whether a rule applies,
or checks
, determining whether a rule is satisfied.
Re-examining rules.checks.mri.PhasePartUnits
from above:
PhasePartUnits:
issue:
code: PHASE_UNITS
message: |
Phase images (with the `part-phase` entity) must have units
"rad" or "arbitrary".
level: error
selectors:
- modality == "mri"
- entities.part == "phase"
- '"Units" in sidecar'
checks:
- intersects([sidecar.Units], ["rad", "arbitrary"])
We see expressions may contain:
fields such as
modality
,entities
(which has a.part
subfield),sidecar
String literals such as
"mri"
,"Units"
or"rad"
Lists containing fields or strings
Comparison operators such as
==
(equality) orin
(subfield exists in field)Functions such as
intersects()
In fact, the full list of fields is defined in the meta.context
object,
which (currently) contains at the top level:
schema
: access to the schema itselfdataset
: attributes of the whole datasetsubject
: attributes of the current subjectpath
: the full path of the current file (relative to dataset root)entities
: an object of entities parsed from the pathdatatype
: the datatype, parsed from the pathsuffix
: the suffix, parsed from the pathextension
: the file extensionmodality
: the file modality, determined by datatypesidecar
: the metadata values, accumulated by the inheritance principleassociations
: associated files, discovered by the inheritance principlecolumns
: the columns in the current TSV filejson
: the contents of the current JSON filegzip
: the contents of the current file GZIP headernifti_header
: selected contents of the current NIfTI file’s headerome
: the contents of the current OME-XML metadatatiff
: the contents of the current TIFF file’s header
Some of these are strings, while others are nested objects. These are to be populated by an interpreter of the schema, and provide the namespace in which expressions are evaluated.
The following operators should be defined by an interpreter:
Operator |
Definition |
Example |
---|---|---|
|
equality |
|
|
inequality |
|
|
less-than / greater-than |
|
|
less-than-or-equal / greater-than-or-equal |
|
|
object lookup, true if RHS is a subfield of LHS |
|
|
negation, true if the following value is false, or vice versa |
|
|
conjunction, true if both RHS and LHS are true |
|
|
disjunction, true if either RHS or LHS is true |
|
|
object query, returns value of subfield |
|
|
array/string index, returns value of Nth element (0-indexed) |
|
|
numeric addition / string concatenation |
|
|
numeric operators (division coerces to float) |
|
The following functions should be defined by an interpreter:
Function |
Definition |
Example |
Note |
---|---|---|---|
|
Number of elements in an array equal to |
|
The number of times “EEG” appears in the column “type” of the current TSV file |
|
Count of files in an array that exist in the dataset. String is array with length 1. See following section for the meanings of rules. |
|
True if all files in |
|
Index of first element in an array equal to |
|
The number, from 0-2 corresponding to the string |
|
|
|
True if either PET or MRI data is found in dataset |
|
|
|
True if either PET or MRI data is found in dataset |
|
Number of elements in an array |
|
True if there is at least one value in the onset column |
|
|
|
True if the file extension ends with |
|
The largest non- |
|
The time of the last onset in an events.tsv file |
|
The smallest non- |
|
A check that the onset of the first slice is 0s |
|
The sorted values of the input array; defaults to type-determined sort. If method is “lexical”, or “numeric” use lexical or numeric sort. |
|
True if |
|
The portion of the input string spanning from start position to end position |
|
|
|
The name of the type, including |
|
Returns |
The exists()
function¶
In various places, BIDS datasets may declare links between files.
In order to validate these links,
the exists()
function returns a count of files that can be found within the dataset.
To accommodate the various ways of declaring these links,
the following rules are defined:
|
Definition |
Example |
---|---|---|
|
A path relative to the root of the dataset. |
|
|
A path relative to the current subject directory. |
|
|
A path relative to the |
For |
|
A path relative to the directory containing the current file. |
For |
|
A URI of the form |
|
The special value null
¶
Missing values in the context object have the special value null
.
This value propagates through all of the above operations in a fully-defined,
hopefully intuitive way.
Most operations involving null
simply resolve to null
:
Operation |
Result |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The following operators have boolean results:
Operation |
Result |
Comment |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Also |
|
|
The type()
function returns a string:
Operation |
Result |
---|---|
|
|
Finally, if an expression (selector or check) evaluates to null
,
the null
will be interpreted equivalent to false
.
That is, a null
selector will not apply the current rule, and a null
check will fail.
Object files¶
Object files define “objects” or “terms”, which are semantic descriptions of
concepts used in BIDS. These reside under the object.*
namespace in the schema.
These files do not describe how objects of different types
(for example file suffixes and file entities) interact with one another,
or whether objects are required in a given dataset or file.
Overview¶
There are currently 12 sub-namespaces, which fall into five rough categories.
The namespaces are:
Namespace |
Description |
Group |
---|---|---|
|
Terms that are used throughout BIDS |
General terms |
|
Broad categories of data represented in BIDS, roughly matching recording instrument |
General terms |
|
Name-value pairs appearing in filenames |
Name/value terms |
|
Name-value pairs appearing in JSON files |
Name/value terms |
|
Column headings and values appearing in TSV files |
Name/value terms |
|
Subdirectories that organize files by type (such as |
Value terms |
|
Filename suffixes that describe the contents of the file |
Value terms |
|
Filename component that describe the format of the file |
Value terms |
|
Terms that define the forms values (for example, in metadata) might take |
Formats |
|
Files and directories that may appear at the root of a dataset |
Files |
|
Full descriptions of enumerated values used in other sub-namespaces |
Value terms |
Because these objects vary, the contents of each namespace can vary.
Common fields to all objects:
Field |
Description |
---|---|
|
A description of the term that can be understood that should not depend on particular surrounding text; may contain markdown for rendering |
|
A human-friendly name, for tools to display; may include spaces |
The name/value terms groups (entities
, metadata
and columns
) define terms where
a name, when present, has a given meaning, and its value may be restricted.
These objects additionally have the field:
Field |
Description |
---|---|
|
For terms that can take on multiple values (such as entities, metadata fields), the name of the term as it appears in the specification and in a dataset; must be alphanumeric; mutually exclusive with |
|
The type (such as |
|
The format of the term (defined in |
Value terms groups (datatypes
, suffixes
, extensions
) define terms where a field
can take on multiple values.
For example, a file has one datatype, as compared to a collection of entities.
These objects may have the fields:
Field |
Description |
---|---|
|
For terms that cannot take on multiple values (for example suffixes or extensions), the string value of the term |
The formats
terms provide one additional field:
Field |
Description |
---|---|
|
Regular expression validating a string rendering of a value |
Value constraints¶
For name/value terms, the type
and format
fields allow constraints to be placed on
the values described by the names.
Additional fields may apply to further constrain the type:
Field |
Description |
---|---|
|
Value ranges for |
|
Value ranges for |
|
Size ranges for |
|
List of accepted values for |
Some values may be more flexible, allowing multiple possible values, or may be arrays or objects:
Field |
Description |
---|---|
|
A list of constraints, any of which could apply |
|
The array described contains values whose types are constrained |
|
The object described has a given set of fields; the values of these fields may be constrained |
|
The object described has constraints on its values, but not the names |
On re-used objects with different definitions¶
In a few cases, two objects with the same name appear multiple times in the specification. When this happens, it is preferred to find a common definition, and clarify it in the rules (see below). However, in some cases, the object description and permissible values differ, and it needs to be defined as two separate objects.
Consider the following examples:
# reference column for channels.tsv files for EEG data
reference__eeg:
name: reference
display_name: Electrode reference
description: |
Name of the reference electrode(s).
This column is not needed when it is common to all channels.
In that case the reference electrode(s) can be specified in `*_eeg.json` as `EEGReference`).
type: string
# reference column for channels.tsv files for iEEG data
reference__ieeg:
name: reference
display_name: Electrode reference
description: |
Specification of the reference (for example, `mastoid`, `ElectrodeName01`, `intracranial`, `CAR`, `other`, `n/a`).
If the channel is not an electrode channel (for example, a microphone channel) use `n/a`.
anyOf:
- type: string
- type: string
enum:
- n/a
Here, the TSV column "reference"
means different things when used for EEG data,
as compared to iEEG data, so two definitions are needed.
Because columns use snake_case
(meaning they can be expected to contain underscores),
two underscores are needed to separate the column name from the string that indicates the use of the term.
The convention can be summed up in the following rules:
Each specific term takes on the form
<term>_<context>
, where<term>
is the common name that the two (or more) terms share,<context>
indicates when the specific term applies.If the
<term>
appears insnake_case
then<context>
begins with an extra_
.
Valid fields for definitions by sub-namespace¶
objects.common_principles
Field
Description
display_name
Human-friendly name
description
Term definition
objects.modalities
Field
Description
display_name
Human-friendly name
description
Term definition
objects.entities
Field
Description
display_name
Human-friendly name
description
Term definition
name
Key of entity, such as
sub
orses
type
Type of value (always
string
)format
Permissible format of values, either
label
orindex
enum
Exclusive list of valid values, if present
Note that descriptions should apply to all uses of the entity; if additional information applies in certain contexts, that should be written in the specification, and not the schema.
objects.metadata
Field
Description
display_name
Human-friendly name
description
Term definition
name
Name of field in JSON object (in
CamelCase
)unit
Interpretation of numeric values
type
Type of value (one of
array
,string
,integer
,number
,object
orboolean
)format
Permissible format of values, from definitions in
objects.formats
enum
Exclusive list of valid values, if present
maximum
Maximum for numeric values
minimum
Minimum for numeric values
*
JSON-schema fields to further constrain values
objects.columns
Field
Description
display_name
Human-friendly name
description
Term definition
name
Name of column in TSV file (in
snake_case
)unit
Interpretation of numeric values
type
Type of value
format
Permissible format of values, from definitions in
objects.formats
pattern
Regular expression constraining string values
enum
Exclusive list of valid values, if present
maximum
Maximum for numeric values
minimum
Minimum for numeric values
*
JSON-schema fields to further constrain values
objects.datatypes
Field
Description
display_name
Human-friendly name
description
Term definition
value
String value of
datatype
objects.suffixes
Field
Description
display_name
Human-friendly name
description
Term definition
value
String value of
suffix
unit
Interpretation of values in a data file with the given suffix
maxValue
Maximum permissible value in a data file with the given suffix
minValue
Minimum permissible value in a data file with the given suffix
anyOf
Used to describe multiple permissible units
objects.extensions
Field
Description
display_name
Human-friendly name
description
Term definition
value
String value of
extension
objects.formats
Field
Description
display_name
Human-friendly name
description
Term definition
pattern
Regular expression defining format
objects.files
Field
Description
display_name
Human-friendly name
description
Term definition
file_type
Indicator that the file is a regular file (
"regular"
) or directory ("directory"
)objects.enums
Field
Description
display_name
Human-friendly name
description
Term definition
value
String value of
enum
Rule files¶
The rules.*
namespace contains most of the validatable content of the schema,
apart from value constraints that can be encoded in objects
.
There are several types of rule, and this section is subject to reconsolidation as patterns are found.
Core concepts¶
Core concepts are expressions (defined above), requirement levels and issues.
Requirement levels and severity¶
BIDS follows RFC 2119 and has three requirement levels: OPTIONAL, RECOMMENDED and REQUIRED.
In the schema, we use optional
, recommended
and required
.
A rule interpreter (validator) is expected to treat:
missing REQUIRED data/metadata as an error,
missing RECOMMENDED data/metadata as a warning,
and silently pass over missing OPTIONAL data.
BIDS also defines a level DEPRECATED
, rendered in the schema as deprecated
,
and corresponding to a warning if the data/metadata is present.
Issues¶
Issues are messages intended to be communicated to a dataset curator to indicate an issue with their dataset.
They have a code and severity as well:
Field |
Description |
---|---|
|
Issue identifier, such as |
|
Issue severity ( |
|
Message for display to a user |
A level of warning
corresponds to a rule in the specification that is RECOMMENDED,
while a level of error
corresponds to a rule that is REQUIRED.
In some cases, an issue is contained next to a level: required
or level: recommended
as part of a larger rule.
In these cases, the level
field should be omitted from the issue
to avoid duplication or conflict.
Filename construction rules¶
A significant portion of BIDS is devoted to the naming of files, and almost all filenames consist of entities, a suffix, an extension, and a data type. Exceptions will be noted below.
rules.files
contains the following subdivisions.
Namespace |
Description |
---|---|
|
Files and directories that reside at the top level of datasets |
|
Tabular metadata files that associate metadata with entities |
|
Raw data and metadata files that have entities, suffixes, datatypes and extensions |
|
Derivative data and metadata files that have entities, suffixes, datatypes and extensions |
Core files and directories¶
rules.files.common.core
describes files that have little-to-no variability in their form.
These either have a single path
field, or a stem
field and a list of extensions
:
Field |
Description |
---|---|
|
Requirement level of file, one of ( |
|
Location of file, relative to dataset root; mutually exclusive with |
|
Name of file, relative to dataset root, up to but not including the extension; mutually exclusive with |
|
List of valid extension strings, including the initial dot ( |
These are the entries for dataset_description.json
and README
:
dataset_description:
level: required
path: dataset_description.json
README:
level: required
stem: README
extensions:
- ''
- .md
- .rst
- .txt
Here, README
and README.md
are both valid, while only dataset_description.json
is permitted.
Tabular metadata files¶
rules.files.common.tables
describes TSV files and their associated metadata,
including participants.tsv
, samples.tsv
, *_sessions.tsv
and *_scans.tsv
.
The first two use the stem
field, while the latter two specify the entities used
to construct the filename.
The valid fields are:
Field |
Description |
---|---|
|
Requirement level of file, one of ( |
|
Name of file, relative to dataset root, up to but not including the extension; mutually exclusive with |
|
Object where the keys are entries in |
|
List of valid extension strings, including the initial dot ( |
For example:
participants:
level: optional
stem: participants
extensions:
- .tsv
- .json
sessions:
suffixes:
- sessions
extensions:
- .tsv
- .json
entities:
subject: required
Note that these files do not have a datatype
, but otherwise follow the same rules as above.
BIDS filenames¶
rules.files.raw
and rules.files.deriv
contain series of related rules.
These are largely grouped by datatype, but file types that appear in multiple locations may be grouped together.
The files described take the form:
[sub-<label>/][ses-<label>/]<datatype>/<entities>_<suffix><extension>
Rules have the following fields:
Field |
Description |
---|---|
|
List of suffixes found in |
|
List of valid extension strings, including initial dot ( |
|
List of datatypes found in |
|
Object where the keys are entries in |
Field |
Requirement level |
Description |
---|---|---|
|
REQUIRED |
Requirement level of field, one of ( |
|
OPTIONAL |
Override of entity field - Permissible format of values, either |
|
OPTIONAL |
Override of entity field - Exclusive list of valid values, if present |
As an example, let us look at a (modified) part of meg.yaml
:
meg:
suffixes:
- meg
extensions:
- .fif
datatypes:
- meg
entities:
subject: required
session: optional
task: required
acquisition: optional
run: optional
processing: optional
split: optional
crosstalk:
suffixes:
- meg
extensions:
- .fif
datatypes:
- meg
entities:
subject: required
session: optional
acquisition:
level: required
enum:
- crosstalk
In this case, the first group has one suffix: meg
.
The second group has the same suffix (meg
), but describes different rules for files with that suffix.
While the valid extension is the same for both groups (.fif
), the entities are not.
Specifically, files in the first group may have task
, run
, processing
, and split
entities,
while files in the second group may not.
Also, when files in the second group have the acq
entity, the associated value MUST be crosstalk
.
A common derivatives type is preprocessed data, where the type of the generated data is the same
as the input data.
BIDS Derivatives specifies that these files may be distinguished from raw data
with the new entities space-<label>
or desc-<label>
.
This rule is encoded:
meg_meg_common:
$ref: rules.files.raw.meg.meg
entities:
$ref: rules.files.raw.meg.meg.entities
space: optional
description: optional
When expanded, this becomes:
meg_meg_common:
suffixes:
- meg
extensions:
- .fif
datatypes:
- meg
entities:
subject: required
session: optional
task: required
acquisition: optional
run: optional
processing: optional
split: optional
space: optional
description: optional
Sidecar and tabular data rules¶
Tabular data and JSON sidecar files follow a similar pattern:
Name |
Value |
|
---|---|---|
JSON |
field |
value |
TSV |
column header |
column values |
In the specification, groups of fields/columns are described together in a table
that includes the name of the field/column, the requirement level and a description.
The definitions, including name and description, appear in objects.metadata
,
and the columns appear in objects.columns
.
Here, we define YAML “tables” that can be rendered in the specification. These take the form:
RuleName:
selectors:
- expression1
- expression2
fields:
- FieldName1:
level: recommended
level_addendum: required if XYZ
description_addendum: Additional text following object description.
- FieldName2: optional
RuleNameReq:
selectors:
- expression1
- expression2
- expression3
fields:
- FieldName1:
level: required
issue:
code: ISSUE_NAME
message: A description of the problem for a user
Here we show an example of two fields, one that is RECOMMENDED in most cases but REQUIRED in another, the other of which is OPTIONAL.
selectors
indicate whether the current rule applies to a given file.
This is not rendered in the text, but may be used by a validator.
fields
is an object with keys that appear in objects.metadata
/objects.columns
.
If the value is a string, then it is a requirement level.
If it is an object, then the it has the following fields
Field |
Requirement level |
Description |
---|---|---|
|
REQUIRED |
Requirement level of field, one of ( |
|
OPTIONAL |
Additional text to describe cases where requirement level changes |
|
OPTIONAL |
Additional text to follow the |
|
OPTIONAL |
issue object, if additional communication is warranted |
The second table implements the change in the first table’s level_addendum
.
The expression3
selector indicates the additional case where the more stringent
rule is applied.
Valid fields for definitions¶
rules.sidecars.*
Field
Description
selectors
List of expressions; any evaluating false indicate rule does not apply
fields
Object with keys that may be found in
objects.metadata
, values either a requirement level or an objectrules.tabular_data.*
Field
Description
selectors
List of expressions; any evaluating false indicate rule does not apply
columns
Object with keys that may be found in
objects.columns
, values either a requirement level or an objectinitial_columns
An optional list of columns that must be the first N columns of a file
index_columns
An optional list of columns that uniquely identify a row.
additional_columns
Indicates whether additional columns may be defined. One of
allowed
,allowed_if_defined
andnot_allowed
.
The following tables demonstrate how mutual exclusive, required fields,
may be set in rules.sidecars.*
:
MRIFuncRepetitionTime:
selectors:
- modality == "mri"
- datatype == "func"
- '!("VolumeTiming" in sidecar)'
- match(extension, "^\.nii(\.gz)?$")
fields:
RepetitionTime:
level: required
level_addendum: mutually exclusive with `VolumeTiming`
MRIFuncVolumeTiming:
selectors:
- modality == "mri"
- datatype == "func"
- '!("RepetitionTime" in sidecar)'
- match(extension, "^\.nii(\.gz)?$")
fields:
VolumeTiming:
level: required
level_addendum: mutually exclusive with `RepetitionTime`
An additional check will be required to assert that both are not present, but these tables may be combined for rendering purposes.
Here we present an example rule in rules.tabular_data.eeg
:
EEGChannels:
selectors:
- datatype == "eeg"
- suffix == "channels"
- extension == ".tsv"
initial_columns:
- name__channels
- type__channels
- units
columns:
name__channels: required
type__channels: required
units: required
description: optional
sampling_frequency: optional
reference: optional
low_cutoff: optional
high_cutoff: optional
notch: optional
status: optional
status_descriptions: optional
additional_columns: allowed_if_defined
Checks¶
rules.checks
can contain more complex rules. Structurally, these are similar to sidecar rules,
in that they have selectors.
They additionally have a checks
list, and an explicit issue.
Field |
Description |
---|---|
|
Issue code object (see Issues |
|
List of expressions; any evaluating false indicate rule does not apply |
|
List of expressions; any evaluating false indicate rule is violated and issue should be raised |
EventsMissing:
issue:
code: EVENTS_TSV_MISSING
message: |
Task scans should have a corresponding events.tsv file.
If this is a resting state scan you can ignore this warning or rename the task to include the word "rest".
level: warning # could be an error with the proper selectors, I think
selectors:
- '"task" in entities'
- '!match(entities.task, "rest")'
- suffix != "events"
checks:
- '"events" in associations'
Ordering rules¶
rules.entities
- This file contains a list of keys intoobjects.entities
and simply defines the order in which entities, when present, MUST appear in filenamesrules.common_principles
- This file contains a list of terms that appear inobjects.common_principles
that determines the order they appear in the specification
One-off rules¶
rules.modalities
- The keys in this file are the modalities, the values objects with the following field:Field
Description
datatypes
List of datatypes mapping to modality
rules.dataset_metadata
- These are similar torules.sidecars.*
, for JSON files at the root level. This is likely to go away in favor of other approaches.rules.errors
- This file describes errors that cannot be expressed in the schema. This provides common codes and language that implementing validators can use to ensure the same problems are reported to users in the same way.
Version of the schema¶
File SCHEMA_VERSION
in the top of the directory contains a semantic
version (MAJOR.MINOR.PATCH
) for the schema (how it is organized).
Note that while in 0.
series, breaking changes are
permitted without changing the MAJOR
(leading) component of the version.
Going forward, the 2nd, MINOR
indicator should be
incremented whenever schema organization introduces “breaking changes”:
changes which would cause existing tools reading schema to
adjust their code to be able to read it again.
Additions of new components to the schema should increment the last,
PATCH
, component of the version so that tools could selectively
enable/disable loading specific components of the schema.
With the release of 1.0.0
version of the schema,
we expect that the MAJOR
component
will be incremented whenever schema organization introduces “breaking changes”,
MINOR
- when adding new components to the schema,
and PATCH
- when fixing errors in existing components.
Schema publication¶
The BIDS Schema is compiled into a single, dereferenced object during
the ReadTheDocs build of the specification.
This object is published as a JSON document that can be found at /schema.json
at the root of the specification.
For example, the schema used to construct the 1.8.0 release of BIDS can be found at
https://bids-specification.readthedocs.io/en/v1.8.0/schema.json,
and the latest version that includes unreleased changes to BIDS and the schema may
be found at https://bids-specification.readthedocs.io/en/latest/schema.json.
The JSON version of the schema contains schema_version
and bids_version
keys
that identify the state of both the schema and the specification at the time it was
compiled.
Metaschema¶
The metaschema.json
file is a meta-schema that uses the JSON Schema language to
formalize the allowable directories, files, fields and values of the BIDS schema,
ensuring consistency across the entire schema directory. Validation of the schema is
incorporated into the CI, so any changes that are inconsistent will be flagged before
inclusion.