feat(schema): Move coordsystem.json rules out of rules.sidecars (#1892)

* feat(schema): Move coordsystem.json rules out of rules.sidecars

* feat: Add make_json_table macro

* feat(spec): Render coordsystem JSON tables

* feat(metaschema): Add schema.rules.json

Author: effigies

src/metaschema.json

@@ -386,19 +386,25 @@
           "required": ["common", "deriv", "raw"],
           "additionalProperties": false
         },
+        "json": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/json"
+          }
+        },
         "sidecars": {
           "type": "object",
           "patternProperties": {
             "^derivatives$": {
               "type": "object",
               "properties": {
-                "common_derivatives": { "$ref": "#/definitions/sidecar" }
+                "common_derivatives": { "$ref": "#/definitions/json" }
               },
               "required": ["common_derivatives"],
               "additionalProperties": false
             },
             "^(?!derivatives$)[a-z_]+$": {
-              "$ref": "#/definitions/sidecar"
+              "$ref": "#/definitions/json"
             },
             "additionalProperties": false
           },
@@ -476,6 +482,7 @@
       "required": [
         "entities",
         "files",
+	"json",
         "sidecars",
         "tabular_data",
         "common_principles",
@@ -586,7 +593,7 @@
         }
       }
     },
-    "sidecar": {
+    "json": {
       "type": "object",
       "patternProperties": {
         "^[a-zA-Z0-9_]+$": {

src/modality-specific-files/electroencephalography.md

@@ -390,7 +390,7 @@ The definitions of the fields specified in these tables may be found in
 A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-{{ MACROS___make_sidecar_table("eeg.EEGCoordsystemGeneral") }}
+{{ MACROS___make_json_table("json.eeg.EEGCoordsystemGeneral") }}
 
 Fields relating to the EEG electrode positions:
 
@@ -402,7 +402,7 @@ The definitions of the fields specified in these tables may be found in
 A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-{{ MACROS___make_sidecar_table("eeg.EEGCoordsystemPositions") }}
+{{ MACROS___make_json_table("json.eeg.EEGCoordsystemPositions") }}
 
 Fields relating to the position of fiducials measured during an EEG session/run:
 
@@ -414,7 +414,7 @@ The definitions of the fields specified in these tables may be found in
 A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-{{ MACROS___make_sidecar_table("eeg.EEGCoordsystemFiducials") }}
+{{ MACROS___make_json_table("json.eeg.EEGCoordsystemFiducials") }}
 
 Fields relating to the position of anatomical landmark measured during an EEG session/run:
 
@@ -426,7 +426,7 @@ The definitions of the fields specified in these tables may be found in
 A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-{{ MACROS___make_sidecar_table(["eeg.EEGCoordsystemLandmark", "eeg.EEGCoordsystemLandmarkDescriptionRec"]) }}
+{{ MACROS___make_json_table(["json.eeg.EEGCoordsystemLandmark", "json.eeg.EEGCoordsystemLandmarkDescriptionRec"]) }}
 
 If the position of anatomical landmarks is measured using the same system or
 device used to measure electrode positions, and if thereby the anatomical

src/modality-specific-files/intracranial-electroencephalography.md

@@ -389,7 +389,7 @@ The definitions of the fields specified in these tables may be found in
 A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-{{ MACROS___make_sidecar_table("ieeg.iEEGCoordsystemGeneral") }}
+{{ MACROS___make_json_table("json.ieeg.iEEGCoordsystemGeneral") }}
 
 Fields relating to the iEEG electrode positions:
 
@@ -401,7 +401,7 @@ The definitions of the fields specified in these tables may be found in
 A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-{{ MACROS___make_sidecar_table("ieeg.iEEGCoordsystemPositions") }}
+{{ MACROS___make_json_table("json.ieeg.iEEGCoordsystemPositions") }}
 
 ### Recommended 3D coordinate systems
 

src/modality-specific-files/magnetoencephalography.md

@@ -343,7 +343,7 @@ The definitions of the fields specified in these tables may be found in
 A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-{{ MACROS___make_sidecar_table("meg.MEGCoordsystemWithEEG") }}
+{{ MACROS___make_json_table("json.meg.MEGCoordsystemWithEEG") }}
 
 Head localization coils:
 
@@ -355,7 +355,7 @@ The definitions of the fields specified in these tables may be found in
 A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-{{ MACROS___make_sidecar_table("meg.MEGCoordsystemHeadLocalizationCoils") }}
+{{ MACROS___make_json_table("json.meg.MEGCoordsystemHeadLocalizationCoils") }}
 
 Digitized head points:
 
@@ -367,7 +367,7 @@ The definitions of the fields specified in these tables may be found in
 A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-{{ MACROS___make_sidecar_table("meg.MEGCoordsystemDigitizedHeadPoints") }}
+{{ MACROS___make_json_table("json.meg.MEGCoordsystemDigitizedHeadPoints") }}
 
 Anatomical MRI:
 
@@ -379,7 +379,7 @@ The definitions of the fields specified in these tables may be found in
 A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-{{ MACROS___make_sidecar_table("meg.MEGCoordsystemAnatomicalMRI") }}
+{{ MACROS___make_json_table("json.meg.MEGCoordsystemAnatomicalMRI") }}
 
 Anatomical landmarks:
 
@@ -391,7 +391,7 @@ The definitions of the fields specified in these tables may be found in
 A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-{{ MACROS___make_sidecar_table("meg.MEGCoordsystemAnatomicalLandmarks") }}
+{{ MACROS___make_json_table("json.meg.MEGCoordsystemAnatomicalLandmarks") }}
 
 It is also RECOMMENDED that the MRI voxel coordinates of the actual anatomical
 landmarks for co-registration of MEG with structural MRI are stored in the
@@ -419,7 +419,7 @@ The definitions of the fields specified in these tables may be found in
 A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-{{ MACROS___make_sidecar_table("meg.MEGCoordsystemFiducialsInformation") }}
+{{ MACROS___make_json_table("json.meg.MEGCoordsystemFiducialsInformation") }}
 
 For more information on the definition of anatomical landmarks, please visit:
     [How are the Left and Right Pre-Auricular (LPA and RPA) points defined? - FieldTrip Toolbox](https://www.fieldtriptoolbox.org/faq/how_are_the_lpa_and_rpa_points_defined/)

src/modality-specific-files/near-infrared-spectroscopy.md

@@ -386,7 +386,7 @@ A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
 
-{{ MACROS___make_sidecar_table("nirs.CoordsystemGeneral") }}
+{{ MACROS___make_json_table("json.nirs.CoordsystemGeneral") }}
 
 Fields relating to the NIRS optode positions:
 
@@ -399,7 +399,7 @@ A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
 
-{{ MACROS___make_sidecar_table(["nirs.CoordinateSystem", "nirs.CoordinateSystemDescriptionRec"]) }}
+{{ MACROS___make_json_table(["json.nirs.CoordinateSystem", "json.nirs.CoordinateSystemDescriptionRec"]) }}
 
 Fields relating to the position of fiducials measured during an NIRS session/run:
 
@@ -412,7 +412,7 @@ A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
 
-{{ MACROS___make_sidecar_table(["nirs.Fiducials", "nirs.FiducialsCoordinateSystemDescriptionRec"]) }}
+{{ MACROS___make_json_table(["json.nirs.Fiducials", "json.nirs.FiducialsCoordinateSystemDescriptionRec"]) }}
 
 Fields relating to the position of anatomical landmarks measured during an NIRS session/run:
 
@@ -425,7 +425,7 @@ A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
 
-{{ MACROS___make_sidecar_table(["nirs.AnatomicalLandmark", "nirs.AnatomicalLandmarkCoordinateSystemDescriptionRec"]) }}
+{{ MACROS___make_json_table(["json.nirs.AnatomicalLandmark", "json.nirs.AnatomicalLandmarkCoordinateSystemDescriptionRec"]) }}
 
 ### Example `*_coordsystem.json`
 

src/schema/rules/json/eeg.yaml

@@ -0,0 +1,91 @@
+#
+# Groups of related metadata fields
+#
+# Assumptions: never need disjunction of selectors
+# Assumptions: top-to-bottom overrides is sufficient logic
+
+---
+# General fields
+EEGCoordsystemGeneral:
+  selectors:
+    - datatype == "eeg"
+    - suffix == "coordsystem"
+  fields:
+    IntendedFor:
+      level: optional
+      description_addendum: |
+        This identifies the MRI or CT scan associated with the electrodes,
+        landmarks, and fiducials.
+
+# Fields relating to the EEG electrode positions
+EEGCoordsystemPositions:
+  selectors:
+    - datatype == "eeg"
+    - suffix == "coordsystem"
+  fields:
+    EEGCoordinateSystem: required
+    EEGCoordinateUnits: required
+    EEGCoordinateSystemDescription:
+      level: recommended
+      level_addendum: required if `EEGCoordinateSystem` is `"Other"`
+
+EEGCoordsystemOther:
+  selectors:
+    - datatype == "eeg"
+    - suffix == "coordsystem"
+    - '"EEGCoordinateSystem" in json'
+    - json.EEGCoordinateSystem == "Other"
+  fields:
+    EEGCoordinateSystemDescription: required
+
+# Fields relating to the position of fiducials measured during an EEG session/run
+EEGCoordsystemFiducials:
+  selectors:
+    - datatype == "eeg"
+    - suffix == "coordsystem"
+  fields:
+    FiducialsDescription: optional
+    FiducialsCoordinates: recommended
+    FiducialsCoordinateSystem: recommended
+    FiducialsCoordinateUnits: recommended
+    FiducialsCoordinateSystemDescription:
+      level: recommended
+      level_addendum: required if `FiducialsCoordinateSystem` is `"Other"`
+
+EEGCoordsystemOtherFiducialCoordinateSystem:
+  selectors:
+    - datatype == "eeg"
+    - suffix == "coordsystem"
+    - json.FiducialsCoordinateSystem == "Other"
+  fields:
+    FiducialsCoordinateSystemDescription: required
+
+# Fields relating to the position of anatomical landmark measured during an EEG session/run
+EEGCoordsystemLandmark:
+  selectors:
+    - datatype == "eeg"
+    - suffix == "coordsystem"
+  fields:
+    AnatomicalLandmarkCoordinates: recommended
+    AnatomicalLandmarkCoordinateSystem:
+      level: recommended
+      description_addendum: Preferably the same as the `EEGCoordinateSystem`.
+    AnatomicalLandmarkCoordinateUnits: recommended
+
+EEGCoordsystemLandmarkDescriptionRec:
+  selectors:
+    - datatype == "eeg"
+    - suffix == "coordsystem"
+    - json.AnatomicalLandmarkCoordinateSystem != "Other"
+  fields:
+    AnatomicalLandmarkCoordinateSystemDescription:
+      level: recommended
+      level_addendum: required if `AnatomicalLandmarkCoordinateSystem` is `"Other"`
+
+EEGCoordsystemLandmarkDescriptionReq:
+  selectors:
+    - datatype == "eeg"
+    - suffix == "coordsystem"
+    - json.AnatomicalLandmarkCoordinateSystem == "Other"
+  fields:
+    AnatomicalLandmarkCoordinateSystemDescription: required

src/schema/rules/json/ieeg.yaml

@@ -0,0 +1,50 @@
+#
+# Groups of related metadata fields
+#
+# Assumptions: never need disjunction of selectors
+# Assumptions: top-to-bottom overrides is sufficient logic
+
+---
+# General fields
+iEEGCoordsystemGeneral:
+  selectors:
+    - datatype == "ieeg"
+    - suffix == "coordsystem"
+  fields:
+    IntendedFor__ds_relative:
+      level: optional
+      description_addendum: |
+        If only a surface reconstruction is available, this should point to
+        the surface reconstruction file.
+        Note that this file should have the same coordinate system
+        specified in `iEEGCoordinateSystem`.
+        For example, **T1**: `'bids::sub-<label>/ses-<label>/anat/sub-01_T1w.nii.gz'`
+        **Surface**: `'bids::derivatives/surfaces/sub-<label>/ses-<label>/anat/
+        sub-01_hemi-R_desc-T1w_pial.surf.gii'`
+        **Operative photo**: `'bids::sub-<label>/ses-<label>/ieeg/
+        sub-0001_ses-01_acq-photo1_photo.jpg'`
+        **Talairach**: `'bids::derivatives/surfaces/sub-Talairach/ses-01/anat/
+        sub-Talairach_hemi-R_pial.surf.gii'`
+
+# Fields relating to the iEEG electrode positions
+iEEGCoordsystemPositions:
+  selectors:
+    - datatype == "ieeg"
+    - suffix == "coordsystem"
+  fields:
+    iEEGCoordinateSystem: required
+    iEEGCoordinateUnits: required
+    iEEGCoordinateSystemDescription:
+      level: recommended
+      level_addendum: required if `iEEGCoordinateSystem` is `"Other"`
+    iEEGCoordinateProcessingDescription: recommended
+    iEEGCoordinateProcessingReference: recommended
+
+iEEGCoordsystemOther:
+  selectors:
+    - datatype == "ieeg"
+    - suffix == "coordsystem"
+    - '"iEEGCoordinateSystem" in json'
+    - json.iEEGCoordinateSystem == "Other"
+  fields:
+    iEEGCoordinateSystemDescription: required