From bdd3c962118a016a646cef6c447696f594e7987a Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Mon, 6 Dec 2021 10:58:25 +1100
Subject: [PATCH 1/6] [FIX] Common principles: Add "entity" to list of
 definitions

---
 src/02-common-principles.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index e29d0b96ed..b2270b28fc 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -105,6 +105,9 @@ misunderstanding we clarify them here.
     The modality may overlap with, but should not be confused with
     the **data type**.
 
+1.  **Entity** - a portion of a file name, consisting of a **key** and corresponding
+    **value** separated by a hyphen.
+
 1.  **`<index>`** - a nonnegative integer, possibly prefixed with arbitrary number of
     0s for consistent indentation, for example, it is `01` in `run-01` following
     `run-<index>` specification.

From 00f9cea8e4cebe2f58c7f8e42058d2904d70b1f6 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Wed, 8 Dec 2021 12:41:00 +1100
Subject: [PATCH 2/6] Common principles: Link "entity" definition to appendices

---
 src/02-common-principles.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index b2270b28fc..cec4504aaa 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -106,7 +106,10 @@ misunderstanding we clarify them here.
     the **data type**.
 
 1.  **Entity** - a portion of a file name, consisting of a **key** and corresponding
-    **value** separated by a hyphen.
+    **value** separated by a hyphen. Supported entities are defined in
+    [Appendix IX](99-appendices/09-entities.md); further, whether they are allowed,
+    OPTIONAL or REQUIRED for various data files, as well as their relative ordering,
+    are defined in the Entity Table in [Appendix IV](99-appendices/04-entity-table.md).
 
 1.  **`<index>`** - a nonnegative integer, possibly prefixed with arbitrary number of
     0s for consistent indentation, for example, it is `01` in `run-01` following

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 3/6] 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`.

From ae8090111492ddc19afe7b4f2b0ef3d06fb0be79 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Thu, 14 Apr 2022 11:32:54 +1000
Subject: [PATCH 4/6] Common principles: More elaborate "entity" definition

---
 src/02-common-principles.md | 156 +++++++++++++++++++++---------------
 1 file changed, 92 insertions(+), 64 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index f829f0a0fa..05cc0834c6 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -33,11 +33,8 @@ misunderstanding we clarify them here.
     taken in one or more visits.
 
 1.  **Sample** - a sample pertaining to a subject such as tissue, primary cell
-    or cell-free sample.
-    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.
+    or cell-free sample. Sample labels MUST be unique within a subject and it
+    is RECOMMENDED that they be unique throughout the dataset.
 
 1.  **Data acquisition** - a continuous uninterrupted block of time during which
     a brain scanning instrument was acquiring data according to particular
@@ -105,36 +102,62 @@ misunderstanding we clarify them here.
     The modality may overlap with, but should not be confused with
     the **data type**.
 
-1.  **Entity** - a portion of a file name, consisting of a **key** and corresponding
-    **value** separated by a hyphen. Supported entities are defined in
-    [Appendix IX](99-appendices/09-entities.md); further, whether they are allowed,
-    OPTIONAL or REQUIRED for various data files, as well as their relative ordering,
-    are defined in the Entity Table in [Appendix IV](99-appendices/04-entity-table.md).
-
-1.  **`<index>`** - a nonnegative integer, possibly prefixed with arbitrary number of
-    0s for consistent indentation, for example, it is `01` in `run-01` following
-    `run-<index>` specification.
-
-1.  **`<label>`** - an alphanumeric value, possibly prefixed with arbitrary
-    number of 0s for consistent indentation, for example, it is `rest` in `task-rest`
-    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 all **entities** and following
-    a final `_`, right before the **file extension**; for example, it is `eeg` in
-    `sub-05_task-matchingpennies_eeg.vhdr`.
+1.  **Suffix** - an alphanumeric string that forms part of a file name, located
+    after all [entities](#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
     period (`.`) preceded by any other alphanumeric. For example, `.gitignore` does
     not have a file extension, but the file extension of `test.nii.gz` is `.nii.gz`.
     Note that the left-most period is included in the file extension.
 
-1.  **DEPRECATED** - A "deprecated" entity or metadata field SHOULD NOT be used in the
+1.  **DEPRECATED** - A "deprecated" [entity](#entities) or metadata field SHOULD NOT be used in the
     generation of new datasets.
     It remains in the standard in order to preserve the interpretability of existing datasets.
     Validating software SHOULD warn when deprecated practices are detected and provide a
     suggestion for updating the dataset to preserve the curator's intent.
 
+## Entities
+
+An "entity" is an attribute that can be associated with a file, contributing
+to the identification of that file as a component of its file name in the
+form of a hyphen-separated key-value pair.
+
+Each entity has the following attributes:
+
+1.  *Name*: A comprehensive name describing the context of information
+    to be provided via the entity.
+1.  *Key*: A short string, typically a compression of the entity name,
+    which uniquely identifies the entity when part of a file name.
+1.  *Value type*: The requisite form of the value that gets specified
+    alongside the key whenever the entity appears in a file name.
+    For each entity, the value is of one of two possible types:
+    1.  *Index*: A non-negative integer, potentially zero-padded for
+        consistent width.
+    1.  *Label*: An alphanumeric string.
+        Note that labels MUST not collide when casing is ignored
+        (see [Case collision intolerance](#case-collision-intolerance)).
+
+The entity *format* is a string that prescribes how the entity appears within
+any given file name. For a hypothetical entity with key "`key`", the format
+can be either "`key-<index>`" or "`key-<label>`", depending on the value
+type of that entity.
+
+An entity *instance* is the specific manifestation of an entity within the
+name of a specific file, based on the format of the entity but with a value
+that provides identifying information to the particular file in whose name
+it appears.
+
+Depending on context, any one of the entity name, key, format, or a specific
+entity instance, may in some instances be referred to as simply an "entity".
+
+"Subject", "session", "sample", "task", and "run" from the list of definitions
+above are all examples of entities. The comprehensive list of supported
+entities is defined in [Appendix IX](99-appendices/09-entities.md);
+further, whether each is OPTIONAL, REQUIRED, or MUST NOT be provided for
+various data files, as well as their relative ordering in a file name, are
+defined in the Entity Table in [Appendix IV](99-appendices/04-entity-table.md).
+
 ## Compulsory, optional, and additional data and metadata
 
 The following standard describes a way of arranging data and writing down
@@ -153,50 +176,55 @@ The solutions will change from case to case and publicly available datasets will
 be reviewed to include common data types in the future releases of the BIDS
 specification.
 
-## File name structure
-
-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
-`subject`, the file name MUST begin with the string `sub-<label>_ses-<label>`.
-If the `session` level is omitted in the folder structure, the file name MUST begin
-with the string `sub-<label>`, without `ses-<label>`.
-
-Note that `sub-<label>` corresponds to the `subject` entity because it has
-the `sub-` "key" and`<label>` "value", where `<label>` would in a real data file
-correspond to a unique identifier of that subject, such as `01`.
-The same holds for the `session` entity with its `ses-` key and its `<label>`
-value.
-
-The extra session layer (at least one `/ses-<label>` subfolder) SHOULD
-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)
-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).
-
-A chain of entities, followed by a suffix, connected by underscores (`_`)
-produces a human readable file name, such as `sub-01_task-rest_eeg.edf`.
-It is evident from the file name alone that the file contains resting state
-data from subject `01`.
-The suffix `eeg` and the extension `.edf` depend on the imaging modality and
-the data format and indicate further details of the file's contents.
-
-Entities within a file name MUST be unique.
-For example, the following file name is not valid because it uses the `acq`
-entity twice:
-`sub-01_acq-laser_acq-uneven_electrodes.tsv`
-
-In cases where entities duplicate metadata,
-the presence of an entity should not be used as a replacement for
+## Filesystem structure
+
+Data for each subject are placed in sub-directories named "`sub-<label>`",
+where string "`<label>`" is substituted with the unique identification
+label of each subject. Additional information on each participant MAY be
+provided in a [participants file](03-modality-agnostic-files.md#participants-file)
+in the root directory of the dataset.
+
+If data for the subject were acquired across multiple sessions, then within
+the subject directory resides sub-directories named "`ses-<label>`",
+where string "`<label>`" is substituted with a unique identification
+label for each session. In datasets where at least one subject has more than
+one session, this additional sub-directory later SHOULD be added for all
+subjects in the dataset. Additional information on each session MAY be
+provided in a [sessions file](03-modality-agnostic-files.md#sessions-file)
+within the subject directory.
+
+Within the session sub-directory (or the subject sub-directory if no
+session sub-directories are present) are sub-directories named according to
+data type as defined above. A data type directory SHOULD NOT be defined if
+there are no files to be placed in that directory.
+
+## File names
+
+A file name consists of a chain of *entity instances* and a *suffix*
+all separated by underscores, and an *extension*. This pattern forms
+file names that are both human- and machine-readable. For instance, file
+"`sub-01_task-rest_eeg.edf`" contains instances of the "subject" and
+"task" entities, making it evident from the file name alone that it
+contains resting-state data from subject `01`; the suffix `eeg`
+and extension `.edf` depend on the imaging modality and the data
+format, and can therefore convey further details of the file's contents.
+
+For a data file that was collected in a given session from a given
+subject, the file name MUST begin with the string `sub-<label>_ses-<label>`.
+Conversely, if the session level is omitted in the folder structure, the file
+name MUST begin with the string `sub-<label>`, without `ses-<label>`.
+
+Any given entity MUST NOT appear more than once in any file name. For example,
+file name "`sub-01_acq-laser_acq-uneven_electrodes.tsv`" is invalid because
+it uses the "acquisition" entity twice.
+
+In cases where an entity and a metadata field convey similar contextual
+information, the presence of an entity should not be used as a replacement for
 the corresponding metadata field.
 For instance, in echo-planar imaging MRI,
 the [`dir-<label>`](./99-appendices/09-entities.md#dir) entity MAY be used
 to distinguish files with different phase-encoding directions,
-but the file's `PhaseEncodingDirection` can only be specified as metadata.
+but the file's `PhaseEncodingDirection` MUST be specified as metadata.
 
 A summary of all entities in BIDS and the order in which they MUST be
 specified is available in the [entity table](./99-appendices/04-entity-table.md)

From 470eb09f3ee5a13686a35b4c92f3f4ac6248a455 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Tue, 26 Apr 2022 13:56:53 +1000
Subject: [PATCH 5/6] Common principles: Reformmating of Entity definition
 changes

Requests made in: Lestropie/bids-specification#4.
Note that this is a repeat of commit 3972dd7d, but with corrected multi-author attribution.

Co-authored-by: Stefan Appelhoff <stefan.appelhoff@mailbox.org>
---
 src/02-common-principles.md | 56 ++++++++++++++++++++-----------------
 1 file changed, 31 insertions(+), 25 deletions(-)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index 05cc0834c6..d6156a586b 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -33,8 +33,9 @@ misunderstanding we clarify them here.
     taken in one or more visits.
 
 1.  **Sample** - a sample pertaining to a subject such as tissue, primary cell
-    or cell-free sample. Sample labels MUST be unique within a subject and it
-    is RECOMMENDED that they be unique throughout the dataset.
+    or cell-free sample.
+    Sample labels MUST be unique within a subject and it is RECOMMENDED that
+    they be unique throughout the dataset.
 
 1.  **Data acquisition** - a continuous uninterrupted block of time during which
     a brain scanning instrument was acquiring data according to particular
@@ -139,9 +140,9 @@ Each entity has the following attributes:
         (see [Case collision intolerance](#case-collision-intolerance)).
 
 The entity *format* is a string that prescribes how the entity appears within
-any given file name. For a hypothetical entity with key "`key`", the format
-can be either "`key-<index>`" or "`key-<label>`", depending on the value
-type of that entity.
+any given file name.
+For a hypothetical entity with key "`key`", the format can be either
+"`key-<index>`" or "`key-<label>`", depending on the value type of that entity.
 
 An entity *instance* is the specific manifestation of an entity within the
 name of a specific file, based on the format of the entity but with a value
@@ -149,14 +150,16 @@ that provides identifying information to the particular file in whose name
 it appears.
 
 Depending on context, any one of the entity name, key, format, or a specific
-entity instance, may in some instances be referred to as simply an "entity".
+entity instance, may be referred to as simply an "entity".
 
 "Subject", "session", "sample", "task", and "run" from the list of definitions
-above are all examples of entities. The comprehensive list of supported
-entities is defined in [Appendix IX](99-appendices/09-entities.md);
+above are all examples of entities.
+The comprehensive list of supported entities is defined in
+[Appendix IX](99-appendices/09-entities.md);
 further, whether each is OPTIONAL, REQUIRED, or MUST NOT be provided for
 various data files, as well as their relative ordering in a file name, are
-defined in the Entity Table in [Appendix IV](99-appendices/04-entity-table.md).
+defined in the Entity Table in
+[Appendix IV](99-appendices/04-entity-table.md).
 
 ## Compulsory, optional, and additional data and metadata
 
@@ -180,33 +183,36 @@ specification.
 
 Data for each subject are placed in sub-directories named "`sub-<label>`",
 where string "`<label>`" is substituted with the unique identification
-label of each subject. Additional information on each participant MAY be
-provided in a [participants file](03-modality-agnostic-files.md#participants-file)
+label of each subject.
+Additional information on each participant MAY be provided in a
+[participants file](03-modality-agnostic-files.md#participants-file)
 in the root directory of the dataset.
 
 If data for the subject were acquired across multiple sessions, then within
 the subject directory resides sub-directories named "`ses-<label>`",
 where string "`<label>`" is substituted with a unique identification
-label for each session. In datasets where at least one subject has more than
-one session, this additional sub-directory later SHOULD be added for all
-subjects in the dataset. Additional information on each session MAY be
-provided in a [sessions file](03-modality-agnostic-files.md#sessions-file)
+label for each session.
+In datasets where at least one subject has more than one session, this
+additional sub-directory later SHOULD be added for all subjects in the dataset.
+Additional information on each session MAY be provided in a
+[sessions file](03-modality-agnostic-files.md#sessions-file)
 within the subject directory.
 
 Within the session sub-directory (or the subject sub-directory if no
 session sub-directories are present) are sub-directories named according to
-data type as defined above. A data type directory SHOULD NOT be defined if
-there are no files to be placed in that directory.
+data type as defined above.
+A data type directory SHOULD NOT be defined if there are no files to be placed
+in that directory.
 
 ## File names
 
 A file name consists of a chain of *entity instances* and a *suffix*
-all separated by underscores, and an *extension*. This pattern forms
-file names that are both human- and machine-readable. For instance, file
-"`sub-01_task-rest_eeg.edf`" contains instances of the "subject" and
-"task" entities, making it evident from the file name alone that it
-contains resting-state data from subject `01`; the suffix `eeg`
-and extension `.edf` depend on the imaging modality and the data
+all separated by underscores, and an *extension*.
+This pattern forms file names that are both human- and machine-readable.
+For instance, file "`sub-01_task-rest_eeg.edf`" contains instances of the
+"subject" and "task" entities, making it evident from the file name alone that it
+contains resting-state data from subject `01`;
+the suffix `eeg` and extension `.edf` depend on the imaging modality and the data
 format, and can therefore convey further details of the file's contents.
 
 For a data file that was collected in a given session from a given
@@ -221,8 +227,8 @@ it uses the "acquisition" entity twice.
 In cases where an entity and a metadata field convey similar contextual
 information, the presence of an entity should not be used as a replacement for
 the corresponding metadata field.
-For instance, in echo-planar imaging MRI,
-the [`dir-<label>`](./99-appendices/09-entities.md#dir) entity MAY be used
+For instance, in echo-planar imaging MRI, the
+[`dir-<label>`](./99-appendices/09-entities.md#dir) entity MAY be used
 to distinguish files with different phase-encoding directions,
 but the file's `PhaseEncodingDirection` MUST be specified as metadata.
 

From bb3f70ec9cd5d4d625721a9bc36ebd82b3e9d575 Mon Sep 17 00:00:00 2001
From: Robert Smith <robert.smith@florey.edu.au>
Date: Tue, 26 Apr 2022 13:59:20 +1000
Subject: [PATCH 6/6] Common principles: Remark fixes

---
 src/02-common-principles.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/02-common-principles.md b/src/02-common-principles.md
index d6156a586b..62da6e2fb1 100644
--- a/src/02-common-principles.md
+++ b/src/02-common-principles.md
@@ -128,13 +128,17 @@ Each entity has the following attributes:
 
 1.  *Name*: A comprehensive name describing the context of information
     to be provided via the entity.
+
 1.  *Key*: A short string, typically a compression of the entity name,
     which uniquely identifies the entity when part of a file name.
+
 1.  *Value type*: The requisite form of the value that gets specified
     alongside the key whenever the entity appears in a file name.
     For each entity, the value is of one of two possible types:
+
     1.  *Index*: A non-negative integer, potentially zero-padded for
         consistent width.
+
     1.  *Label*: An alphanumeric string.
         Note that labels MUST not collide when casing is ignored
         (see [Case collision intolerance](#case-collision-intolerance)).