Skill Tracer
Skills › Scientific Agent Skills › bids › bids_specification.md

bids_specification.md

163 lines · skills/bids/references/bids_specification.md at 5f2bc03

Open on GitHub
1# BIDS Specification Reference
2
3> **Note**: The canonical, machine-readable source of truth is `bids_schema.json` (in this directory), exported from the [BIDS Schema](https://github.com/bids-standard/bids-specification/tree/master/src/schema). The tables below are a human-readable summary. Snapshot reviewed against BIDS 1.11.2 / schema 2.0.0 on 2026-09-30. Read rule selectors and prose together; field definitions alone do not establish requiredness.
4

BIDS Specification Reference

Note: The canonical, machine-readable source of truth is bids_schema.json (in this directory), exported from the BIDS Schema. The tables below are a human-readable summary. Snapshot reviewed against BIDS 1.11.2 / schema 2.0.0 on 2026-09-30. Read rule selectors and prose together; field definitions alone do not establish requiredness.
Raw lines 1 to 4
5## Entity Table
6
7Complete list of BIDS entities, their keys, and where they apply. **Rows are listed in the required filename ordering** — entities must appear in this order in BIDS filenames. This order is defined in the schema at `rules.entities` (see `bids_schema.json`).
8
9| # | Entity | Key | Format | Applies to |
10|---|--------|-----|--------|------------|
11| 1 | Subject | `sub-` | `<label>` | Subject-specific raw data (not dataset-level files) |
12| 2 | Template | `tpl-` | `<label>` | derivatives (template-based) |
13| 3 | Session | `ses-` | `<label>` | All datatypes |
14| 4 | Cohort | `cohort-` | `<label>` | derivatives (template cohorts) |
15| 5 | Sample | `sample-` | `<label>` | microscopy |
16| 6 | Task | `task-` | `<label>` | func, eeg, meg, ieeg, beh, pet, nirs, motion |
17| 7 | Tracking system | `tracksys-` | `<label>` | motion |
18| 8 | Acquisition | `acq-` | `<label>` | All datatypes |
19| 9 | Nucleus | `nuc-` | `<label>` | MR spectroscopy |
20| 10 | Volume | `voi-` | `<label>` | MR spectroscopy |
21| 11 | Contrast enhancing agent | `ce-` | `<label>` | anat |
22| 12 | Tracer | `trc-` | `<label>` | pet |
23| 13 | Stain | `stain-` | `<label>` | microscopy |
24| 14 | Reconstruction | `rec-` | `<label>` | anat, func, pet |
25| 15 | Direction | `dir-` | `<label>` | fmap, dwi, perf, func |
26| 16 | Run | `run-` | `<index>` (integer) | All datatypes |
27| 17 | Modality | `mod-` | `<label>` | fieldmaps |
28| 18 | Echo | `echo-` | `<index>` | func, fmap |
29| 19 | Flip | `flip-` | `<index>` | anat (quantitative MRI) |
30| 20 | Inversion | `inv-` | `<index>` | anat (quantitative MRI) |
31| 21 | Magnetization transfer | `mt-` | `on`/`off` | anat (quantitative MRI) |
32| 22 | Part | `part-` | `mag`/`phase`/`real`/`imag` | anat, func |
33| 23 | Processing | `proc-` | `<label>` | eeg, meg, ieeg |
34| 24 | Hemisphere | `hemi-` | `L`/`R` | derivatives (surface data) |
35| 25 | Space | `space-` | `<label>` | derivatives |
36| 26 | Split | `split-` | `<index>` | func, dwi, eeg, meg, ieeg |
37| 27 | Recording | `recording-` | `<label>` | physio, stim, eeg, meg |
38| 28 | Chunk | `chunk-` | `<index>` | large files split across chunks |
39| 29 | Atlas | `atlas-` | `<label>` | derivatives (atlas-based) |
40| 30 | Segmentation | `seg-` | `<label>` | derivatives |
41| 31 | Scale | `scale-` | `<label>` | derivatives |
42| 32 | Resolution | `res-` | `<label>` | derivatives |
43| 33 | Density | `den-` | `<label>` | derivatives (surface meshes) |
44| 34 | Label | `label-` | `<label>` | derivatives (segmentation labels) |
45| 35 | Description | `desc-` | `<label>` | derivatives only |

Entity Table

Complete list of BIDS entities, their keys, and where they apply. Rows are listed in the required filename ordering — entities must appear in this order in BIDS filenames. This order is defined in the schema at rules.entities (see bids_schema.json).

#EntityKeyFormatApplies to
1Subjectsub-<label>Subject-specific raw data (not dataset-level files)
2Templatetpl-<label>derivatives (template-based)
3Sessionses-<label>All datatypes
4Cohortcohort-<label>derivatives (template cohorts)
5Samplesample-<label>microscopy
6Tasktask-<label>func, eeg, meg, ieeg, beh, pet, nirs, motion
7Tracking systemtracksys-<label>motion
8Acquisitionacq-<label>All datatypes
9Nucleusnuc-<label>MR spectroscopy
10Volumevoi-<label>MR spectroscopy
11Contrast enhancing agentce-<label>anat
12Tracertrc-<label>pet
13Stainstain-<label>microscopy
14Reconstructionrec-<label>anat, func, pet
15Directiondir-<label>fmap, dwi, perf, func
16Runrun-<index> (integer)All datatypes
17Modalitymod-<label>fieldmaps
18Echoecho-<index>func, fmap
19Flipflip-<index>anat (quantitative MRI)
20Inversioninv-<index>anat (quantitative MRI)
21Magnetization transfermt-on/offanat (quantitative MRI)
22Partpart-mag/phase/real/imaganat, func
23Processingproc-<label>eeg, meg, ieeg
24Hemispherehemi-L/Rderivatives (surface data)
25Spacespace-<label>derivatives
26Splitsplit-<index>func, dwi, eeg, meg, ieeg
27Recordingrecording-<label>physio, stim, eeg, meg
28Chunkchunk-<index>large files split across chunks
29Atlasatlas-<label>derivatives (atlas-based)
30Segmentationseg-<label>derivatives
31Scalescale-<label>derivatives
32Resolutionres-<label>derivatives
33Densityden-<label>derivatives (surface meshes)
34Labellabel-<label>derivatives (segmentation labels)
35Descriptiondesc-<label>derivatives only
Raw lines 5 to 46
47## Datatypes (Top-Level Directories)
49| Datatype | Description | Common Suffixes |
50|----------|-------------|-----------------|
51| `anat` | Structural MRI | `T1w`, `T2w`, `FLAIR`, `T2starw`, `inplaneT1`, `inplaneT2`, `PDw`, `T1map`, `T2map`, `T1rho`, `UNIT1`, `MP2RAGE`, `MTR`, `MTS` |
52| `func` | Functional MRI | `bold`, `cbv`, `sbref` |
53| `dwi` | Diffusion-weighted imaging | `dwi`, `sbref` |
54| `fmap` | Fieldmaps | `phasediff`, `phase1`, `phase2`, `magnitude1`, `magnitude2`, `fieldmap`, `epi` |
55| `perf` | Perfusion imaging (ASL) | `asl`, `m0scan`, `aslcontext` |
56| `eeg` | Electroencephalography | `eeg`, `channels`, `electrodes`, `events`, `coordsystem` |
57| `meg` | Magnetoencephalography | `meg`, `channels`, `coordsystem`, `events`, `headshape` |
58| `ieeg` | Intracranial EEG | `ieeg`, `channels`, `electrodes`, `events`, `coordsystem` |
59| `pet` | Positron Emission Tomography | `pet`, `blood` |
60| `micr` | Microscopy | `2PE`, `BF`, `CARS`, `CONF`, `DIC`, `DF`, `FLUO`, `MPE`, `NLO`, `OCT`, `PC`, `PLI`, `SRS`, `XPCT` |
61| `beh` | Behavioral data (no imaging) | `events`, `beh`, `physio`, `stim` |
62| `motion` | Motion capture | `motion`, `channels`, `events` |
63| `nirs` | Near-infrared spectroscopy | `nirs`, `channels`, `optodes`, `coordsystem`, `events` |
64| `mrs` | MR spectroscopy | `svs`, `mrsi`, `unloc` |
65| `emg` | Electromyography | `emg`, `channels`, `electrodes`, `coordsystem`, `events` |
66| `phenotype` | Dataset-level phenotypic tables | questionnaire-specific TSV names |

Datatypes (Top-Level Directories)

DatatypeDescriptionCommon Suffixes
anatStructural MRIT1w, T2w, FLAIR, T2starw, inplaneT1, inplaneT2, PDw, T1map, T2map, T1rho, UNIT1, MP2RAGE, MTR, MTS
funcFunctional MRIbold, cbv, sbref
dwiDiffusion-weighted imagingdwi, sbref
fmapFieldmapsphasediff, phase1, phase2, magnitude1, magnitude2, fieldmap, epi
perfPerfusion imaging (ASL)asl, m0scan, aslcontext
eegElectroencephalographyeeg, channels, electrodes, events, coordsystem
megMagnetoencephalographymeg, channels, coordsystem, events, headshape
ieegIntracranial EEGieeg, channels, electrodes, events, coordsystem
petPositron Emission Tomographypet, blood
micrMicroscopy2PE, BF, CARS, CONF, DIC, DF, FLUO, MPE, NLO, OCT, PC, PLI, SRS, XPCT
behBehavioral data (no imaging)events, beh, physio, stim
motionMotion capturemotion, channels, events
nirsNear-infrared spectroscopynirs, channels, optodes, coordsystem, events
mrsMR spectroscopysvs, mrsi, unloc
emgElectromyographyemg, channels, electrodes, coordsystem, events
phenotypeDataset-level phenotypic tablesquestionnaire-specific TSV names
Raw lines 47 to 67
68## File Extensions
70| Extension | Description |
71|-----------|-------------|
72| `.nii.gz` | Compressed NIfTI (standard for MRI/fMRI/DWI) |
73| `.nii` | Uncompressed NIfTI |
74| `.json` | JSON sidecar metadata |
75| `.tsv` | Tab-separated values (events, participants, etc.) |
76| `.bvec` | b-vectors (DWI gradient directions) |
77| `.bval` | b-values (DWI gradient strengths) |
78| `.edf` | European Data Format (EEG) |
79| `.bdf` | BioSemi Data Format (EEG) |
80| `.vhdr`/`.vmrk`/`.eeg` | BrainVision format (EEG) |
81| `.set` | EEGLAB format (EEG) |
82| `.fif` | Elekta/MEGIN format (MEG) |
83| `.ds` | CTF dataset (MEG) |
84| `.sqd`/`.con` | KIT/Yokogawa (MEG) |

File Extensions

ExtensionDescription
.nii.gzCompressed NIfTI (standard for MRI/fMRI/DWI)
.niiUncompressed NIfTI
.jsonJSON sidecar metadata
.tsvTab-separated values (events, participants, etc.)
.bvecb-vectors (DWI gradient directions)
.bvalb-values (DWI gradient strengths)
.edfEuropean Data Format (EEG)
.bdfBioSemi Data Format (EEG)
.vhdr/.vmrk/.eegBrainVision format (EEG)
.setEEGLAB format (EEG)
.fifElekta/MEGIN format (MEG)
.dsCTF dataset (MEG)
.sqd/.conKIT/Yokogawa (MEG)
Raw lines 68 to 85
86## Required Files

Required Files

Raw lines 86 to 87
88### Dataset-level (always required)
89- `dataset_description.json`

Dataset-level (always required)

  • dataset_description.json
Raw lines 88 to 90
91### Dataset-level (recommended)
92- `README` or `README.md`
93- `CHANGES`
94- `participants.tsv` + `participants.json`
95- `LICENSE`

Dataset-level (recommended)

  • README or README.md
  • CHANGES
  • participants.tsv + participants.json
  • LICENSE
Raw lines 91 to 96
97### Run-level (recommended)
98- `sub-<label>/[ses-<label>/]sub-<label>[_ses-<label>]_scans.tsv` - per-run acquisition metadata

Run-level (recommended)

  • sub-<label>/[ses-<label>/]sub-<label>[_ses-<label>]_scans.tsv - per-run acquisition metadata
Raw lines 97 to 99
100### Modality-specific required files
101- **func/bold**: `TaskName` plus valid volume timing metadata; describe recorded events in `_events.tsv` (not every task has recorded events)
102- **dwi**: `.bvec` and `.bval` files
103- **eeg/meg/ieeg**: consult datatype rules for channel tables and event recordings; iEEG requires electrodes and coordinate metadata. Requirements differ by datatype and format
104- **perf/asl**: `_aslcontext.tsv`

Modality-specific required files

  • func/bold: TaskName plus valid volume timing metadata; describe recorded events in _events.tsv (not every task has recorded events)
  • dwi: .bvec and .bval files
  • eeg/meg/ieeg: consult datatype rules for channel tables and event recordings; iEEG requires electrodes and coordinate metadata. Requirements differ by datatype and format
  • perf/asl: _aslcontext.tsv
Raw lines 100 to 105
106## Directory Structure Rules
1081. Subject directories are named `sub-<label>` and sit at dataset root
1092. For multi-session subjects, use `ses-<label>` directories. When any subject has multiple sessions, this layer SHOULD be added for all subjects (not a universal MUST)
1103. Datatype directories (`anat/`, `func/`, etc.) sit inside subject (or session) directories
1114. `sourcedata/` stores raw unprocessed data (DICOM, etc.) - not validated
1125. `derivatives/` stores processed outputs - each pipeline in its own subdirectory
1136. `code/` stores analysis scripts
1147. `stimuli/` stores stimulus files used during acquisition
1158. `phenotype/` stores questionnaire/behavioral data not tied to specific imaging

Directory Structure Rules

  1. Subject directories are named sub-<label> and sit at dataset root
  2. For multi-session subjects, use ses-<label> directories. When any subject has multiple sessions, this layer SHOULD be added for all subjects (not a universal MUST)
  3. Datatype directories (anat/, func/, etc.) sit inside subject (or session) directories
  4. sourcedata/ stores raw unprocessed data (DICOM, etc.) - not validated
  5. derivatives/ stores processed outputs - each pipeline in its own subdirectory
  6. code/ stores analysis scripts
  7. stimuli/ stores stimulus files used during acquisition
  8. phenotype/ stores questionnaire/behavioral data not tied to specific imaging
Raw lines 106 to 116
117## Metadata Inheritance
119JSON metadata cascades from higher to lower directories. If the same key appears at multiple levels, the most specific (closest to the data file) wins.
121**Resolution order** (highest priority first):
1221. File-level sidecar: `sub-01/func/sub-01_task-rest_bold.json`
1232. Subject-level sidecar: `sub-01/sub-01_task-rest_bold.json`
1243. Dataset-level sidecar: `task-rest_bold.json`
126This avoids duplicating metadata that is constant across subjects (e.g., `RepetitionTime`, `TaskName`).

Metadata Inheritance

JSON metadata cascades from higher to lower directories. If the same key appears at multiple levels, the most specific (closest to the data file) wins.

Resolution order (highest priority first):

  1. File-level sidecar: sub-01/func/sub-01_task-rest_bold.json
  2. Subject-level sidecar: sub-01/sub-01_task-rest_bold.json
  3. Dataset-level sidecar: task-rest_bold.json

This avoids duplicating metadata that is constant across subjects (e.g., RepetitionTime, TaskName).

Raw lines 117 to 127
128## Standard Template Spaces
130Common `space-` values used in derivatives:
132| Space Label | Description |
133|-------------|-------------|
134| `MNI152NLin2009cAsym` | MNI 2009c nonlinear asymmetric (fMRIPrep default) |
135| `MNI152NLin6Asym` | MNI 6th-generation nonlinear asymmetric (FSL default) |
136| `MNI152Lin` | MNI linear registration |
137| `MNIPediatricAsym` | Pediatric MNI templates |
138| `T1w` | Individual subject's T1w native space |
139| `fsnative` | FreeSurfer individual surface space |
140| `fsaverage` | FreeSurfer average surface (164k vertices) |
141| `fsaverage5` | FreeSurfer average surface (10k vertices) |
142| `fsaverage6` | FreeSurfer average surface (40k vertices) |
143| `fsLR` | HCP fs_LR surface space |
144| `OASIS30ANTs` | OASIS-30 ANTs template |
145| `UNCInfant` | UNC infant templates |
147Use the [BIDS coordinate-system identifiers](https://bids-specification.readthedocs.io/en/stable/appendices/coordinate-systems.html); TemplateFlow provides many reference resources: https://www.templateflow.org/. Pipeline aliases such as fsaverage5/fsaverage6 may encode density; confirm the target output convention.

Standard Template Spaces

Common space- values used in derivatives:

Space LabelDescription
MNI152NLin2009cAsymMNI 2009c nonlinear asymmetric (fMRIPrep default)
MNI152NLin6AsymMNI 6th-generation nonlinear asymmetric (FSL default)
MNI152LinMNI linear registration
MNIPediatricAsymPediatric MNI templates
T1wIndividual subject's T1w native space
fsnativeFreeSurfer individual surface space
fsaverageFreeSurfer average surface (164k vertices)
fsaverage5FreeSurfer average surface (10k vertices)
fsaverage6FreeSurfer average surface (40k vertices)
fsLRHCP fs_LR surface space
OASIS30ANTsOASIS-30 ANTs template
UNCInfantUNC infant templates

Use the BIDS coordinate-system identifiers; TemplateFlow provides many reference resources: https://www.templateflow.org/. Pipeline aliases such as fsaverage5/fsaverage6 may encode density; confirm the target output convention.

Raw lines 128 to 148
149## Recent specification changes
151The [official changelog](https://bids-specification.readthedocs.io/en/stable/CHANGES.html)
152is the maintained version history. BIDS 1.11.2 adds OME-Zarr imaging support and
153PET surface-map derivatives, accepts institutional authors, and requires complete
154BrainVision triplets in the schema. BIDS 1.11.0 added eye tracking, atlases and EMG;
1551.10.0 added MR spectroscopy. These are specification versions, not validator versions.

Recent specification changes

The official changelog is the maintained version history. BIDS 1.11.2 adds OME-Zarr imaging support and PET surface-map derivatives, accepts institutional authors, and requires complete BrainVision triplets in the schema. BIDS 1.11.0 added eye tracking, atlases and EMG; 1.10.0 added MR spectroscopy. These are specification versions, not validator versions.

Raw lines 149 to 156
157## Entity Label Rules
159- **Labels** (`<label>`): alphanumeric with `+` allowed; leading zeros are allowed; labels must not collide when case is ignored
160- **Indices** (`<index>`): non-negative integers, optionally zero-padded for consistent width; padding does not create a distinct numeric index (e.g., `run-01`, `run-02`)
161- Subject labels: typically numeric (`01`, `02`) but can be alphanumeric (`CON01`, `PAT01`)
162- Session labels: descriptive (`pre`, `post`, `baseline`, `followup`) or numeric
163- Task labels: brief, descriptive, no spaces (`rest`, `nback`, `faces`, `gonogo`)

Entity Label Rules

  • Labels (<label>): alphanumeric with + allowed; leading zeros are allowed; labels must not collide when case is ignored
  • Indices (<index>): non-negative integers, optionally zero-padded for consistent width; padding does not create a distinct numeric index (e.g., run-01, run-02)
  • Subject labels: typically numeric (01, 02) but can be alphanumeric (CON01, PAT01)
  • Session labels: descriptive (pre, post, baseline, followup) or numeric
  • Task labels: brief, descriptive, no spaces (rest, nback, faces, gonogo)
Raw lines 157 to 163