From 6d7eb0fa8e40e481440976a353bb02d451935db5 Mon Sep 17 00:00:00 2001
From: Taylor Salo <tsalo006@fiu.edu>
Date: Tue, 27 Jun 2023 04:55:56 -0400
Subject: [PATCH] [SCHEMA] Add full object definitions for valid values in
 schema (#919)

* Add some descriptions. Mostly just TODOs for now.

* Start rendering value restrictions in descriptions.

* Fix.

* Revert rendering. Will move to separate PR.

* Run black.

* Add more enum descriptions.

* Add nonstandard and non-template coordinate systems.

I'm not 100% sure about this one. I grabbed values from the coordinate systems appendix.

* Fix linting issues.

* Run prettier.

* Make the expanded enums into objects.

* Fix up rendering, hopefully.

* Update metadata.yaml

* Update render.py

* whoops.

* Update render.py

* Whoops!

* Finish resolving conflicts.

* Move enums to a separate file.

* Fix on and off.

* Remove duplicate keys.

* Start adding channel type values.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Add EEG columns.

* Remove empty entries.

* Add MEG channels.

* Add NIRS channels.

* Try fixing the formatting.

* Fix.

* OTHER sex isn't the same as OTHER channel type.

* Consolidate channels enums across datatypes.

* Replace name with value.

* Replicate #1478.

* Add .value to value refs.

* Add tags to channel values.

* ENH: Allow for dereferencing individual values in schema

* Rename values to enum.

* Rename enum to enum_values.

* Fix test.

* Rename and move enums around.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update columns.yaml

* Document new sub-namespace.

* Fix table.

* Remove unused enum groups.

* Apply suggestions from code review

Co-authored-by: Chris Markiewicz <effigies@gmail.com>

* Update the other direction enum defs.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Chris Markiewicz <effigies@gmail.com>
Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
---
 src/schema/README.md                          |   14 +-
 src/schema/objects/columns.yaml               |  199 +--
 src/schema/objects/entities.yaml              |   16 +-
 src/schema/objects/enums.yaml                 | 1089 +++++++++++++++++
 src/schema/objects/metadata.yaml              |  236 ++--
 src/schema/rules/files/raw/meg.yaml           |    2 +
 src/schema/rules/tabular_data/eeg.yaml        |    4 +-
 src/schema/rules/tabular_data/ieeg.yaml       |    4 +-
 src/schema/rules/tabular_data/meg.yaml        |    4 +-
 src/schema/rules/tabular_data/motion.yaml     |    4 +-
 src/schema/rules/tabular_data/nirs.yaml       |    4 +-
 .../schemacode/bidsschematools/render/text.py |   44 +-
 .../bidsschematools/render/utils.py           |    8 +-
 tools/schemacode/bidsschematools/rules.py     |    9 +-
 tools/schemacode/bidsschematools/schema.py    |   38 +-
 .../bidsschematools/tests/test_schema.py      |   33 +
 16 files changed, 1356 insertions(+), 352 deletions(-)
 create mode 100644 src/schema/objects/enums.yaml

diff --git a/src/schema/README.md b/src/schema/README.md
index 94cd868d7e..b61740bbcc 100644
--- a/src/schema/README.md
+++ b/src/schema/README.md
@@ -336,7 +336,7 @@ or whether objects are required in a given dataset or file.
 
 ### Overview
 
-There are currently 11 sub-namespaces, which fall into five rough categories.
+There are currently 12 sub-namespaces, which fall into five rough categories.
 
 The namespaces are:
 
@@ -352,6 +352,7 @@ The namespaces are:
 | `objects.extensions`        | Filename component that describe the format of the file                             | Value terms      |
 | `objects.formats`           | Terms that define the forms values (for example, in metadata) might take            | Formats          |
 | `objects.files`             | Files and directories that may appear at the root of a dataset                      | Files            |
+| `objects.enums`             | Full descriptions of enumerated values used in other sub-namespaces                 | Value terms      |
 
 Because these objects vary, the contents of each namespace can vary.
 
@@ -554,6 +555,13 @@ The convention can be summed up in the following rules:
     | `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,
@@ -910,11 +918,11 @@ EEGChannels:
   - extension == ".tsv"
   initial_columns:
   - name__channels
-  - type__eeg_channels
+  - type__channels
   - units
   columns:
     name__channels: required
-    type__eeg_channels: required
+    type__channels: required
     units: required
     description: optional
     sampling_frequency: optional
diff --git a/src/schema/objects/columns.yaml b/src/schema/objects/columns.yaml
index b4b32c41a5..bd1ab1478e 100644
--- a/src/schema/objects/columns.yaml
+++ b/src/schema/objects/columns.yaml
@@ -183,8 +183,8 @@ hemisphere:
     The hemisphere in which the electrode is placed.
   type: string
   enum:
-    - L
-    - R
+    - $ref: objects.enums.left_hemisphere.value
+    - $ref: objects.enums.right_hemisphere.value
 high_cutoff:
   name: high_cutoff
   display_name: High cutoff
@@ -603,142 +603,7 @@ trigger:
     continuous measurement of the scanner trigger signal
   type: number
 # type column in channels.tsv files
-type__eeg_channels:
-  name: type
-  display_name: Channel type
-  description: |
-    Type of channel; MUST use the channel types listed below.
-    Note that the type MUST be in upper-case.
-  type: string
-  enum:
-    - AUDIO
-    - EEG
-    - EOG
-    - ECG
-    - EMG
-    - EYEGAZE
-    - GSR
-    - HEOG
-    - MISC
-    - PPG
-    - PUPIL
-    - REF
-    - RESP
-    - SYSCLOCK
-    - TEMP
-    - TRIG
-    - VEOG
-type__meg_channels:
-  name: type
-  display_name: Channel type
-  description: |
-    Type of channel; MUST use the channel types listed below.
-    Note that the type MUST be in upper-case.
-  type: string
-  enum:
-    - MEGMAG
-    - MEGGRADAXIAL
-    - MEGGRADPLANAR
-    - MEGREFMAG
-    - MEGREFGRADAXIAL
-    - MEGREFGRADPLANAR
-    - MEGOTHER
-    - EEG
-    - ECOG
-    - SEEG
-    - DBS
-    - VEOG
-    - HEOG
-    - EOG
-    - ECG
-    - EMG
-    - TRIG
-    - AUDIO
-    - PD
-    - EYEGAZE
-    - PUPIL
-    - MISC
-    - SYSCLOCK
-    - ADC
-    - DAC
-    - HLU
-    - FITERR
-    - OTHER
-type__ieeg_channels:
-  name: type
-  display_name: Channel type
-  description: |
-    Type of channel; MUST use the channel types listed below.
-    Note that the type MUST be in upper-case.
-  type: string
-  enum:
-    - EEG
-    - ECOG
-    - SEEG
-    - DBS
-    - VEOG
-    - HEOG
-    - EOG
-    - ECG
-    - EMG
-    - TRIG
-    - AUDIO
-    - PD
-    - EYEGAZE
-    - PUPIL
-    - MISC
-    - SYSCLOCK
-    - ADC
-    - DAC
-    - REF
-    - OTHER
-type__nirs_channels:
-  name: type
-  display_name: Channel type
-  description: |
-    Type of channel; MUST use the channel types listed below.
-    Note that the type MUST be in upper-case.
-  type: string
-  enum:
-    - NIRSCWAMPLITUDE
-    - NIRSCWFLUORESCENSEAMPLITUDE
-    - NIRSCWOPTICALDENSITY
-    - NIRSCWHBO
-    - NIRSCWHBR
-    - NIRSCWMUA
-    - MEGMAG
-    - MEGGRADAXIAL
-    - MEGGRADPLANAR
-    - MEGREFMAG
-    - MEGREFGRADAXIAL
-    - MEGREFGRADPLANAR
-    - MEGOTHER
-    - EEG
-    - ECOG
-    - SEEG
-    - DBS
-    - VEOG
-    - HEOG
-    - EOG
-    - ECG
-    - EMG
-    - TRIG
-    - AUDIO
-    - PD
-    - EYEGAZE
-    - PUPIL
-    - MISC
-    - SYSCLOCK
-    - ADC
-    - DAC
-    - HLU
-    - FITERR
-    - ACCEL
-    - GYRO
-    - MAGN
-    - MISC
-    - OTHER
-type__motion_channels:
+type__channels:
   name: type
   display_name: Channel type
   description: |
@@ -746,16 +611,54 @@ type__motion_channels:
     Note that the type MUST be in upper-case.
   type: string
   enum:
-    - ACCEL
-    - ANGACCEL
-    - GYRO
-    - JNTANG
-    - LATENCY
-    - MAGN
-    - MISC
-    - ORNT
-    - POS
-    - VEL
+    - $ref: objects.enums.ACCEL.value
+    - $ref: objects.enums.ADC.value
+    - $ref: objects.enums.ANGACCEL.value
+    - $ref: objects.enums.AUDIO.value
+    - $ref: objects.enums.DAC.value
+    - $ref: objects.enums.DBS.value
+    - $ref: objects.enums.ECG.value
+    - $ref: objects.enums.ECOG.value
+    - $ref: objects.enums.EEG.value
+    - $ref: objects.enums.EMG.value
+    - $ref: objects.enums.EOG.value
+    - $ref: objects.enums.EYEGAZE.value
+    - $ref: objects.enums.FITERR.value
+    - $ref: objects.enums.GSR.value
+    - $ref: objects.enums.GYRO.value
+    - $ref: objects.enums.HEOG.value
+    - $ref: objects.enums.HLU.value
+    - $ref: objects.enums.JNTANG.value
+    - $ref: objects.enums.LATENCY.value
+    - $ref: objects.enums.MAGN.value
+    - $ref: objects.enums.MEGGRADAXIAL.value
+    - $ref: objects.enums.MEGGRADPLANAR.value
+    - $ref: objects.enums.MEGMAG.value
+    - $ref: objects.enums.MEGOTHER.value
+    - $ref: objects.enums.MEGREFGRADAXIAL.value
+    - $ref: objects.enums.MEGREFGRADPLANAR.value
+    - $ref: objects.enums.MEGREFMAG.value
+    - $ref: objects.enums.MISC.value
+    - $ref: objects.enums.NIRSCWAMPLITUDE.value
+    - $ref: objects.enums.NIRSCWFLUORESCENSEAMPLITUDE.value
+    - $ref: objects.enums.NIRSCWHBO.value
+    - $ref: objects.enums.NIRSCWHBR.value
+    - $ref: objects.enums.NIRSCWMUA.value
+    - $ref: objects.enums.NIRSCWOPTICALDENSITY.value
+    - $ref: objects.enums.ORNT.value
+    - $ref: objects.enums.OTHER.value
+    - $ref: objects.enums.PD.value
+    - $ref: objects.enums.POS.value
+    - $ref: objects.enums.PPG.value
+    - $ref: objects.enums.PUPIL.value
+    - $ref: objects.enums.REF.value
+    - $ref: objects.enums.RESP.value
+    - $ref: objects.enums.SEEG.value
+    - $ref: objects.enums.SYSCLOCK.value
+    - $ref: objects.enums.TEMP.value
+    - $ref: objects.enums.TRIG.value
+    - $ref: objects.enums.VEL.value
+    - $ref: objects.enums.VEOG.value
 # type column for electrodes.tsv files
 type__electrodes:
   name: type
diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml
index 83e1fa0826..3260b4a3d4 100644
--- a/src/schema/objects/entities.yaml
+++ b/src/schema/objects/entities.yaml
@@ -132,8 +132,8 @@ hemisphere:
   type: string
   format: label
   enum:
-    - 'L'
-    - 'R'
+    - $ref: objects.enums.left_hemisphere.value
+    - $ref: objects.enums.right_hemisphere.value
 inversion:
   name: inv
   display_name: Inversion Time
@@ -184,8 +184,8 @@ mtransfer:
   type: string
   format: label
   enum:
-    - 'on'
-    - 'off'
+    - $ref: objects.enums.on__mtransfer.value
+    - $ref: objects.enums.off__mtransfer.value
 part:
   name: part
   display_name: Part
@@ -207,10 +207,10 @@ part:
   type: string
   format: label
   enum:
-    - mag
-    - phase
-    - real
-    - imag
+    - $ref: objects.enums.magnitude.value
+    - $ref: objects.enums.phase.value
+    - $ref: objects.enums.real.value
+    - $ref: objects.enums.imaginary.value
 processing:
   name: proc
   display_name: Processed (on device)
diff --git a/src/schema/objects/enums.yaml b/src/schema/objects/enums.yaml
new file mode 100644
index 0000000000..16b2e6c618
--- /dev/null
+++ b/src/schema/objects/enums.yaml
@@ -0,0 +1,1089 @@
+---
+# This file defines valid values in BIDS key-value pairs.
+_EEGCoordSys:
+  type: string
+  enum:
+    - $ref: objects.enums.CapTrak.value
+    - $ref: objects.enums.EEGLAB.value
+    - $ref: objects.enums.EEGLAB-HJ.value
+    - $ref: objects.enums.Other.value
+_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
+_MEGCoordSys:
+  type: string
+  enum:
+    - $ref: objects.enums.CTF.value
+    - $ref: objects.enums.ElektaNeuromag.value
+    - $ref: objects.enums.4DBti.value
+    - $ref: objects.enums.KitYokogawa.value
+    - $ref: objects.enums.ChietiItab.value
+    - $ref: objects.enums.Other.value
+_StandardTemplateCoordSys:
+  type: string
+  enum:
+    - $ref: objects.enums.ICBM452AirSpace.value
+    - $ref: objects.enums.ICBM452Warp5Space.value
+    - $ref: objects.enums.IXI549Space.value
+    - $ref: objects.enums.fsaverage.value
+    - $ref: objects.enums.fsaverageSym.value
+    - $ref: objects.enums.fsLR.value
+    - $ref: objects.enums.MNIColin27.value
+    - $ref: objects.enums.MNI152Lin.value
+    - $ref: objects.enums.MNI152NLin2009aSym.value
+    - $ref: objects.enums.MNI152NLin2009bSym.value
+    - $ref: objects.enums.MNI152NLin2009cSym.value
+    - $ref: objects.enums.MNI152NLin2009aAsym.value
+    - $ref: objects.enums.MNI152NLin2009bAsym.value
+    - $ref: objects.enums.MNI152NLin2009cAsym.value
+    - $ref: objects.enums.MNI152NLin6Sym.value
+    - $ref: objects.enums.MNI152NLin6ASym.value
+    - $ref: objects.enums.MNI305.value
+    - $ref: objects.enums.NIHPD.value
+    - $ref: objects.enums.OASIS30AntsOASISAnts.value
+    - $ref: objects.enums.OASIS30Atropos.value
+    - $ref: objects.enums.Talairach.value
+    - $ref: objects.enums.UNCInfant.value
+_StandardTemplateDeprecatedCoordSys:
+  type: string
+  enum:
+    - $ref: objects.enums.fsaverage3.value
+    - $ref: objects.enums.fsaverage4.value
+    - $ref: objects.enums.fsaverage5.value
+    - $ref: objects.enums.fsaverage6.value
+    - $ref: objects.enums.fsaveragesym.value
+    - $ref: objects.enums.UNCInfant0V21.value
+    - $ref: objects.enums.UNCInfant1V21.value
+    - $ref: objects.enums.UNCInfant2V21.value
+    - $ref: objects.enums.UNCInfant0V22.value
+    - $ref: objects.enums.UNCInfant1V22.value
+    - $ref: objects.enums.UNCInfant2V22.value
+    - $ref: objects.enums.UNCInfant0V23.value
+    - $ref: objects.enums.UNCInfant1V23.value
+    - $ref: objects.enums.UNCInfant2V23.value
+_iEEGCoordSys:
+  type: string
+  enum:
+    - $ref: objects.enums.Pixels.value
+    - $ref: objects.enums.ACPC.value
+    - $ref: objects.enums.ScanRAS.value
+    - $ref: objects.enums.Other.value
+left_hemisphere:
+  value: 'L'
+  display_name: Left Hemisphere
+  description: |
+    A left hemibrain image.
+right_hemisphere:
+  value: 'R'
+  display_name: Right Hemisphere
+  description: |
+    A right hemibrain image.
+CASL:
+  value: CASL
+  display_name: Continuous arterial spin labeling
+  description: |
+    Continuous arterial spin labeling was employed.
+PCASL:
+  value: PCASL
+  display_name: Pseudo-continuous arterial spin labeling
+  description: |
+    Pseudo-continuous arterial spin labeling was employed.
+PASL:
+  value: PASL
+  display_name: Pulsed arterial spin labeling
+  description: |
+    Pulsed arterial spin labeling was employed.
+Separate:
+  value: Separate
+  display_name: Separate
+  description: |
+    A separate `m0scan` file is present.
+Included:
+  value: Included
+  display_name: Included
+  description: |
+    An m0scan volume is contained within the associated `asl` file.
+Estimate:
+  value: Estimate
+  display_name: Estimate
+  description: |
+    A single whole-brain M0 value is provided in the metadata.
+Absent:
+  value: Absent
+  display_name: Absent
+  description: |
+    No specific M0 information is present.
+TwoD:
+  value: 2D
+  display_name: Two-dimensional
+  description: |
+    Two-dimensional MR acquisition.
+ThreeD:
+  value: 3D
+  display_name: Three-dimensional
+  description: |
+    Three-dimensional MR acquisition.
+HARD:
+  value: HARD
+  display_name: Hard pulse
+  description: |
+    A very brief, strong, rectangular pulse.
+GAUSSIAN:
+  value: GAUSSIAN
+  display_name: Gaussian pulse
+  description: |
+    A Gaussian pulse.
+GAUSSHANN:
+  value: GAUSSHANN
+  display_name: Gaussian-Hanning pulse.
+  description: |
+    A Gaussian pulse with a Hanning window.
+SINC:
+  value: SINC
+  display_name: Sinc pulse
+  description: |
+    A sinc-shaped pulse.
+SINCHANN:
+  value: SINCHANN
+  display_name: Sinc-Hanning pulse
+  description: |
+    A sinc-shaped pulse with a Hanning window.
+SINCGAUSS:
+  value: SINCGAUSS
+  display_name: Sinc-Gauss pulse
+  description: |
+    A sinc-shaped pulse with a Gaussian window.
+FERMI:
+  value: FERMI
+  display_name: Fermi pulse
+  description: |
+    A Fermi-shaped pulse.
+i:
+  value: i
+  display_name: i
+  description: |
+    The encoding direction is along the first axis of the data in the NIFTI file,
+    and the encoding value increases from the zero index to the maximum index.
+j:
+  value: j
+  display_name: j
+  description: |
+    The encoding direction is along the second axis of the data in the NIFTI file,
+    and the encoding value increases from the zero index to the maximum index.
+k:
+  value: k
+  display_name: k
+  description: |
+    The encoding direction is along the third axis of the data in the NIFTI file,
+    and the encoding value increases from the zero index to the maximum index.
+iMinus:
+  value: i-
+  display_name: i-
+  description: |
+    The encoding direction is along the first axis of the data in the NIFTI file,
+    and the encoding value decreases from the zero index to the maximum index.
+jMinus:
+  value: j-
+  display_name: j-
+  description: |
+    The encoding direction is along the second axis of the data in the NIFTI file,
+    and the encoding value decreases from the zero index to the maximum index.
+kMinus:
+  value: k-
+  display_name: k-
+  description: |
+    The encoding direction is along the third axis of the data in the NIFTI file,
+    and the encoding value decreases from the zero index to the maximum index.
+continuous:
+  value: continuous
+  display_name: Continuous recording
+  description: |
+    Continuous recording.
+epoched:
+  value: epoched
+  display_name: Epoched recording
+  description: |
+    Recording is limited to time windows around events of interest
+    (for example, stimulus presentations or subject responses).
+discontinuous:
+  value: discontinuous
+  display_name: Discontinuous recording
+  description: |
+    Discontinuous recording.
+orig:
+  value: orig
+  display_name: orig
+  description: |
+    A (potentially unique) per-image space.
+    Useful for describing the source of transforms from an input image to a target space.
+Brain:
+  value: Brain
+  display_name: Brain mask
+  description: |
+    A brain mask.
+Lesion:
+  value: Lesion
+  display_name: Lesion mask
+  description: |
+    A lesion mask.
+Face:
+  value: Face
+  display_name: Face mask
+  description: |
+    A face mask.
+ROI:
+  value: ROI
+  display_name: ROI mask
+  description: |
+    A region of interest mask.
+CapTrak:
+  value: CapTrak
+  display_name: CapTrak
+  description: |
+    RAS orientation and the origin approximately between LPA and RPA
+EEGLAB:
+  value: EEGLAB
+  display_name: EEGLAB
+  description: |
+    ALS orientation and the origin exactly between LPA and RPA.
+    For more information, see the
+    [EEGLAB wiki page](https://eeglab.org/tutorials/ConceptsGuide/coordinateSystem.html#eeglab-coordinate-system).
+EEGLAB-HJ:
+  value: EEGLAB-HJ
+  display_name: EEGLAB-HJ
+  description: |
+    ALS orientation and the origin exactly between LHJ and RHJ.
+    For more information, see the
+    [EEGLAB wiki page](https://eeglab.org/tutorials/ConceptsGuide/coordinateSystem.html#\
+    eeglab-hj-coordinate-system).
+Other:
+  value: Other
+  display_name: Other
+  description: |
+    Other coordinate system.
+Genetic:
+  value: Genetic
+  display_name: Genetic
+  description: |
+    Data report on a single genetic location (typically directly in the `participants.tsv` file).
+Genomic:
+  value: Genomic
+  display_name: Genomic
+  description: |
+    Data link to participants' genome (multiple genetic locations).
+Epigenomic:
+  value: Epigenomic
+  display_name: Epigenomic
+  description: |
+    Data link to participants' characterization of reversible modifications of DNA.
+Transcriptomic:
+  value: Transcriptomic
+  display_name: Transcriptomic
+  description: |
+    Data link to participants RNA levels.
+Metabolomic:
+  value: Metabolomic
+  display_name: Metabolomic
+  description: |
+    Data link to participants' products of cellular metabolic functions.
+Proteomic:
+  value: Proteomic
+  display_name: Proteomic
+  description: |
+    Data link to participants peptides and proteins quantification.
+CTF:
+  value: CTF
+  display_name: CTF
+  description: |
+    ALS orientation and the origin between the ears.
+ElektaNeuromag:
+  value: ElektaNeuromag
+  display_name: Elekta Neuromag
+  description: |
+    RAS orientation and the origin between the ears.
+4DBti:
+  value: 4DBti
+  display_name: 4D BTI
+  description: |
+    ALS orientation and the origin between the ears.
+KitYokogawa:
+  value: KitYokogawa
+  display_name: KIT/Yokogawa
+  description: |
+    ALS orientation and the origin between the ears.
+ChietiItab:
+  value: ChietiItab
+  display_name: Chieti ITAB
+  description: |
+    RAS orientation and the origin between the ears.
+individual:
+  value: individual
+  display_name: individual
+  description: |
+    Participant specific anatomical space (for example derived from T1w and/or T2w images).
+    This coordinate system requires specifying an additional, participant-specific file to be fully defined.
+    In context of surfaces this space has been referred to as `fsnative`.
+
+    In order for this space to be interpretable, `SpatialReference` metadata MUST be provided.
+study:
+  value: study
+  display_name: study
+  description: |
+    Custom space defined using a group/study-specific template.
+    This coordinate system requires specifying an additional file to be fully defined.
+
+    In order for this space to be interpretable, `SpatialReference` metadata MUST be provided.
+scanner:
+  value: scanner
+  display_name: scanner
+  description: |
+    The intrinsic coordinate system of the original image (the first entry of `RawSources`)
+    after reconstruction and conversion to NIfTI or equivalent for the case of surfaces and dual volume/surface
+    files.
+
+    The `scanner` coordinate system is implicit and assumed by default if the derivative filename does not
+    define **any** `space-<label>`.
+    Please note that `space-scanner` SHOULD NOT be used,
+    it is mentioned in this specification to make its existence explicit.
+ICBM452AirSpace:
+  value: ICBM452AirSpace
+  display_name: ICBM452AirSpace
+  description: |
+    Reference space defined by the "average of 452 T1-weighted MRIs of normal young adult brains"
+    with "linear transforms of the subjects into the atlas space using a 12-parameter affine
+    transformation".
+ICBM452Warp5Space:
+  value: ICBM452Warp5Space
+  display_name: ICBM452Warp5Space
+  description: |
+    Reference space defined by the "average of 452 T1-weighted MRIs of normal young adult brains"
+    "based on a 5th order polynomial transformation into the atlas space".
+IXI549Space:
+  value: IXI549Space
+  display_name: IXI549Space
+  description: |
+    Reference space defined by the average of the "549 (...) subjects from the IXI dataset"
+    linearly transformed to ICBM MNI 452.
+
+    Used by SPM12.
+fsaverage:
+  value: fsaverage
+  display_name: fsaverage
+  description: |
+    The `fsaverage` is a **dual template** providing both volumetric and surface coordinates references.
+    The volumetric template corresponds to a FreeSurfer variant of `MNI305` space.
+    The `fsaverage` atlas also defines a surface reference system (formerly described as fsaverage[3|4|5|6|sym]).
+
+    Used by Freesurfer.
+fsaverageSym:
+  value: fsaverageSym
+  display_name: fsaverageSym
+  description: |
+    The `fsaverage` is a **dual template** providing both volumetric and surface coordinates references.
+    The volumetric template corresponds to a FreeSurfer variant of `MNI305` space.
+    The `fsaverageSym` atlas also defines a symmetric surface reference system
+    (formerly described as `fsaveragesym`).
+
+    Used by Freesurfer.
+fsLR:
+  value: fsLR
+  display_name: fsLR
+  description: |
+    The `fsLR` is a **dual template** providing both volumetric and surface coordinates references.
+    The volumetric template corresponds to `MNI152NLin6Asym`.
+    Surface templates are given at several sampling densities:
+    164k (used by HCP pipelines for 3T and 7T anatomical analysis),
+    59k (used by HCP pipelines for 7T MRI bold and DWI analysis),
+    32k (used by HCP pipelines for 3T MRI bold and DWI analysis), or
+    4k (used by HCP pipelines for MEG analysis) fsaverage_LR surface reconstructed from the T1w image.
+
+    Used by Freesurfer.
+MNIColin27:
+  value: MNIColin27
+  display_name: MNIColin27
+  description: |
+    Average of 27 T1 scans of a single subject.
+
+    Used by SPM96.
+MNI152Lin:
+  value: MNI152Lin
+  display_name: MNI152Lin
+  description: |
+    Also known as ICBM (version with linear coregistration).
+
+    Used by SPM99 to SPM8.
+MNI152NLin2009aSym:
+  value: MNI152NLin2009aSym
+  display_name: MNI152NLin2009aSym
+  description: |
+    Also known as ICBM (non-linear coregistration with 40 iterations, released in 2009).
+    This is the first symmetric version.
+
+    Used by the DARTEL toolbox in SPM12b.
+MNI152NLin2009bSym:
+  value: MNI152NLin2009bSym
+  display_name: MNI152NLin2009bSym
+  description: |
+    Also known as ICBM (non-linear coregistration with 40 iterations, released in 2009).
+    This is the second symmetric version.
+
+    Used by the DARTEL toolbox in SPM12b.
+MNI152NLin2009cSym:
+  value: MNI152NLin2009cSym
+  display_name: MNI152NLin2009cSym
+  description: |
+    Also known as ICBM (non-linear coregistration with 40 iterations, released in 2009).
+    This is the third symmetric version.
+
+    Used by the DARTEL toolbox in SPM12b.
+MNI152NLin2009aAsym:
+  value: MNI152NLin2009aAsym
+  display_name: MNI152NLin2009aAsym
+  description: |
+    Also known as ICBM (non-linear coregistration with 40 iterations, released in 2009).
+    This is the first asymmetric version.
+
+    Used by the DARTEL toolbox in SPM12b.
+MNI152NLin2009bAsym:
+  value: MNI152NLin2009bAsym
+  display_name: MNI152NLin2009bAsym
+  description: |
+    Also known as ICBM (non-linear coregistration with 40 iterations, released in 2009).
+    This is the second asymmetric version.
+
+    Used by the DARTEL toolbox in SPM12b.
+MNI152NLin2009cAsym:
+  value: MNI152NLin2009cAsym
+  display_name: MNI152NLin2009cAsym
+  description: |
+    Also known as ICBM (non-linear coregistration with 40 iterations, released in 2009).
+    This is the third asymmetric version.
+
+    Used by the DARTEL toolbox in SPM12b.
+MNI152NLin6Sym:
+  value: MNI152NLin6Sym
+  display_name: MNI152NLin6Sym
+  description: |
+    Also known as symmetric ICBM 6th generation (non-linear coregistration).
+
+    Used by FSL.
+MNI152NLin6ASym:
+  value: MNI152NLin6ASym
+  display_name: MNI152NLin6ASym
+  description: |
+    A variation of `MNI152NLin6Sym` built by A. Janke that is released as the _MNI template_ of FSL.
+    Volumetric templates included with
+    [HCP-Pipelines](https://github.com/Washington-University/HCPpipelines/tree/master/global/templates)
+    correspond to this template too.
+
+    Used by FSL and HPC-Pipelines.
+MNI305:
+  value: MNI305
+  display_name: MNI205
+  description: |
+    Also known as avg305.
+NIHPD:
+  value: NIHPD
+  display_name: NIHPD
+  description: |
+    Pediatric templates generated from the NIHPD sample.
+    Available for different age groups
+    (4.5-18.5 y.o., 4.5-8.5 y.o., 7-11 y.o., 7.5-13.5 y.o., 10-14 y.o., 13-18.5 y.o.).
+    This template also comes in either -symmetric or -asymmetric flavor.
+OASIS30AntsOASISAnts:
+  value: OASIS30AntsOASISAnts
+  display_name: OASIS30AntsOASISAnts
+  description: |
+    OASIS30AntsOASISAnts
+OASIS30Atropos:
+  value: OASIS30Atropos
+  display_name: OASIS30Atropos
+  description: |
+    OASIS30Atropos
+Talairach:
+  value: Talairach
+  display_name: Talairach
+  description: |
+    Piecewise linear scaling of the brain is implemented as described in TT88.
+UNCInfant:
+  value: UNCInfant
+  display_name: UNCInfant
+  description: |
+    Infant Brain Atlases from Neonates to 1- and 2-year-olds.
+fsaverage3:
+  value: fsaverage3
+  display_name: fsaverage3
+  description: |
+    Images were sampled to the FreeSurfer surface reconstructed from the subject's T1w image,
+    and registered to an fsaverage template.
+    For new datasets, the recommended alternative is fsaverage.
+fsaverage4:
+  value: fsaverage4
+  display_name: fsaverage4
+  description: |
+    Images were sampled to the FreeSurfer surface reconstructed from the subject's T1w image,
+    and registered to an fsaverage template.
+    For new datasets, the recommended alternative is fsaverage.
+fsaverage5:
+  value: fsaverage5
+  display_name: fsaverage5
+  description: |
+    Images were sampled to the FreeSurfer surface reconstructed from the subject's T1w image,
+    and registered to an fsaverage template.
+    For new datasets, the recommended alternative is fsaverage.
+fsaverage6:
+  value: fsaverage6
+  display_name: fsaverage6
+  description: |
+    Images were sampled to the FreeSurfer surface reconstructed from the subject's T1w image,
+    and registered to an fsaverage template.
+    For new datasets, the recommended alternative is fsaverage.
+fsaveragesym:
+  value: fsaveragesym
+  display_name: fsaveragesym
+  description: |
+    Images were sampled to the FreeSurfer surface reconstructed from the subject's T1w image,
+    and registered to an fsaverage template.
+    For new datasets, the recommended alternative is fsaverageSym.
+UNCInfant0V21:
+  value: UNCInfant0V21
+  display_name: UNCInfant0V21
+  description: |
+    Infant Brain Atlases from Neonates to 1- and 2-year-olds. See https://www.nitrc.org/projects/pediatricatlas.
+    For new datasets, the recommended alternative is UNCInfant.
+UNCInfant1V21:
+  value: UNCInfant1V21
+  display_name: UNCInfant1V21
+  description: |
+    Infant Brain Atlases from Neonates to 1- and 2-year-olds. See https://www.nitrc.org/projects/pediatricatlas.
+    For new datasets, the recommended alternative is UNCInfant.
+UNCInfant2V21:
+  value: UNCInfant2V21
+  display_name: UNCInfant2V21
+  description: |
+    Infant Brain Atlases from Neonates to 1- and 2-year-olds. See https://www.nitrc.org/projects/pediatricatlas.
+    For new datasets, the recommended alternative is UNCInfant.
+UNCInfant0V22:
+  value: UNCInfant0V22
+  display_name: UNCInfant0V22
+  description: |
+    Infant Brain Atlases from Neonates to 1- and 2-year-olds. See https://www.nitrc.org/projects/pediatricatlas.
+    For new datasets, the recommended alternative is UNCInfant.
+UNCInfant1V22:
+  value: UNCInfant1V22
+  display_name: UNCInfant1V22
+  description: |
+    Infant Brain Atlases from Neonates to 1- and 2-year-olds. See https://www.nitrc.org/projects/pediatricatlas.
+    For new datasets, the recommended alternative is UNCInfant.
+UNCInfant2V22:
+  value: UNCInfant2V22
+  display_name: UNCInfant2V22
+  description: |
+    Infant Brain Atlases from Neonates to 1- and 2-year-olds. See https://www.nitrc.org/projects/pediatricatlas.
+    For new datasets, the recommended alternative is UNCInfant.
+UNCInfant0V23:
+  value: UNCInfant0V23
+  display_name: UNCInfant0V23
+  description: |
+    Infant Brain Atlases from Neonates to 1- and 2-year-olds. See https://www.nitrc.org/projects/pediatricatlas.
+    For new datasets, the recommended alternative is UNCInfant.
+UNCInfant1V23:
+  value: UNCInfant1V23
+  display_name: UNCInfant1V23
+  description: |
+    Infant Brain Atlases from Neonates to 1- and 2-year-olds. See https://www.nitrc.org/projects/pediatricatlas.
+    For new datasets, the recommended alternative is UNCInfant.
+UNCInfant2V23:
+  value: UNCInfant2V23
+  display_name: UNCInfant2V23
+  description: |
+    Infant Brain Atlases from Neonates to 1- and 2-year-olds. See https://www.nitrc.org/projects/pediatricatlas.
+    For new datasets, the recommended alternative is UNCInfant.
+Pixels:
+  value: Pixels
+  display_name: Pixels
+  description: |
+    If electrodes are localized in 2D space (only x and y are
+    specified and z is n/a), then the positions in this file must correspond to
+    the locations expressed in pixels on the photo/drawing/rendering of the
+    electrodes on the brain. In this case, coordinates must be (row,column)
+    pairs, with (0,0) corresponding to the upper left pixel and (N,0)
+    corresponding to the lower left pixel.
+ACPC:
+  value: ACPC
+  display_name: ACPC
+  description: |
+    The origin of the coordinate system is at the Anterior Commissure
+    and the negative y-axis is passing through the Posterior Commissure. The
+    positive z-axis is passing through a mid-hemispheric point in the superior
+    direction. The anatomical landmarks are determined in the individual's
+    anatomical scan and no scaling or deformations have been applied to the
+    individual's anatomical scan. For more information, see the
+    [ACPC site](https://www.fieldtriptoolbox.org/faq/acpc/) on the FieldTrip
+    toolbox wiki.
+ScanRAS:
+  value: ScanRAS
+  display_name: ScanRAS
+  description: |
+    The origin of the coordinate system is the center of the
+    gradient coil for the corresponding T1w image of the subject, and the x-axis
+    increases left to right, the y-axis increases posterior to anterior and
+    the z-axis increases inferior to superior. For more information see the
+    [Nipy Documentation](https://nipy.org/nibabel/coordinate_systems.html). It is
+    strongly encouraged to align the subject's T1w to ACPC so that the `ACPC`
+    coordinate system can be used. If the subject's T1w in the BIDS dataset
+    is not aligned to ACPC, `ScanRAS` should be used.
+on__mtransfer:
+  value: 'on'
+  display_name: 'On'
+  description: |
+    The image acquired in the presence of the magnetization transfer pulse,
+    also known as the off-resonance pulse.
+off__mtransfer:
+  value: 'off'
+  display_name: 'Off'
+  description: |
+    The image acquired in the absence of the magnetization transfer pulse.
+magnitude:
+  value: mag
+  display_name: Magnitude
+  description: |
+    A magnitude image, typically paired with an associated "phase" image.
+phase:
+  value: phase
+  display_name: Phase
+  description: |
+    A phase image, typically paird with an associated "magnitude" (part-mag) image.
+    Images with this key/value pair MAY be in radians or in arbitrary units.
+    The sidecar JSON file MUST include the units of the `phase` image.
+    The possible options are `rad` or `arbitrary`.
+real:
+  value: real
+  display_name: Real
+  description: |
+    A real-valued image, typically paired with an associated "imaginary" (part-imag) image.
+imaginary:
+  value: imag
+  display_name: Imaginary
+  description: |
+    An imaginary-valued image, typically paird with an associated "real" image.
+ACCEL:
+  value: ACCEL
+  display_name: ACCEL
+  tags:
+    - fnirs
+    - motion
+  description: |
+    Accelerometer channel, one channel for each spatial axis.
+    Column `component` for the axis MUST be added to the `*_channels.tsv` file (x, y, or z).
+ANGACCEL:
+  value: ANGACCEL
+  display_name: ANGACCEL
+  tags:
+    - motion
+  description: |
+    Angular acceleration channel, one channel for each spatial axis.
+    Column `component` for the axis MUST be added to the `*_channels.tsv` file (x, y, or z).
+GYRO:
+  value: GYRO
+  display_name: GYRO
+  tags:
+    - fnirs
+    - motion
+  description: |
+    Gyrometer channel, one channel for each spatial axis.
+    Column `component` for the axis MUST be added to the `*_channels.tsv` file (x, y, or z).
+JNTANG:
+  value: JNTANG
+  display_name: JNTANG
+  tags:
+    - motion
+  description: |
+    Joint angle channel between two fixed axis belonging to two bodyparts.
+    Angle SHOULD be defined between proximal and distal bodypart in `deg`.
+LATENCY:
+  value: LATENCY
+  display_name: LATENCY
+  tags:
+    - motion
+  description: |
+    Latency of samples in seconds from recording onset.
+    MUST be in form of `ss[.000000]`,
+    where `[.000000]` is an optional subsecond resolution between 1 and 6 decimal points.
+MAGN:
+  value: MAGN
+  display_name: MAGN
+  tags:
+    - fnirs
+    - motion
+  description: |
+    Magnetic field strength, one channel for each spatial axis.
+    Column `component` for the axis MUST be added to the `*_channels.tsv` file (x, y or z).
+MISC:
+  value: MISC
+  display_name: MISC
+  tags:
+    - eeg
+    - meg
+    - ieeg
+    - fnirs
+    - motion
+  description: |
+    Miscellaneous channels.
+ORNT:
+  value: ORNT
+  display_name: ORNT
+  tags:
+    - fnirs
+    - motion
+  description: |
+    Orientation channel, one channel for each spatial axis or quaternion component.
+    Column `component` for the axis or quaternion label MUST be added to the `*_channels.tsv` file
+    (x, y, z, quat_x, quat_y, quat_z, or quat_w).
+POS:
+  value: POS
+  display_name: POS
+  tags:
+    - motion
+  description: |
+    Position in space, one channel for each spatial axis.
+    Column `component` for the axis MUST be added to the `*_channels.tsv` file (x, y or z).
+VEL:
+  value: VEL
+  display_name: VEL
+  tags:
+    - motion
+  description: |
+    Velocity, one channel for each spatial axis.
+    Column `component` for the axis MUST be added to the `*_channels.tsv` file (x, y or z).
+AUDIO:
+  value: AUDIO
+  display_name: AUDIO
+  tags:
+    - eeg
+    - meg
+    - ieeg
+    - fnirs
+  description: |
+    Audio signal.
+EEG:
+  value: EEG
+  display_name: EEG
+  tags:
+    - eeg
+    - meg
+    - ieeg
+    - fnirs
+  description: |
+    Electroencephalogram channel.
+EOG:
+  value: EOG
+  display_name: EOG
+  tags:
+    - eeg
+    - meg
+    - ieeg
+    - fnirs
+  description: |
+    Generic electrooculogram (eye), different from HEOG and VEOG.
+ECG:
+  value: ECG
+  display_name: ECG
+  tags:
+    - eeg
+    - meg
+    - ieeg
+    - fnirs
+  description: |
+    Electrocardiogram (heart).
+EMG:
+  value: EMG
+  display_name: EMG
+  tags:
+    - eeg
+    - meg
+    - ieeg
+    - fnirs
+  description: |
+    Electromyogram (muscle).
+EYEGAZE:
+  value: EYEGAZE
+  display_name: EYEGAZE
+  tags:
+    - eeg
+    - meg
+    - ieeg
+    - fnirs
+  description: |
+    Eye tracker gaze.
+GSR:
+  value: GSR
+  display_name: GSR
+  tags:
+    - eeg
+  description: |
+    Galvanic skin response.
+HEOG:
+  value: HEOG
+  display_name: HEOG
+  tags:
+    - eeg
+    - meg
+    - ieeg
+    - fnirs
+  description: |
+    Horizontal EOG (eye).
+PPG:
+  value: PPG
+  display_name: PPG
+  tags:
+    - eeg
+  description: |
+    Photoplethysmography.
+PUPIL:
+  value: PUPIL
+  display_name: PUPIL
+  tags:
+    - eeg
+    - meg
+    - ieeg
+    - fnirs
+  description: |
+    Eye tracker pupil diameter.
+REF:
+  value: REF
+  display_name: REF
+  tags:
+    - eeg
+    - ieeg
+  description: |
+    Reference channel.
+RESP:
+  value: RESP
+  display_name: RESP
+  tags:
+    - eeg
+  description: |
+    Respiration.
+SYSCLOCK:
+  value: SYSCLOCK
+  display_name: SYSCLOCK
+  tags:
+    - eeg
+    - meg
+    - ieeg
+    - fnirs
+  description: |
+    System time showing elapsed time since trial started.
+TEMP:
+  value: TEMP
+  display_name: TEMP
+  tags:
+    - eeg
+  description: |
+    Temperature.
+TRIG:
+  value: TRIG
+  display_name: TRIG
+  tags:
+    - eeg
+    - meg
+    - ieeg
+    - fnirs
+  description: |
+    Analog (TTL in Volt) or digital (binary TTL) trigger channel.
+VEOG:
+  value: VEOG
+  display_name: VEOG
+  tags:
+    - eeg
+    - meg
+    - ieeg
+    - fnirs
+  description: |
+    Vertical EOG (eye).
+MEGMAG:
+  value: MEGMAG
+  display_name: MEGMAG
+  tags:
+    - meg
+    - fnirs
+  description: |
+    MEG magnetometer.
+MEGGRADAXIAL:
+  value: MEGGRADAXIAL
+  display_name: MEGGRADAXIAL
+  tags:
+    - meg
+    - fnirs
+  description: |
+    MEG axial gradiometer.
+MEGGRADPLANAR:
+  value: MEGGRADPLANAR
+  display_name: MEGGRADPLANAR
+  tags:
+    - meg
+    - fnirs
+  description: |
+    MEG planargradiometer.
+MEGREFMAG:
+  value: MEGREFMAG
+  display_name: MEGREFMAG
+  tags:
+    - meg
+    - fnirs
+  description: |
+    MEG reference magnetometer.
+MEGREFGRADAXIAL:
+  value: MEGREFGRADAXIAL
+  display_name: MEGREFGRADAXIAL
+  tags:
+    - meg
+    - fnirs
+  description: |
+    MEG reference axial gradiometer.
+MEGREFGRADPLANAR:
+  value: MEGREFGRADPLANAR
+  display_name: MEGREFGRADPLANAR
+  tags:
+    - meg
+    - fnirs
+  description: |
+    MEG reference planar gradiometer.
+MEGOTHER:
+  value: MEGOTHER
+  display_name: MEGOTHER
+  tags:
+    - meg
+    - ieeg
+    - fnirs
+  description: |
+    Any other type of MEG sensor.
+ECOG:
+  value: ECOG
+  display_name: ECOG
+  tags:
+    - meg
+    - ieeg
+    - fnirs
+  description: |
+    Electrode channel.
+SEEG:
+  value: SEEG
+  display_name: SEEG
+  tags:
+    - meg
+    - ieeg
+    - fnirs
+  description: |
+    Electrode channel.
+DBS:
+  value: DBS
+  display_name: DBS
+  tags:
+    - meg
+    - ieeg
+    - fnirs
+  description: |
+    Electrode channel.
+PD:
+  value: PD
+  display_name: PD
+  tags:
+    - meg
+    - ieeg
+    - fnirs
+  description: |
+    Photodiode.
+ADC:
+  value: ADC
+  display_name: ADC
+  tags:
+    - meg
+    - ieeg
+    - fnirs
+  description: |
+    Analog to Digital input.
+DAC:
+  value: DAC
+  display_name: DAC
+  tags:
+    - meg
+    - ieeg
+    - fnirs
+  description: |
+    Digital to Analog output.
+HLU:
+  value: HLU
+  display_name: HLU
+  tags:
+    - meg
+    - fnirs
+  description: |
+    Measured position of head and head coils.
+FITERR:
+  value: FITERR
+  display_name: FITERR
+  tags:
+    - meg
+    - fnirs
+  description: |
+    Fit error signal from each head localization coil.
+OTHER:
+  value: OTHER
+  display_name: OTHER
+  tags:
+    - meg
+    - fnirs
+  description: |
+    Any other type of channel.
+NIRSCWAMPLITUDE:
+  value: NIRSCWAMPLITUDE
+  display_name: NIRSCWAMPLITUDE
+  tags:
+    - fnirs
+  description: |
+    Continuous wave amplitude measurements. Equivalent to dataType 001 in SNIRF.
+NIRSCWFLUORESCENSEAMPLITUDE:
+  value: NIRSCWFLUORESCENSEAMPLITUDE
+  display_name: NIRSCWFLUORESCENSEAMPLITUDE
+  tags:
+    - fnirs
+  description: |
+    Continuous wave fluorescence amplitude measurements. Equivalent to dataType 051 in SNIRF.
+NIRSCWOPTICALDENSITY:
+  value: NIRSCWOPTICALDENSITY
+  display_name: NIRSCWOPTICALDENSITY
+  tags:
+    - fnirs
+  description: |
+    Continuous wave change in optical density measurements. Equivalent to dataTypeLabel dOD in SNIRF.
+NIRSCWHBO:
+  value: NIRSCWHBO
+  display_name: NIRSCWHBO
+  tags:
+    - fnirs
+  description: |
+    Continuous wave oxygenated hemoglobin (oxyhemoglobin) concentration measurements.
+    Equivalent to dataTypeLabel HbO in SNIRF.
+NIRSCWHBR:
+  value: NIRSCWHBR
+  display_name: NIRSCWHBR
+  tags:
+    - fnirs
+  description: |
+    Continuous wave deoxygenated hemoglobin (deoxyhemoglobin) concentration measurements.
+    Equivalent to dataTypeLabel HbR in SNIRF.
+NIRSCWMUA:
+  value: NIRSCWMUA
+  display_name: NIRSCWMUA
+  tags:
+    - fnirs
+  description: |
+    Continuous wave optical absorption measurements. Equivalent to dataTypeLabel mua in SNIRF.
diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index 8d0742faff..ea6e2fb5eb 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -80,10 +80,10 @@ AnatomicalLandmarkCoordinateSystem:
     If `"Other"`, provide definition of the coordinate system in
     `"AnatomicalLandmarkCoordinateSystemDescription"`.
   anyOf:
-    - $ref: objects.metadata._MEGCoordSys
-    - $ref: objects.metadata._EEGCoordSys
-    - $ref: objects.metadata._StandardTemplateCoordSys
-    - $ref: objects.metadata._StandardTemplateDeprecatedCoordSys
+    - $ref: objects.enums._MEGCoordSys
+    - $ref: objects.enums._EEGCoordSys
+    - $ref: objects.enums._StandardTemplateCoordSys
+    - $ref: objects.enums._StandardTemplateDeprecatedCoordSys
 AnatomicalLandmarkCoordinateSystemDescription:
   name: AnatomicalLandmarkCoordinateSystemDescription
   display_name: Anatomical Landmark Coordinate System Description
@@ -154,9 +154,9 @@ ArterialSpinLabelingType:
     The arterial spin labeling type.
   type: string
   enum:
-    - CASL
-    - PCASL
-    - PASL
+    - $ref: objects.enums.CASL.value
+    - $ref: objects.enums.PCASL.value
+    - $ref: objects.enums.PASL.value
 AssociatedEmptyRoom:
   name: AssociatedEmptyRoom
   display_name: Associated Empty Room
@@ -659,10 +659,10 @@ DigitizedHeadPointsCoordinateSystem:
     If `"Other"`, provide definition of the coordinate system in
     `"DigitizedHeadPointsCoordinateSystemDescription"`.
   anyOf:
-    - $ref: objects.metadata._MEGCoordSys
-    - $ref: objects.metadata._EEGCoordSys
-    - $ref: objects.metadata._StandardTemplateCoordSys
-    - $ref: objects.metadata._StandardTemplateDeprecatedCoordSys
+    - $ref: objects.enums._MEGCoordSys
+    - $ref: objects.enums._EEGCoordSys
+    - $ref: objects.enums._StandardTemplateCoordSys
+    - $ref: objects.enums._StandardTemplateDeprecatedCoordSys
 DigitizedHeadPointsCoordinateSystemDescription:
   name: DigitizedHeadPointsCoordinateSystemDescription
   display_name: Digitized Head Points Coordinate System Description
@@ -760,10 +760,10 @@ EEGCoordinateSystem:
     If `"Other"`, provide definition of the coordinate system in
     `EEGCoordinateSystemDescription`.
   anyOf:
-    - $ref: objects.metadata._MEGCoordSys
-    - $ref: objects.metadata._EEGCoordSys
-    - $ref: objects.metadata._StandardTemplateCoordSys
-    - $ref: objects.metadata._StandardTemplateDeprecatedCoordSys
+    - $ref: objects.enums._MEGCoordSys
+    - $ref: objects.enums._EEGCoordSys
+    - $ref: objects.enums._StandardTemplateCoordSys
+    - $ref: objects.enums._StandardTemplateDeprecatedCoordSys
 EEGCoordinateSystemDescription:
   name: EEGCoordinateSystemDescription
   display_name: EEG Coordinate System Description
@@ -967,10 +967,10 @@ FiducialsCoordinateSystem:
     If `"Other"`, provide definition of the coordinate system in
     `"FiducialsCoordinateSystemDescription"`.
   anyOf:
-    - $ref: objects.metadata._MEGCoordSys
-    - $ref: objects.metadata._EEGCoordSys
-    - $ref: objects.metadata._StandardTemplateCoordSys
-    - $ref: objects.metadata._StandardTemplateDeprecatedCoordSys
+    - $ref: objects.enums._MEGCoordSys
+    - $ref: objects.enums._EEGCoordSys
+    - $ref: objects.enums._StandardTemplateCoordSys
+    - $ref: objects.enums._StandardTemplateDeprecatedCoordSys
 FiducialsCoordinateSystemDescription:
   name: FiducialsCoordinateSystemDescription
   display_name: Fiducials Coordinate System Description
@@ -1133,11 +1133,15 @@ GeneticLevel:
     Describes the level of analysis.
     Values MUST be one of `"Genetic"`, `"Genomic"`, `"Epigenomic"`,
     `"Transcriptomic"`, `"Metabolomic"`, or `"Proteomic"`.
+
+    For more information on these levels, see
+    [Multi-omics approaches to disease](https://genomebiology.biomedcentral.com/articles/10.1186/s13059-017-1215-1)
+    by Hasin et al. 2017.
   anyOf:
-    - $ref: objects.metadata._GeneticLevelEnum
+    - $ref: objects.enums._GeneticLevelEnum
     - type: array
       items:
-        $ref: objects.metadata._GeneticLevelEnum
+        $ref: objects.enums._GeneticLevelEnum
 Genetics:
   name: Genetics
   display_name: Genetics
@@ -1263,10 +1267,10 @@ HeadCoilCoordinateSystem:
     If `"Other"`, provide definition of the coordinate system in
     `HeadCoilCoordinateSystemDescription`.
   anyOf:
-    - $ref: objects.metadata._MEGCoordSys
-    - $ref: objects.metadata._EEGCoordSys
-    - $ref: objects.metadata._StandardTemplateCoordSys
-    - $ref: objects.metadata._StandardTemplateDeprecatedCoordSys
+    - $ref: objects.enums._MEGCoordSys
+    - $ref: objects.enums._EEGCoordSys
+    - $ref: objects.enums._StandardTemplateCoordSys
+    - $ref: objects.enums._StandardTemplateDeprecatedCoordSys
 HeadCoilCoordinateSystemDescription:
   name: HeadCoilCoordinateSystemDescription
   display_name: Head Coil Coordinate System Description
@@ -1748,10 +1752,10 @@ M0Type:
     `"Absent"` means that no specific M0 information is present.
   type: string
   enum:
-    - Separate
-    - Included
-    - Estimate
-    - Absent
+    - $ref: objects.enums.Separate.value
+    - $ref: objects.enums.Included.value
+    - $ref: objects.enums.Estimate.value
+    - $ref: objects.enums.Absent.value
 MAGNChannelCount:
   name: MAGNChannelCount
   display_name: Magnetometer Channel Count
@@ -1777,10 +1781,10 @@ MEGCoordinateSystem:
     If `"Other"`, provide definition of the coordinate system in
     `"MEGCoordinateSystemDescription"`.
   anyOf:
-    - $ref: objects.metadata._MEGCoordSys
-    - $ref: objects.metadata._EEGCoordSys
-    - $ref: objects.metadata._StandardTemplateCoordSys
-    - $ref: objects.metadata._StandardTemplateDeprecatedCoordSys
+    - $ref: objects.enums._MEGCoordSys
+    - $ref: objects.enums._EEGCoordSys
+    - $ref: objects.enums._StandardTemplateCoordSys
+    - $ref: objects.enums._StandardTemplateDeprecatedCoordSys
 MEGCoordinateSystemDescription:
   name: MEGCoordinateSystemDescription
   display_name: MEG Coordinate System Description
@@ -1831,8 +1835,8 @@ MRAcquisitionType:
     Corresponds to DICOM Tag 0018, 0023 `MR Acquisition Type`.
   type: string
   enum:
-    - 2D
-    - 3D
+    - $ref: objects.enums.TwoD.value
+    - $ref: objects.enums.ThreeD.value
 MRTransmitCoilSequence:
   name: MRTransmitCoilSequence
   display_name: MR Transmit Coil Sequence
@@ -1878,13 +1882,13 @@ MTPulseShape:
     The value `"SINCGAUSS"` refers to a sinc pulse with a Gaussian window.
   type: string
   enum:
-    - HARD
-    - GAUSSIAN
-    - GAUSSHANN
-    - SINC
-    - SINCHANN
-    - SINCGAUSS
-    - FERMI
+    - $ref: objects.enums.HARD.value
+    - $ref: objects.enums.GAUSSIAN.value
+    - $ref: objects.enums.GAUSSHANN.value
+    - $ref: objects.enums.SINC.value
+    - $ref: objects.enums.SINCHANN.value
+    - $ref: objects.enums.SINCGAUSS.value
+    - $ref: objects.enums.FERMI.value
 MTState:
   name: MTState
   display_name: MT State
@@ -2117,10 +2121,10 @@ NIRSCoordinateSystem:
     If `"Other"`, a definition of the coordinate system MUST be
     provided in `NIRSCoordinateSystemDescription`.
   anyOf:
-    - $ref: objects.metadata._MEGCoordSys
-    - $ref: objects.metadata._EEGCoordSys
-    - $ref: objects.metadata._StandardTemplateCoordSys
-    - $ref: objects.metadata._StandardTemplateDeprecatedCoordSys
+    - $ref: objects.enums._MEGCoordSys
+    - $ref: objects.enums._EEGCoordSys
+    - $ref: objects.enums._StandardTemplateCoordSys
+    - $ref: objects.enums._StandardTemplateDeprecatedCoordSys
 NIRSCoordinateSystemDescription:
   name: NIRSCoordinateSystemDescription
   display_name: NIRS Coordinate System Description
@@ -2243,6 +2247,7 @@ PCASLType:
   description: |
     The type of gradient pulses used in the `control` condition.
   type: string
+  # TODO: Add definitions for these values.
   enum:
     - balanced
     - unbalanced
@@ -2353,12 +2358,12 @@ PhaseEncodingDirection:
     `InPlanePhaseEncodingDirection` which can have `ROW` or `COL` values.
   type: string
   enum:
-    - i
-    - j
-    - k
-    - i-
-    - j-
-    - k-
+    - $ref: objects.enums.i.value
+    - $ref: objects.enums.iMinus.value
+    - $ref: objects.enums.j.value
+    - $ref: objects.enums.jMinus.value
+    - $ref: objects.enums.k.value
+    - $ref: objects.enums.kMinus.value
 PhotoDescription:
   name: PhotoDescription
   display_name: Photo Description
@@ -2608,9 +2613,9 @@ RecordingType:
     interest (for example, stimulus presentations or subject responses).
   type: string
   enum:
-    - continuous
-    - epoched
-    - discontinuous
+    - $ref: objects.enums.continuous.value
+    - $ref: objects.enums.epoched.value
+    - $ref: objects.enums.discontinuous.value
 ReferencesAndLinks:
   name: ReferencesAndLinks
   display_name: References And Links
@@ -2777,6 +2782,7 @@ SampleOrigin:
   description: |
     Describes from which tissue the genetic information was extracted.
   type: string
+  # TODO: Add definitions for these values.
   enum:
     - blood
     - saliva
@@ -3024,12 +3030,12 @@ SliceEncodingDirection:
     slice index as defined by the NIfTI header.
   type: string
   enum:
-    - i
-    - j
-    - k
-    - i-
-    - j-
-    - k-
+    - $ref: objects.enums.i.value
+    - $ref: objects.enums.iMinus.value
+    - $ref: objects.enums.j.value
+    - $ref: objects.enums.jMinus.value
+    - $ref: objects.enums.k.value
+    - $ref: objects.enums.kMinus.value
 SliceThickness:
   name: SliceThickness
   display_name: Slice Thickness
@@ -3180,7 +3186,7 @@ SpatialReference:
   anyOf:
     - type: string
       enum:
-        - orig
+        - $ref: objects.enums.orig.value
     - type: string
       format: uri
     - type: string
@@ -3190,7 +3196,7 @@ SpatialReference:
         anyOf:
           - type: string
             enum:
-              - orig
+              - $ref: objects.enums.orig.value
           - type: string
             format: uri
           - type: string
@@ -3267,6 +3273,7 @@ SpoilingType:
   description: |
     Specifies which spoiling method(s) are used by a spoiled sequence.
   type: string
+  # TODO: Add definitions for these values.
   enum:
     - RF
     - GRADIENT
@@ -3380,6 +3387,7 @@ TissueOrigin:
   description: |
     Describes the type of tissue analyzed for `"SampleOrigin"` `brain`.
   type: string
+  # TODO: Add definitions for these values.
   enum:
     - gray matter
     - white matter
@@ -3492,10 +3500,10 @@ Type:
     The value `"ROI"` refers to a region of interest mask.
   type: string
   enum:
-    - Brain
-    - Lesion
-    - Face
-    - ROI
+    - $ref: objects.enums.Brain.value
+    - $ref: objects.enums.Lesion.value
+    - $ref: objects.enums.Face.value
+    - $ref: objects.enums.ROI.value
 Units:
   name: Units
   display_name: Units
@@ -3568,94 +3576,6 @@ WithdrawalRate:
     The unit of the specified withdrawal rate should be in `"mL/s"`.
   type: number
   unit: mL/s
-_CoordUnits:
-  type: string
-  enum:
-    - m
-    - mm
-    - cm
-    - n/a
-_EEGCoordSys:
-  type: string
-  enum:
-    - CapTrak
-    - EEGLAB
-    - EEGLAB-HJ
-    - Other
-_GeneticLevelEnum:
-  type: string
-  enum:
-    - Genetic
-    - Genomic
-    - Epigenomic
-    - Transcriptomic
-    - Metabolomic
-    - Proteomic
-_LandmarkCoordinates:
-  type: object
-  additionalProperties:
-    type: array
-    items:
-      type: number
-    minItems: 3
-    maxItems: 3
-_MEGCoordSys:
-  type: string
-  enum:
-    - CTF
-    - ElektaNeuromag
-    - 4DBti
-    - KitYokogawa
-    - ChietiItab
-    - Other
-_StandardTemplateCoordSys:
-  type: string
-  enum:
-    - ICBM452AirSpace
-    - ICBM452Warp5Space
-    - IXI549Space
-    - fsaverage
-    - fsaverageSym
-    - fsLR
-    - MNIColin27
-    - MNI152Lin
-    - MNI152NLin2009aSym
-    - MNI152NLin2009bSym
-    - MNI152NLin2009cSym
-    - MNI152NLin2009aAsym
-    - MNI152NLin2009bAsym
-    - MNI152NLin2009cAsym
-    - MNI152NLin6Sym
-    - MNI152NLin6ASym
-    - MNI305
-    - NIHPD
-    - OASIS30AntsOASISAnts
-    - OASIS30Atropos
-    - Talairach
-    - UNCInfant
-_StandardTemplateDeprecatedCoordSys:
-  type: string
-  enum:
-    - fsaverage3
-    - fsaverage4
-    - fsaverage5
-    - fsaverage6
-    - fsaveragesym
-    - UNCInfant0V21
-    - UNCInfant1V21
-    - UNCInfant2V21
-    - UNCInfant0V22
-    - UNCInfant1V22
-    - UNCInfant2V22
-    - UNCInfant0V23
-    - UNCInfant1V23
-    - UNCInfant2V23
-_iEEGCoordSys:
-  type: string
-  enum:
-    - Pixels
-    - ACPC
-    - Other
 iEEGCoordinateProcessingDescription:
   name: iEEGCoordinateProcessingDescription
   display_name: iEEG Coordinate Processing Description
@@ -3687,9 +3607,9 @@ iEEGCoordinateSystem:
     [2D coordinate systems](SPEC_ROOT/modality-specific-files/intracranial\
     -electroencephalography.md#allowed-2d-coordinate-systems).
   anyOf:
-    - $ref: objects.metadata._iEEGCoordSys
-    - $ref: objects.metadata._StandardTemplateCoordSys
-    - $ref: objects.metadata._StandardTemplateDeprecatedCoordSys
+    - $ref: objects.enums._iEEGCoordSys
+    - $ref: objects.enums._StandardTemplateCoordSys
+    - $ref: objects.enums._StandardTemplateDeprecatedCoordSys
 iEEGCoordinateSystemDescription:
   name: iEEGCoordinateSystemDescription
   display_name: iEEG Coordinate System Description
diff --git a/src/schema/rules/files/raw/meg.yaml b/src/schema/rules/files/raw/meg.yaml
index c308cd8b9b..4bf7a42549 100644
--- a/src/schema/rules/files/raw/meg.yaml
+++ b/src/schema/rules/files/raw/meg.yaml
@@ -39,6 +39,7 @@ calibration:
     session: optional
     acquisition:
       level: required
+      # TODO: Add definitions for these values.
       enum:
         - calibration
 
@@ -54,6 +55,7 @@ crosstalk:
     session: optional
     acquisition:
       level: required
+      # TODO: Add definitions for these values.
       enum:
         - crosstalk
 
diff --git a/src/schema/rules/tabular_data/eeg.yaml b/src/schema/rules/tabular_data/eeg.yaml
index fd1e237425..ae31c5f6d9 100644
--- a/src/schema/rules/tabular_data/eeg.yaml
+++ b/src/schema/rules/tabular_data/eeg.yaml
@@ -6,11 +6,11 @@ EEGChannels:
     - extension == ".tsv"
   initial_columns:
     - name__channels
-    - type__eeg_channels
+    - type__channels
     - units
   columns:
     name__channels: required
-    type__eeg_channels: required
+    type__channels: required
     units: required
     description: optional
     sampling_frequency: optional
diff --git a/src/schema/rules/tabular_data/ieeg.yaml b/src/schema/rules/tabular_data/ieeg.yaml
index e502274068..ad40a98098 100644
--- a/src/schema/rules/tabular_data/ieeg.yaml
+++ b/src/schema/rules/tabular_data/ieeg.yaml
@@ -6,7 +6,7 @@ iEEGChannels:
     - extension == ".tsv"
   initial_columns:
     - name__channels
-    - type__ieeg_channels
+    - type__channels
     - units
     - low_cutoff
     - high_cutoff
@@ -17,7 +17,7 @@ iEEGChannels:
         When a corresponding electrode is specified in `_electrodes.tsv`,
         the name of that electrode MAY be specified here and the reference electrode
         name MAY be provided in the `reference` column.
-    type__ieeg_channels: required
+    type__channels: required
     units: required
     low_cutoff: required
     high_cutoff: required
diff --git a/src/schema/rules/tabular_data/meg.yaml b/src/schema/rules/tabular_data/meg.yaml
index 0f0d6041cd..ff8e5a7596 100644
--- a/src/schema/rules/tabular_data/meg.yaml
+++ b/src/schema/rules/tabular_data/meg.yaml
@@ -6,11 +6,11 @@ MEGChannels:
     - extension == ".tsv"
   initial_columns:
     - name__channels
-    - type__meg_channels
+    - type__channels
     - units
   columns:
     name__channels: required
-    type__meg_channels: required
+    type__channels: required
     units: required
     description: optional
     sampling_frequency: optional
diff --git a/src/schema/rules/tabular_data/motion.yaml b/src/schema/rules/tabular_data/motion.yaml
index 58fbec72f9..cd7e809ae9 100644
--- a/src/schema/rules/tabular_data/motion.yaml
+++ b/src/schema/rules/tabular_data/motion.yaml
@@ -7,13 +7,13 @@ motionChannels:
   initial_columns:
     - name__channels
     - component
-    - type__motion_channels
+    - type__channels
     - tracked_point__channels
     - units__motion
   columns:
     name__channels: required
     component: required
-    type__motion_channels: required
+    type__channels: required
     tracked_point__channels: required
     units__motion: required
     placement__motion: recommended
diff --git a/src/schema/rules/tabular_data/nirs.yaml b/src/schema/rules/tabular_data/nirs.yaml
index 57bf0e2bd1..117116abd3 100644
--- a/src/schema/rules/tabular_data/nirs.yaml
+++ b/src/schema/rules/tabular_data/nirs.yaml
@@ -6,14 +6,14 @@ nirsChannels:
     - extension == ".tsv"
   initial_columns:
     - name__channels
-    - type__nirs_channels
+    - type__channels
     - source__channels
     - detector__channels
     - wavelength_nominal
     - units__nirs
   columns:
     name__channels: required
-    type__nirs_channels: required
+    type__channels: required
     source__channels: required
     detector__channels: required
     wavelength_nominal: required
diff --git a/tools/schemacode/bidsschematools/render/text.py b/tools/schemacode/bidsschematools/render/text.py
index 822966c50a..6468007625 100644
--- a/tools/schemacode/bidsschematools/render/text.py
+++ b/tools/schemacode/bidsschematools/render/text.py
@@ -72,7 +72,14 @@ def _make_entity_definition(entity, entity_info):
     text += f"**Format**: `{entity_info['name']}-<{entity_info.get('format', 'label')}>`"
     text += "\n\n"
     if "enum" in entity_info.keys():
-        text += f"**Allowed values**: `{'`, `'.join(entity_info['enum'])}`"
+        allowed_values = []
+        for value in entity_info["enum"]:
+            if isinstance(value, str):
+                allowed_values.append(value)
+            else:
+                allowed_values.append(value["name"])
+
+        text += f"**Allowed values**: `{'`, `'.join(allowed_values)}`"
         text += "\n\n"
 
     description = entity_info["description"]
@@ -167,21 +174,25 @@ def make_glossary(schema, src_path=None):
         elif obj["type"] == "format":
             text += f"**Regular expression**: `{obj_def['pattern']}`\n\n"
 
+        keys_to_drop = ["description", "display_name", "name", "value", "pattern"]
         if "enum" in obj_def.keys():
-            allowed_vals = [f"`{enum}`" for enum in obj_def["enum"]]
-            text += f"**Allowed values**: {', '.join(allowed_vals)}\n\n"
+            allowed_values = []
+            keys_to_drop.append("enum")
+            for value in obj_def["enum"]:
+                if isinstance(value, str):
+                    allowed_values.append(value)
+                else:
+                    allowed_values.append(value["name"])
+
+            text += f"**Allowed values**: `{'`, `'.join(allowed_values)}`\n\n"
 
         text += f"**Description**:\n{obj_desc}\n\n"
 
-        temp_obj_def = {
-            k: v
-            for k, v in obj_def.items()
-            if k not in ("description", "display_name", "name", "value", "enum", "pattern")
-        }
+        reduced_obj_def = {k: v for k, v in obj_def.items() if k not in keys_to_drop}
 
-        if temp_obj_def:
-            temp_obj_def = yaml.dump(temp_obj_def)
-            text += f"**Schema information**:\n```yaml\n{temp_obj_def}\n```"
+        if reduced_obj_def:
+            reduced_obj_def = yaml.dump(reduced_obj_def)
+            text += f"**Schema information**:\n```yaml\n{reduced_obj_def}\n```"
 
     # Spec internal links need to be replaced
     text = text.replace("SPEC_ROOT", utils.get_relpath(src_path))
@@ -202,9 +213,18 @@ def _add_entity(filename_template, entity_pattern, requirement_level):
 def _format_entity(entity, lt, gt):
     fmt = entity.get("format")
     if "enum" in entity:
-        fmt = "|".join(entity["enum"])
+        allowed_values = []
+        for value in entity["enum"]:
+            if isinstance(value, str):
+                allowed_values.append(value)
+            else:
+                allowed_values.append(value["name"])
+
+        fmt = "|".join(allowed_values)
+
     if fmt is None:
         raise ValueError(f"entity missing format or enum fields: {entity}")
+
     return f"{entity['name']}-{lt}{fmt}{gt}"
 
 
diff --git a/tools/schemacode/bidsschematools/render/utils.py b/tools/schemacode/bidsschematools/render/utils.py
index 9764a4efbe..a482b54492 100644
--- a/tools/schemacode/bidsschematools/render/utils.py
+++ b/tools/schemacode/bidsschematools/render/utils.py
@@ -254,11 +254,9 @@ def describe_valid_values(definition):
     elif definition["type"] == "string":
         if "enum" in definition.keys():
             # Allow enums to be "objects" (dicts) or strings
-            enum_values = [
-                list(v.keys())[0] if isinstance(v, dict) else v for v in definition["enum"]
-            ]
-            enum_values = [f'`"{v}"`' for v in enum_values]
-            description = f"Must be one of: {', '.join(enum_values)}."
+            enums = [list(v.keys())[0] if isinstance(v, dict) else v for v in definition["enum"]]
+            enums = [f'`"{v}"`' for v in enums]
+            description = f"Must be one of: {', '.join(enums)}."
 
     elif definition["type"] in ("integer", "number"):
         minstr = maxstr = minmaxstr = ""
diff --git a/tools/schemacode/bidsschematools/rules.py b/tools/schemacode/bidsschematools/rules.py
index 5b321cefd2..6dd837629f 100644
--- a/tools/schemacode/bidsschematools/rules.py
+++ b/tools/schemacode/bidsschematools/rules.py
@@ -86,7 +86,14 @@ def _entity_rule(rule: Mapping, schema: bst.types.Namespace):
         entity = {**schema.objects.entities[ent], **ent_obj}
 
         if "enum" in entity:
-            pattern = "|".join(entity["enum"])
+            allowed_values = []
+            for value in entity["enum"]:
+                if isinstance(value, str):
+                    allowed_values.append(value)
+                else:
+                    allowed_values.append(value["name"])
+
+            pattern = "|".join(allowed_values)
         else:
             pattern = schema.objects.formats[entity["format"]].pattern
 
diff --git a/tools/schemacode/bidsschematools/schema.py b/tools/schemacode/bidsschematools/schema.py
index 9b9b4a409a..22dac02cb6 100644
--- a/tools/schemacode/bidsschematools/schema.py
+++ b/tools/schemacode/bidsschematools/schema.py
@@ -52,10 +52,20 @@ def _get_bids_version(schema_dir):
 
 
 def _find(obj, predicate):
-    """Find objects in an arbitrary object that satisfy a predicate
+    """Find objects in an arbitrary object that satisfy a predicate.
 
     Note that this does not cut branches, so every iterable sub-object
     will be fully searched.
+
+    Parameters
+    ----------
+    obj : object
+    predicate : function
+
+    Returns
+    -------
+    generator
+        A generator of entries in ``obj`` that satisfy the predicate.
     """
     try:
         if predicate(obj):
@@ -74,26 +84,40 @@ def _find(obj, predicate):
 
 
 def dereference(namespace, inplace=True):
-    """Replace references in namespace with the contents of the referred object
+    """Replace references in namespace with the contents of the referred object.
 
     Parameters
     ----------
     namespace : Namespace
-        Namespace for which to dereference
+        Namespace for which to dereference.
 
     inplace : bool, optional
-        Whether to modify the namespace in place or create a copy, by default True
+        Whether to modify the namespace in place or create a copy, by default True.
 
     Returns
     -------
     namespace : Namespace
-        Deferred namespace
+        Dereferenced namespace
     """
     if not inplace:
         namespace = deepcopy(namespace)
+
     for struct in _find(namespace, lambda obj: "$ref" in obj):
-        target = struct.pop("$ref")
-        struct.update({**namespace[target], **struct})
+        target = namespace.get(struct["$ref"])
+        if isinstance(target, Mapping):
+            struct.pop("$ref")
+            struct.update({**target, **struct})
+
+    # At this point, any remaining refs are one-off objects in lists
+    for struct in _find(namespace, lambda obj: any("$ref" in sub for sub in obj)):
+        for i, item in enumerate(struct):
+            try:
+                target = item.pop("$ref")
+            except (AttributeError, KeyError):
+                pass
+            else:
+                struct[i] = namespace.get(target)
+
     return namespace
 
 
diff --git a/tools/schemacode/bidsschematools/tests/test_schema.py b/tools/schemacode/bidsschematools/tests/test_schema.py
index 73041b0b3b..b0703361a3 100644
--- a/tools/schemacode/bidsschematools/tests/test_schema.py
+++ b/tools/schemacode/bidsschematools/tests/test_schema.py
@@ -309,3 +309,36 @@ def test_dereferencing():
             }
         },
     }
+
+    orig = {
+        "objects": {
+            "enums": {
+                "left": {"value": "L"},
+                "right": {"value": "R"},
+            },
+            "entities.hemisphere": {
+                "name": "hemi",
+                "enum": [
+                    {"$ref": "objects.enums.left.value"},
+                    {"$ref": "objects.enums.right.value"},
+                ],
+            },
+        },
+    }
+
+    sch = types.Namespace.build(orig)
+    dereffed = schema.dereference(sch)
+    assert dereffed == {
+        "objects": {
+            "enums": {
+                "left": {"value": "L"},
+                "right": {"value": "R"},
+            },
+            "entities": {
+                "hemisphere": {
+                    "name": "hemi",
+                    "enum": ["L", "R"],
+                },
+            },
+        },
+    }