[FIX] update highlighting of examples, JSON keys and values, and TSV headers or values in the schema (#998)

* remove extra double quotes from examples in columns.yml

* update example highlighting and add double quotes for JSON keys or values for entities.yml

* update example and JSON keys and values highlighting in metadata.yml

* Apply suggestions from code review

Co-authored-by: Taylor Salo <[email protected]>

* Apply suggestions from code review

Co-authored-by: Stefan Appelhoff <[email protected]>

Co-authored-by: Taylor Salo <[email protected]>
Co-authored-by: Stefan Appelhoff <[email protected]>

Author: 3 people

src/schema/objects/columns.yaml

@@ -65,7 +65,7 @@ duration:
   name: duration
   description: |
     Duration of the event (measured from onset) in seconds.
-    Must always be either zero or positive (or `"n/a"` if unavailable).
+    Must always be either zero or positive (or `n/a` if unavailable).
     A "duration" value of zero implies that the delta function or event is so
     short as to be effectively modeled as an impulse.
   anyOf:
@@ -183,7 +183,7 @@ mapping:
 material:
   name: material
   description: |
-    Material of the electrode (for example, `"Tin"`, `"Ag/AgCl"`, `"Gold"`).
+    Material of the electrode (for example, `Tin`, `Ag/AgCl`, `Gold`).
   type: string
 metabolite_parent_fraction:
   name: metabolite_parent_fraction
@@ -264,7 +264,7 @@ participant_id:
 plasma_radioactivity:
   name: plasma_radioactivity
   description: |
-    Radioactivity in plasma, in unit of plasma radioactivity (for example, `"kBq/mL"`).
+    Radioactivity in plasma, in unit of plasma radioactivity (for example, `kBq/mL`).
   type: number
 # reference column for channels.tsv files for EEG data
 reference__eeg:
@@ -278,7 +278,7 @@ reference__eeg:
 reference__ieeg:
   name: reference
   description: |
-    Specification of the reference (for example, 'mastoid', 'ElectrodeName01', 'intracranial', 'CAR', 'other', 'n/a').
+    Specification of the reference (for example, `mastoid`, `ElectrodeName01`, `intracranial`, `CAR`, `other`, `n/a`).
     If the channel is not an electrode channel (for example, a microphone channel) use `n/a`.
   anyOf:
   - type: string
@@ -295,7 +295,7 @@ response_time:
   description: |
     Response time measured in seconds.
     A negative response time can be used to represent preemptive responses and
-    "n/a" denotes a missed response.
+    `n/a` denotes a missed response.
   anyOf:
   - type: number
     unit: s
@@ -382,7 +382,7 @@ software_filters:
   name: software_filters
   description: |
     List of temporal and/or spatial software filters applied
-    (for example, "SSS", `"SpatialCompensation"`).
+    (for example, `SSS`, `SpatialCompensation`).
     Note that parameters should be defined in the general MEG sidecar .json file.
     Indicate `n/a` in the absence of software filters applied.
   anyOf:
@@ -403,8 +403,8 @@ status:
   name: status
   description: |
     Data quality observed on the channel.
-    A channel is considered `"bad"` if its data quality is compromised by excessive noise.
-    If quality is unknown, then a value of `"n/a"` may be used.
+    A channel is considered `bad` if its data quality is compromised by excessive noise.
+    If quality is unknown, then a value of `n/a` may be used.
     Description of noise type SHOULD be provided in `[status_description]`.
   type: string
   enum:
@@ -427,7 +427,7 @@ stim_file:
     (under the root folder of the dataset; with optional subfolders).
     The values under the `stim_file` column correspond to a path relative to
     `/stimuli`.
-    For example `"images/cat03.jpg"` will be translated to `"/stimuli/images/cat03.jpg"`.
+    For example `images/cat03.jpg` will be translated to `/stimuli/images/cat03.jpg`.
   type: string
   format: stimuli_relative
 strain:
@@ -456,8 +456,8 @@ trial_type:
   description: |
     Primary categorisation of each trial to identify them as instances of the
     experimental conditions.
-    For example: for a response inhibition task, it could take on values "go" and
-    "no-go" to refer to response initiation and response inhibition experimental
+    For example: for a response inhibition task, it could take on values `go` and
+    `no-go` to refer to response initiation and response inhibition experimental
     conditions.
   type: string
 trigger:
@@ -539,7 +539,7 @@ whole_blood_radioactivity:
   name: whole_blood_radioactivity
   description: |
     Radioactivity in whole blood samples,
-    in unit of radioactivity measurements in whole blood samples (for example, `"kBq/mL"`).
+    in unit of radioactivity measurements in whole blood samples (for example, `kBq/mL`).
   type: number
 x:
   name: x

src/schema/objects/entities.yaml

@@ -15,13 +15,13 @@ acquisition:
     resolution.
     In such case two files could have the following names:
     `sub-01_acq-highres_T1w.nii.gz` and `sub-01_acq-lowres_T1w.nii.gz`, however
-    the user is free to choose any other label than highres and lowres as long
+    the user is free to choose any other label than `highres` and `lowres` as long
     as they are consistent across subjects and sessions.
     In case different sequences are used to record the same modality
-    (for example, RARE and FLASH for T1w)
+    (for example, `RARE` and `FLASH` for T1w)
     this field can also be used to make that distinction.
     At what level of detail to make the distinction (for example,
-    just between RARE and FLASH, or between RARE, FLASH, and FLASHsubsampled)
+    just between `RARE` and `FLASH`, or between `RARE`, `FLASH`, and `FLASHsubsampled`)
     remains at the discretion of the researcher.
   type: string
   format: label
