From 34c85b64efc5d2da3b01a9a192e87bcd806f6a0a Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Wed, 8 Dec 2021 16:15:19 +1100
Subject: [PATCH] Standardise use of "entity" definition across specification

---
 src/02-common-principles.md                   | 29 +++++------
 .../01-magnetic-resonance-imaging-data.md     | 52 +++++++++----------
 .../03-electroencephalography.md              |  6 ++-
 .../07-behavioral-experiments.md              |  4 +-
 src/05-derivatives/01-introduction.md         |  2 +-
 src/05-derivatives/03-imaging.md              |  2 +-
 src/99-appendices/04-entity-table.md          |  2 +-
 src/99-appendices/06-meg-file-formats.md      |  4 +-
 src/99-appendices/09-entities.md              |  2 +-
 src/schema/README.md                          | 10 ++--
 src/schema/objects/columns.yaml               |  2 +-
 src/schema/objects/entities.yaml              | 28 +++++-----
 src/schema/objects/metadata.yaml              | 30 +++++------
 13 files changed, 87 insertions(+), 86 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index cec4504aaa..f829f0a0fa 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -13,7 +13,7 @@ misunderstanding we clarify them here.
     purpose of a particular study. A dataset consists of data acquired from one
     or more subjects, possibly from multiple sessions.
 
-1.  **Subject** - a person or animal participating in the study.  Used
+1.  **Subject** - a person or animal participating in the study. Used
     interchangeably with term **Participant**.
 
 1.  **Session** - a logical grouping of neuroimaging and behavioral data
@@ -34,7 +34,7 @@ misunderstanding we clarify them here.
 
 1.  **Sample** - a sample pertaining to a subject such as tissue, primary cell
     or cell-free sample.
-    The `sample-<label>` key/value pair is used to distinguish between different
+    The `sample-<label>` **entity** is used to distinguish between different
     samples from the same subject.
     The label MUST be unique per subject and is RECOMMENDED to be unique
     throughout the dataset.