@@ -32,7 +32,7 @@ ceagent:
     The `ce-<label>` key/value can be used to distinguish
     sequences using different contrast enhanced images.
     The label is the name of the contrast agent.
-    The key `ContrastBolusIngredient` MAY also be added in the JSON file,
+    The key `"ContrastBolusIngredient"` MAY also be added in the JSON file,
     with the same label.
   type: string
   format: label
@@ -82,9 +82,9 @@ echo:
     If files belonging to an entity-linked file collection are acquired at different
     echo times, the `_echo-<index>` key/value pair MUST be used to distinguish
     individual files.
-    This entity represents the `EchoTime` metadata field. Please note that the `<index>`
+    This entity represents the `"EchoTime"` metadata field. Please note that the `<index>`
     denotes the number/index (in the form of a nonnegative integer), not the
-    `EchoTime` value which needs to be stored in the field `EchoTime` of the separate
+    `"EchoTime"` value which needs to be stored in the field `"EchoTime"` of the separate
     JSON file.
   type: string
   format: index
@@ -95,9 +95,9 @@ flip:
     If files belonging to an entity-linked file collection are acquired at different
     flip angles, the `_flip-<index>` key/value pair MUST be used to distinguish
     individual files.
-    This entity represents the `FlipAngle` metadata field. Please note that the `<index>`
-    denotes the number/index (in the form of a nonnegative integer), not the `FlipAngle`
-    value which needs to be stored in the field `FlipAngle` of the separate JSON file.
+    This entity represents the `"FlipAngle"` metadata field. Please note that the `<index>`
+    denotes the number/index (in the form of a nonnegative integer), not the `"FlipAngle"`
+    value which needs to be stored in the field `"FlipAngle"` of the separate JSON file.
   type: string
   format: index
 hemisphere:
@@ -119,9 +119,9 @@ inversion:
     If files belonging to an entity-linked file collection are acquired at different
     inversion times, the `_inv-<index>` key/value pair MUST be used to distinguish
     individual files.
-    This entity represents the `InversionTime` metadata field. Please note that the `<index>`
-    denotes the number/index (in the form of a nonnegative integer), not the `InversionTime`
-    value which needs to be stored in the field `InversionTime` of the separate JSON file.
+    This entity represents the `"InversionTime` metadata field. Please note that the `<index>`
+    denotes the number/index (in the form of a nonnegative integer), not the `"InversionTime"`
+    value which needs to be stored in the field `"InversionTime"` of the separate JSON file.
   type: string
   format: index
 label:
@@ -151,7 +151,7 @@ mtransfer:
     If files belonging to an entity-linked file collection are acquired at different
     magnetization transfer (MT) states, the `_mt-<label>` key/value pair MUST be used to
     distinguish individual files.
-    This entity represents the `MTState` metadata field. Allowed label values for this
+    This entity represents the `"MTState"` metadata field. Allowed label values for this
     entity are `on` and `off`, for images acquired in presence and absence of an MT pulse,
     respectively.
   type: string
@@ -172,7 +172,7 @@ part:
 
     Phase images 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`.
+    The possible options are `"rad"` or `"arbitrary"`.
 
     When there is only a magnitude image of a given type, the `part` key MAY be
     omitted.
@@ -190,7 +190,7 @@ processing:
     a file that was a result of particular processing performed on the device.
 
     This is useful for files produced in particular by Elekta's MaxFilter
-    (for example, sss, tsss, trans, quat or mc),
+    (for example, `sss`, `tsss`, `trans`, `quat` or `mc`),
     which some installations impose to be run on raw data because of active
     shielding software corrections before the MEG data can actually be
     exploited.
@@ -201,7 +201,7 @@ reconstruction:
   entity: rec
   description: |
     The `rec-<label>` key/value can be used to distinguish
-    different reconstruction algorithms (for example ones using motion
+    different reconstruction algorithms (for example `MoCo` for the ones using motion
     correction).
   type: string
   format: label
@@ -220,7 +220,7 @@ resolution:
   entity: res
   description: |
     Resolution of regularly sampled N-dimensional data.
-    MUST have a corresponding `Resolution` metadata field to provide
+    MUST have a corresponding `"Resolution"` metadata field to provide
     interpretation.
 
     This entity is only applicable to derivative data.
@@ -350,7 +350,7 @@ tracer:
   description: |
     The `trc-<label>` key/value can be used to distinguish
     sequences using different tracers.
-    The key `TracerName` MUST also be included in the associated JSON file,
+    The key `"TracerName"` MUST also be included in the associated JSON file,
     although the label may be different.
   type: string
   format: label