@@ -120,8 +120,8 @@ misunderstanding we clarify them here.
     following `task-<label>` specification. Note that labels MUST not collide when
     casing is ignored (see [Case collision intolerance](#case-collision-intolerance)).
 
-1.  **`suffix`** - an alphanumeric value, located after the `key-value_` pairs (thus after
-    the final `_`), right before the **File extension**, for example, it is `eeg` in
+1.  **`suffix`** - an alphanumeric value, located after all **entities** and following
+    a final `_`, right before the **file extension**; for example, it is `eeg` in
     `sub-05_task-matchingpennies_eeg.vhdr`.
 
 1.  **File extension** - a portion of the file name after the left-most
@@ -155,8 +155,7 @@ specification.
 
 ## File name structure
 
-A file name consists of a chain of *entities*, or key-value pairs, a *suffix* and an
-*extension*.
+A file name consists of a chain of *entities*, a *suffix* and an *extension*.
 Two prominent examples of entities are `subject` and `session`.
 
 For a data file that was collected in a given `session` from a given
@@ -175,7 +174,7 @@ be added for all subjects if at least one subject in the dataset has more than
 one session.
 If a `/ses-<label>` subfolder is included as part of the directory hierarchy,
 then the same [`ses-<label>`](./99-appendices/09-entities.md#ses)
-key/value pair MUST also be included as part of the file names themselves.
+entity MUST also be included as part of the file names themselves.
 Acquisition time of session can
 be defined in the [sessions file](03-modality-agnostic-files.md#sessions-file).
 
@@ -414,9 +413,9 @@ levels unless they are overridden by a file at the lower level. For example,
 TR to a specific value. If one of the runs has a different TR than the one
 specified in that file, another `sub-*_task-rest_bold.json` file can be placed
 within that specific series directory specifying the TR for that specific run.
-There is no notion of "unsetting" a key/value pair.
-Once a key/value pair is set in a given level in the dataset, lower down in
-the hierarchy that key/value pair will always have some assigned value.
+There is no notion of "unsetting" a key-value pair.
+Once a key-value pair is set in a given level in the dataset, lower down in
+the hierarchy that key-value pair will always have some assigned value.
 Files for a particular participant can exist only at participant level directory,
 that is, `/dataset/sub-*[/ses-*]/sub-*_T1w.json`. Similarly, any file that is not
 specific to a participant is to be declared only at top level of dataset for example:
@@ -496,8 +495,8 @@ with different value in the
 deeper level, that value will be applicable for that particular run/task NIfTI
 file/s. In other words, the `.json` file at the deeper level overrides values
 that are potentially also defined in the `.json` at a more shallow level. If the
-`.json` file at the more shallow level contains key-value-pairs that are not
-present in the `.json` file at the deeper level, these key-value-pairs are
+`.json` file at the more shallow level contains key-value pairs that are not
+present in the `.json` file at the deeper level, these key-value pairs are
 inherited by the `.json` file at the deeper level (but NOT vice versa!).
 
 ### Good practice recommendations
@@ -607,9 +606,9 @@ Example:
 }
 ```
 
-### Key/value files (dictionaries)
+### Key-value files (dictionaries)
 
-JavaScript Object Notation (JSON) files MUST be used for storing key/value
+JavaScript Object Notation (JSON) files MUST be used for storing key-value
 pairs. JSON files MUST be in UTF-8 encoding. Extensive documentation of the
 format can be found at [https://www.json.org/](https://www.json.org/),
 and at [https://tools.ietf.org/html/std90](https://tools.ietf.org/html/std90).
@@ -664,7 +663,7 @@ of `<index>`es.
 Please note that a given label or index is distinct from the "prefix"
 it refers to. For example `sub-01` refers to the `sub` entity (a
 subject) with the label `01`. The `sub-` prefix is not part of the subject
-label, but must be included in file names (similarly to other key names).
+label, but must be included in file names (similarly to other entities).
 
 ## Uniform Resource Indicator
 
diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
index aa5c2c7f12..2fd72896da 100644
--- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
+++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md
@@ -217,8 +217,8 @@ If the structural images included in the dataset were defaced (to protect
 identity of participants) one MAY provide the binary mask that was used to
 remove facial features in the form of `_defacemask` files.
 In such cases,  the OPTIONAL [`mod-<label>`](../99-appendices/09-entities.md#mod)
-key/value pair corresponds to modality suffix,
-such as T1w or inplaneT1, referenced by the defacemask image.
+entity corresponds to modality suffix,
+such as `T1w` or `inplaneT1`, referenced by the defacemask image.
 For example, `sub-01_mod-T1w_defacemask.nii.gz`.
 
 If several scans with the same acquisition parameters are acquired in the same session,
@@ -233,7 +233,7 @@ or different acquisition parameters indicated by
 then `run` is not needed to distinguish the scans and MAY be omitted.
 
 The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq)
-key/value pair corresponds to a custom label the user
+entity corresponds to a custom label the user
 MAY use to distinguish a different set of parameters used for acquiring the same
 modality. For example this should be used when a study includes two T1w images -
 one full brain low resolution and one restricted field of view but high
@@ -247,7 +247,7 @@ distinction (for example, just between RARE and FLASH, or between RARE, FLASH, a
 FLASHsubsampled) remains at the discretion of the researcher.
 
 Similarly the OPTIONAL [`ce-<label>`](../99-appendices/09-entities.md#ce)
-key/value can be used to distinguish
+entity can be used to distinguish
 sequences using different contrast enhanced images. The label is the name of the
 contrast agent. The key `ContrastBolusIngredient` MAY be also be added in the
 JSON file, with the same label.
@@ -265,7 +265,7 @@ fields specific to anatomical scans:
    }
 ) }}
 
-The [`part-<label>`](../99-appendices/09-entities.md#part) key/value pair is
+The [`part-<label>`](../99-appendices/09-entities.md#part) entity is
 used to indicate which component of the complex representation of the MRI
 signal is represented in voxel data.
 This entity is associated with the DICOM Tag `0008, 9208`.
@@ -299,10 +299,10 @@ For example, for `sub-01_part-phase_T1w.json`:
 }
 ```
 
-When there is only a magnitude image of a given type, the `part` key MAY be omitted.
+When there is only a magnitude image of a given type, the `part` entity MAY be omitted.
 
 Similarly, the OPTIONAL [`rec-<label>`](../99-appendices/09-entities.md#rec)
-key/value can be used to distinguish
+entity can be used to distinguish
 different reconstruction algorithms (for example ones using motion correction).
 
 Structural MR images whose intensity is represented in a non-arbitrary scale
@@ -387,18 +387,18 @@ type `sbref` (for example, `sub-control01_task-nback_sbref.nii.gz`).
 
 Each task has a unique label that MUST only consist of letters and/or numbers
 (other characters, including spaces and underscores, are not allowed) with the
-[`task-<label>`](../99-appendices/09-entities.md#task) key/value pair.
+[`task-<label>`](../99-appendices/09-entities.md#task) entity.
 Those labels MUST be consistent across subjects and sessions.
 
 If more than one run of the same task has been acquired the
-[`run-<index>`](../99-appendices/09-entities.md#run) key/value pair MUST be used:
+[`run-<index>`](../99-appendices/09-entities.md#run) entity MUST be used:
 `_run-1`, `_run-2`, `_run-3`, and so on. If only one run was acquired the
 `run-<index>` can be omitted. In the context of functional imaging a run is
 defined as the same task, but in some cases it can mean different set of stimuli
 (for example randomized order) and participant responses.
 
 The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq)
-key/value pair corresponds to a custom label one may
+entity corresponds to a custom label one may
 use to distinguish different set of parameters used for acquiring the same task.
 For example this should be used when a study includes two resting state images -
 one single band and one multiband. In such case two files could have the
@@ -408,24 +408,24 @@ other label than `singleband` and `multiband` as long as they are consistent
 across subjects and sessions and consist only of the legal label characters.
 
 Similarly the OPTIONAL [`ce-<label>`](../99-appendices/09-entities.md#ce)
-key/value can be used to distinguish
+entity can be used to distinguish
 sequences using different contrast enhanced images. The label is the name of the
-contrast agent. The key ContrastBolusIngredient MAY be also be added in the JSON
+contrast agent. The key "`ContrastBolusIngredient`" MAY be also be added in the JSON
 file, with the same label.
 
 Similarly the OPTIONAL [`rec-<label>`](../99-appendices/09-entities.md#rec)
-key/value can be used to distinguish
+entity can be used to distinguish
 different reconstruction algorithms (for example ones using motion correction).
 
 Similarly the OPTIONAL [`dir-<label>`](../99-appendices/09-entities.md#dir)
-and [`rec-<label>`](../99-appendices/09-entities.md#rec) key/values
+and [`rec-<label>`](../99-appendices/09-entities.md#rec) entities
 can be used to distinguish different phase-encoding directions and
 reconstruction algorithms (for example ones using motion correction).
 See [`fmap` Case 4](01-magnetic-resonance-imaging-data.md#case-4-multiple-phase-encoded-directions-pepolar)
 for more information on `dir` field specification.
 
 Multi-echo data MUST be split into one file per echo using the
-[`echo-<index>`](../99-appendices/09-entities.md#echo) key-value pair. For example:
+[`echo-<index>`](../99-appendices/09-entities.md#echo) entity. For example:
 
 {{ MACROS___make_filetree_example(
    {
@@ -453,7 +453,7 @@ Newly generated datasets SHOULD NOT use the `_phase` suffix, and the suffix will
 from the specification in the next major release.
 For backwards compatibility, `_phase` is considered equivalent to `_part-phase_bold`.
 When the `_phase` suffix is not used, each file shares the same
-name with the exception of the `part-<mag|phase>` or `part-<real|imag>` key/value.
+name with the exception of the `part-<mag|phase>` or `part-<real|imag>` entity.
 
 For example:
 
@@ -601,19 +601,19 @@ Currently supported image types include:
 {{ MACROS___make_filename_template(datatypes=["dwi"]) }}
 
 If more than one run of the same acquisition and direction has been acquired, the
-[`run-<index>`](../99-appendices/09-entities.md#run) key/value pair MUST be used:
+[`run-<index>`](../99-appendices/09-entities.md#run) entity MUST be used:
 `_run-1`, `_run-2`, `_run-3` (and so forth.)
-When there is only one scan of a given acquisition and direction, the run key MAY be
+When there is only one scan of a given acquisition and direction, the `run` entity MAY be
 omitted.
-The [`run-<index>`](../99-appendices/09-entities.md#run) key/value pair is RECOMMENDED
+The [`run-<index>`](../99-appendices/09-entities.md#run) entity is RECOMMENDED
 to encode the splits of multipart DWI scans (see [below](#multipart-split-dwi-schemes).)
 
 The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq)
-key/value pair corresponds to a custom label the user may use to
+entity corresponds to a custom label the user may use to
 distinguish different sets of parameters.
 
 The OPTIONAL [`dir-<label>`](../99-appendices/09-entities.md#dir)
-key/value pair corresponds to a custom label the user may use to
+entity corresponds to a custom label the user may use to
 distinguish different sets of phase-encoding directions.
 
 **Combining multi- and single-band acquisitions**.
@@ -623,7 +623,7 @@ The single-band reference image MAY be stored with suffix `sbref` (for example,
 to be stored.
 
 Otherwise, if some gradient information is associated to the single-band diffusion
-image and a multi-band diffusion image also exists, the `acq-<label>` key/value pair
+image and a multi-band diffusion image also exists, the `acq-<label>` entity
 MUST be used to distinguish both images.
 In such a case, two files could have the following names:
 `sub-01_acq-singleband_dwi.nii.gz` and `sub-01_acq-multiband_dwi.nii.gz`.
@@ -754,7 +754,7 @@ runs instead:
 ) }}
 
 The `MultipartID` metadata MAY be used with the
-[`acq-<label>`](../99-appendices/09-entities.md#acq) key/value pair, for example:
+[`acq-<label>`](../99-appendices/09-entities.md#acq) entity, for example:
 
 {{ MACROS___make_filetree_example(
    {
@@ -970,10 +970,10 @@ using the following image types:
 Two OPTIONAL entities, following more general rules of the specification,
 are allowed across all the four scenarios:
 
--   The OPTIONAL [`run-<index>`](../99-appendices/09-entities.md#run) key/value pair corresponds to a one-based index
+-   The OPTIONAL [`run-<index>`](../99-appendices/09-entities.md#run) entity corresponds to a one-based index
     to distinguish multiple fieldmaps with the same parameters.
 
--   The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq) key/value pair corresponds to a custom label
+-   The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq) entity corresponds to a custom label
     the user may use to distinguish different set of parameters.
 
 ### Expressing the MR protocol intent for fieldmaps
@@ -1136,7 +1136,7 @@ AFNI `3dqwarp`, and SPM.
 
 The [`dir-<label>`](../99-appendices/09-entities.md#dir) entity is REQUIRED
 for these files.
-This key-value pair MUST be used in addition to
+This entity MUST be used in addition to
 the REQUIRED `PhaseEncodingDirection` metadata field
 (see [File name structure](../02-common-principles.md#file-name-structure)).
 
diff --git a/src/04-modality-specific-files/03-electroencephalography.md b/src/04-modality-specific-files/03-electroencephalography.md
index e6b7178491..13099f4ddb 100644
--- a/src/04-modality-specific-files/03-electroencephalography.md
+++ b/src/04-modality-specific-files/03-electroencephalography.md
@@ -314,7 +314,8 @@ Cz     0.0000   0.0714   0.0699   cup      Ag/AgCl
 REF    -0.0742  -0.0200  -0.0100  cup      Ag/AgCl
 ```
 
-The [`acq-<label>`](../99-appendices/09-entities.md#acq) key/value pair can be used to indicate acquisition of the same data. For
+The [`acq-<label>`](../99-appendices/09-entities.md#acq) entity can be used to
+indicate acquisition of the same data. For
 example, this could be the recording of electrode positions with a different
 electrode position recording device, or repeated digitization before and after
 the recording.
@@ -436,7 +437,8 @@ Please note that the photos may need to be cropped or blurred to conceal
 identifying features prior to sharing, depending on the terms of the consent
 given by the participant.
 
-The [`acq-<label>`](../99-appendices/09-entities.md#acq) key/value pair can be used to indicate acquisition of different photos of
+The [`acq-<label>`](../99-appendices/09-entities.md#acq) entity can be used to
+indicate acquisition of different photos of
 the same face (or other body part in different angles to show, for example, the
 location of the nasion (NAS) as opposed to the right periauricular point (RPA).
 
diff --git a/src/04-modality-specific-files/07-behavioral-experiments.md b/src/04-modality-specific-files/07-behavioral-experiments.md
index 0406871b15..cd0895e622 100644
--- a/src/04-modality-specific-files/07-behavioral-experiments.md
+++ b/src/04-modality-specific-files/07-behavioral-experiments.md
@@ -16,10 +16,10 @@ rather than `_events.tsv`.
 
 Each task has a unique label that MUST only consist of letters and/or numbers
 (other characters, including spaces and underscores, are not allowed) with the
-[`task-<label>`](../99-appendices/09-entities.md#task) key/value pair.
+[`task-<label>`](../99-appendices/09-entities.md#task) entity.
 Those labels MUST be consistent across subjects and sessions.
 
-The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq) key/value pair corresponds to a custom label to
+The OPTIONAL [`acq-<label>`](../99-appendices/09-entities.md#acq) entity corresponds to a custom label to
 distinguish different conditions present during multiple runs of the same task.
 For example, if a study includes runs of an n-back task, with deep brain
 stimulation turned on or off, the data files may be labelled
diff --git a/src/05-derivatives/01-introduction.md b/src/05-derivatives/01-introduction.md
index f215d9c59a..f2dcdf38ab 100644
--- a/src/05-derivatives/01-introduction.md
+++ b/src/05-derivatives/01-introduction.md
@@ -58,7 +58,7 @@ in [Derived dataset and pipeline description][derived-dataset-description].
 
 -   When necessary to distinguish two files that do not otherwise have a
     distinguishing entity, the [`_desc-<label>`](../99-appendices/09-entities.md#desc)
-    keyword-value SHOULD be used.
+    entity SHOULD be used.
     This includes the cases of needing to distinguish both differing inputs and
     differing outputs (for example, `_desc-T1w` and `_desc-T2w` to distinguish
     brain mask files derived from T1w and T2w images;
diff --git a/src/05-derivatives/03-imaging.md b/src/05-derivatives/03-imaging.md
index 0cce5b1733..2ac6ac428f 100644
--- a/src/05-derivatives/03-imaging.md
+++ b/src/05-derivatives/03-imaging.md
@@ -303,7 +303,7 @@ Example:
 ) }}
 
 See [Common image-derived labels](#common-image-derived-labels)
-for reserved key values for [`label`](../99-appendices/09-entities.md#label).
+for reserved values for the [`label`](../99-appendices/09-entities.md#label) entity.
 
 A 4D probabilistic segmentation, in which each frame corresponds to a different
 tissue class, must provide a label mapping in its JSON sidecar. For example:
diff --git a/src/99-appendices/04-entity-table.md b/src/99-appendices/04-entity-table.md
index 0151c08738..8ee6951f90 100644
--- a/src/99-appendices/04-entity-table.md
+++ b/src/99-appendices/04-entity-table.md
@@ -1,6 +1,6 @@
 # Appendix IV: Entity table
 
-This section compiles the entities (key-value pairs) described throughout this
+This section compiles the entities (key-value pairs within file names) described throughout this
 specification, and establishes a common order within a filename.
 For example, if a file has an acquisition and reconstruction label, the
 acquisition entity must precede the reconstruction entity.
diff --git a/src/99-appendices/06-meg-file-formats.md b/src/99-appendices/06-meg-file-formats.md
index 1f5abc039f..860dfd095e 100644
--- a/src/99-appendices/06-meg-file-formats.md
+++ b/src/99-appendices/06-meg-file-formats.md
@@ -317,9 +317,9 @@ For this reason, the marker file extension was later modernized to `.mrk` to bet
 However again, to preserve backwards compatibility, `.sqd` is still a valid extension for the marker file(s).
 
 If there are multiple files with marker coils, the marker files must have the
-`acq-<label>` parameter and no more that two marker files may be associated with
+`acq-<label>` entity and no more that two marker files may be associated with
 one raw data file.
-While the acquisition parameter can take any value, it is RECOMMENDED that if
+While the acquisition entity can take any value, it is RECOMMENDED that if
 the two marker measurements occur before and after the raw data acquisition,
 `pre` and `post` are used to differentiate the two situations.
 
diff --git a/src/99-appendices/09-entities.md b/src/99-appendices/09-entities.md
index 196ae27ac2..f76d3398a8 100644
--- a/src/99-appendices/09-entities.md
+++ b/src/99-appendices/09-entities.md
@@ -1,6 +1,6 @@
 # Appendix IX: Entities
 
-This section compiles the entities (key-value pairs) described throughout this
+This section compiles the entities (key-value pairs within file names) described throughout this
 specification, and describes each.
 
 A general introduction to entities is given in the section on
diff --git a/src/schema/README.md b/src/schema/README.md
index c3d142cba6..4a2eb93500 100644
--- a/src/schema/README.md
+++ b/src/schema/README.md
@@ -48,7 +48,7 @@ Each of these object types has a single file in the `objects/` folder.
     1.  each datatype's full name
     1.  a free text description of the datatype.
 
--   `entities.yaml`: Entities (key/value pairs in folder and filenames).
+-   `entities.yaml`: Entities (key-value pairs in folder and filenames).
 
 -   `metadata.yaml`: All valid metadata fields that are explicitly supported in BIDS sidecar JSON files.
 
@@ -123,7 +123,7 @@ The `description` field is a freeform description of the datatype.
 
 ### `entities.yaml`
 
-This file contains a dictionary in which each entity (key/value pair in filenames) is defined.
+This file contains a dictionary in which each entity (key-value pair in filenames) is defined.
 Keys are long-form versions of the entities, which are distinct from both the entities as
 they appear in filenames _and_ their full names.
 For example, the key for the "Contrast Enhancing Agent" entity, which appears in filenames as `ce-<label>`,
@@ -155,11 +155,11 @@ The `format` field defines the specific format the value should take.
 Entities are broadly divided into either `label` or `index` types.
 
 When `format` is `index`, then the entity's associated value should be a non-zero integer, optionally with leading zeros.
-For example, `run` should have an index, so a valid key-value pair in a filename would be `run-01`.
+For example, `run` should have an index, so a valid entity would be `run-01`.
 
 When `format` is `label`, then the value should be an alphanumeric string.
 Beyond limitations on which characters are allowed, labels have few restrictions.
-For example, `acq` should have a label, so a valid key-value pair might be `acq-someLabel`.
+For example, `acq` should have a label, so a valid entity might be `acq-someLabel`.
 
 For a small number of entities, only certain labels are allowed.
 In those cases, instead of a `format` field, there will be an `enum` field, which will provide a list of allowed values.
@@ -269,7 +269,7 @@ There are additional fields which may define rules that apply to a given type.
 -   `object`: If `type` is `object`, then there MAY be any of the following
     fields at the same level as `type`: `additionalProperties`,
     `properties`.
-    Objects are defined as sets of key/value pairs.
+    Objects are defined as sets of key-value pairs.
     Keys MUST be strings, while values may have specific attributes,
     which is what `additionalProperties` describes.
     Here is an example of a field which MUST be an object,
diff --git a/src/schema/objects/columns.yaml b/src/schema/objects/columns.yaml
index ee658ffbbd..66092c6925 100644
--- a/src/schema/objects/columns.yaml
+++ b/src/schema/objects/columns.yaml
@@ -51,7 +51,7 @@ color:
 derived_from:
   name: derived_from
   description: |
-    `sample-<label>` key/value pair from which a sample is derived,
+    `sample-<label>` entity from which a sample is derived,
     for example a slice of tissue (`sample-02`) derived from a block of tissue (`sample-01`).
   type: string
   pattern: ^sample-[0-9a-zA-Z]+$
diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml
index e6a3db6ca3..f971c07bdc 100644
--- a/src/schema/objects/entities.yaml
+++ b/src/schema/objects/entities.yaml
@@ -7,7 +7,7 @@ acquisition:
   name: Acquisition
   entity: acq
   description: |
-    The `acq-<label>` key/value pair corresponds to a custom label the
+    The `acq-<label>` entity corresponds to a custom label the
     user MAY use to distinguish a different set of parameters used for
     acquiring the same modality.
     For example this should be used when a study includes two T1w images - one
@@ -29,7 +29,7 @@ ceagent:
   name: Contrast Enhancing Agent
   entity: ce
   description: |
-    The `ce-<label>` key/value can be used to distinguish
+    The `ce-<label>` entity 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,
@@ -52,7 +52,7 @@ description:
   entity: desc
   description: |
     When necessary to distinguish two files that do not otherwise have a
-    distinguishing entity, the `_desc-<label>` keyword-value SHOULD be used.
+    distinguishing entity, the `_desc-<label>` entity SHOULD be used.
 
     This entity is only applicable to derivative data.
   type: string
@@ -61,7 +61,7 @@ direction:
   name: Phase-Encoding Direction
   entity: dir
   description: |
-    The `dir-<label>` key/value can be set to an arbitrary alphanumeric label
+    The `dir-<label>` entity can be set to an arbitrary alphanumeric label
     (for example, `dir-LR` or `dir-AP`) to distinguish different phase-encoding
     directions.
   type: string
@@ -71,7 +71,7 @@ echo:
   entity: echo
   description: |
     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
+    echo times, the `_echo-<index>` entity MUST be used to distinguish
     individual files.
     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
@@ -84,7 +84,7 @@ flip:
   entity: flip
   description: |
     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
+    flip angles, the `_flip-<index>` entity 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`
@@ -108,7 +108,7 @@ inversion:
   entity: inv
   description: |
     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
+    inversion times, the `_inv-<index>` entity 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`
@@ -130,7 +130,7 @@ modality:
   name: Corresponding Modality
   entity: mod
   description: |
-    The `mod-<label>` key/value pair corresponds to modality label for defacing
+    The `mod-<label>` entity corresponds to modality label for defacing
     masks, for example, T1w, inplaneT1, referenced by a defacemask image.
     For example, `sub-01_mod-T1w_defacemask.nii.gz`.
   type: string
@@ -140,7 +140,7 @@ mtransfer:
   entity: mt
   description: |
     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
+    magnetization transfer (MT) states, the `_mt-<label>` entity MUST be used to
     distinguish individual files.
     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,
@@ -155,7 +155,7 @@ part:
   description: |
     This entity is used to indicate which component of the complex
     representation of the MRI signal is represented in voxel data.
-    The `part-<label>` key/value pair is associated with the DICOM Tag
+    The `part-<label>` entity is associated with the DICOM Tag
     `0008, 9208`.
     Allowed label values for this entity are `phase`, `mag`, `real` and `imag`,
     which are typically used in `part-mag`/`part-phase` or
@@ -165,7 +165,7 @@ part:
     The sidecar JSON file MUST include the units of the `phase` image.
     The possible options are `rad` or `arbitrary`.
 
-    When there is only a magnitude image of a given type, the `part` key MAY be
+    When there is only a magnitude image of a given type, the `part` entity MAY be
     omitted.
   type: string
   enum:
@@ -191,7 +191,7 @@ reconstruction:
   name: Reconstruction
   entity: rec
   description: |
-    The `rec-<label>` key/value can be used to distinguish
+    The `rec-<label>` entity can be used to distinguish
     different reconstruction algorithms (for example ones using motion
     correction).
   type: string
@@ -239,7 +239,7 @@ sample:
   description: |
     A sample pertaining to a subject such as tissue, primary cell
     or cell-free sample.
-    The `sample-<label>` key/value pair is used to distinguish between different
+    The `sample-<label>` entity is used to distinguish between different
     samples from the same subject.
     The label MUST be unique per subject and is RECOMMENDED to be unique
     throughout the dataset.
@@ -327,7 +327,7 @@ tracer:
   name: Tracer
   entity: trc
   description: |
-    The `trc-<label>` key/value can be used to distinguish
+    The `trc-<label>` entity can be used to distinguish
     sequences using different tracers.
     The key `TracerName` MUST also be included in the associated JSON file,
     although the label may be different.
diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index 873f69a357..2471c9a095 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -91,7 +91,7 @@ AnatomicalLandmarkCoordinateUnits:
 AnatomicalLandmarkCoordinates:
   name: AnatomicalLandmarkCoordinates
   description: |
-    Key:value pairs of the labels and 3-D digitized locations of anatomical landmarks,
+    Key-value pairs of the labels and 3-D digitized locations of anatomical landmarks,
     interpreted following the `AnatomicalLandmarkCoordinateSystem`
     (for example, `{"NAS": [12.7,21.3,13.9], "LPA": [5.2,11.3,9.6],
     "RPA": [20.2,11.3,9.1]}`.
@@ -107,7 +107,7 @@ AnatomicalLandmarkCoordinates:
 AnatomicalLandmarkCoordinates_mri:
   name: AnatomicalLandmarkCoordinates
   description: |
-    Key:value pairs of any number of additional anatomical landmarks and their
+    Key-value pairs of any number of additional anatomical landmarks and their
     coordinates in voxel units (where first voxel has index 0,0,0)
     relative to the associated anatomical MRI
     (for example, `{"AC": [127,119,149], "PC": [128,93,141],
@@ -445,8 +445,8 @@ Density:
   name: Density
   description: |
     Specifies the interpretation of the density keyword.
-    If an object is used, then the keys should be values for the ``den`` entity
-    and values should be descriptions of those ``den`` values.
+    If an object is used, then the keys should be values for the `den` entity
+    and values should be descriptions of those `den` values.
   anyOf:
   - type: string
   - type: object
@@ -652,7 +652,7 @@ EchoTime:
     a single value for this field, or to the files in a
     [file collection](/99-appendices/10-file-collections.html)
     where the value of this field is iterated using the
-    [echo entity](/99-appendices/09-entities.html#echo).
+    [`echo` entity](/99-appendices/09-entities.html#echo).
     The data type array provides a value for each volume in a 4D dataset and
     should only be used when the volume timing is critical for interpretation
     of the data, such as in
@@ -797,7 +797,7 @@ FiducialsCoordinateUnits:
 FiducialsCoordinates:
   name: FiducialsCoordinates
   description: |
-    Key:value pairs of the labels and 3-D digitized position of anatomical
+    Key-value pairs of the labels and 3-D digitized position of anatomical
     landmarks, interpreted following the `FiducialsCoordinateSystem`
     (for example, `{"NAS": [12.7,21.3,13.9], "LPA": [5.2,11.3,9.6],
     "RPA": [20.2,11.3,9.1]}`).
@@ -827,7 +827,7 @@ FlipAngle:
     a single value for this field, or to the files in a
     [file collection](/99-appendices/10-file-collections.html)
     where the value of this field is iterated using the
-    [flip entity](/99-appendices/09-entities.html#flip).
+    [`flip` entity](/99-appendices/09-entities.html#flip).
     The data type array provides a value for each volume in a 4D dataset and
     should only be used when the volume timing is critical for interpretation of
     the data, such as in
@@ -989,8 +989,8 @@ HardwareFilters:
   name: HardwareFilters
   description: |
     Object of temporal hardware filters applied, or "n/a" if the data is not
-    available. Each key:value pair in the JSON object is a name of the filter and
-    an object in which its parameters are defined as key:value pairs.
+    available. Each key-value pair in the JSON object is a name of the filter and
+    an object in which its parameters are defined as key-value pairs.
     For example, `{"Highpass RC filter": {"Half amplitude cutoff (Hz)":
     0.0159, "Roll-off": "6dB/Octave"}}`.
   anyOf:
@@ -1041,7 +1041,7 @@ HeadCoilCoordinateUnits:
 HeadCoilCoordinates:
   name: HeadCoilCoordinates
   description: |
-    Key:value pairs describing head localization coil labels and their
+    Key-value pairs describing head localization coil labels and their
     coordinates, interpreted following the `HeadCoilCoordinateSystem`
     (for example, `{"NAS": [12.7,21.3,13.9], "LPA": [5.2,11.3,9.6],
     "RPA": [20.2,11.3,9.1]}`).
@@ -2083,8 +2083,8 @@ Resolution:
   name: Resolution
   description: |
     Specifies the interpretation of the resolution keyword.
-    If an object is used, then the keys should be values for the ``res`` entity
-    and values should be descriptions of those ``res`` values.
+    If an object is used, then the keys should be values for the `res` entity
+    and values should be descriptions of those `res` values.
   anyOf:
   - type: string
   - type: object
@@ -2248,8 +2248,8 @@ SoftwareFilters:
     [Object](https://www.json.org/json-en.html)
     of temporal software filters applied, or `"n/a"` if the data is
     not available.
-    Each key:value pair in the JSON object is a name of the filter and an object
-    in which its parameters are defined as key:value pairs
+    Each key-value pair in the JSON object is a name of the filter and an object
+    in which its parameters are defined as key-value pairs
     (for example, `{"Anti-aliasing filter":
     {"half-amplitude cutoff (Hz)": 500, "Roll-off": "6dB/Octave"}}`).
   anyOf:
@@ -2428,7 +2428,7 @@ StationName:
 StimulusPresentation:
   name: StimulusPresentation
   description: |
-    Object containing key value pairs related to the software used to present
+    Object containing key-value pairs related to the software used to present
     the stimuli during the experiment, specifically:
     `OperatingSystem`, `SoftwareName`, `SoftwareRRID`, `SoftwareVersion` and
     `Code`.