[MISC] Clarify participant_id in participants.tsv file if it exists (#738)

* Adding clarification.

* Fix clarifications.

* Fix link.

* Apply suggestions from code review

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

* Add link back.

* Update src/06-longitudinal-and-multi-site-studies.md

* Apply suggestions from code review

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

* Update src/06-longitudinal-and-multi-site-studies.md

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

* Fix docs.

* line breaks

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

Author: 3 people

src/03-modality-agnostic-files.md

@@ -162,9 +162,9 @@ participants.json
 
 The purpose of this RECOMMENDED file is to describe properties of participants
 such as age, sex, handedness.
-In case of single-session studies, this file has one compulsory column
-`participant_id` that consists of `sub-<label>`, followed by a list of optional
-columns describing participants.
+If this file exists, it MUST contain the column `participant_id`,
+which MUST consist of `sub-<label>` values identifying one row for each participant,
+followed by a list of optional columns describing participants.
 Each participant MUST be described by one and only one row.
 
 Commonly used *optional* columns in `participant.tsv` files are `age`, `sex`,

src/06-longitudinal-and-multi-site-studies.md

@@ -1,18 +1,20 @@
 # Longitudinal and multi-site studies
 
 Multiple sessions (visits) are encoded by adding an extra layer of directories
-and file names in the form of `ses-<label>`. Session label can consist
-only of alphanumeric characters `[a-zA-Z0-9]` and should be consistent across
-subjects. If numbers are used in session labels we recommend using zero padding
+and file names in the form of `ses-<label>`.
+Session labels MUST consist only of alphanumeric characters `[a-zA-Z0-9]`
+and SHOULD be consistent across subjects.
+If numbers are used in session labels we RECOMMEND using zero padding
 (for example `ses-01`, `ses-11` instead of `ses-1`, `ses-11`). This makes
 results of alphabetical sorting more intuitive. Acquisition time of session can
-be defined in the sessions file (see below for details).
+be defined in the [sessions file](#sessions-file).
 
-The extra session layer (at least one `/ses-<label>` subfolder) should
+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. Skipping the session layer for only some subjects in the dataset is
-not allowed. If a `/ses-<label>` subfolder is included as part of the
-directory hierarchy, then the same `ses-<label>` tag must also be
+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.
 
 ```Text
@@ -71,11 +73,11 @@ sub-<label>/
 Optional: Yes
 
 In case of multiple sessions there is an option of adding additional
-participant key files describing variables changing between sessions. In such
-case one file per participant should be added. These files need to include
-compulsory `session_id` column and describe each session by one and only one
-row. Column names in per participant key files have to be different from group
-level participant key column names.
+`sessions.tsv` files describing variables changing between sessions.
+In such case one file per participant SHOULD be added.
+These files MUST include a `session_id` column and describe each session by one and only one row.
+Column names in `sessions.tsv` files MUST be different from group level participant key column names in the
+[`participants.tsv` file](./03-modality-agnostic-files.md#participants-file).
 
 `_sessions.tsv` example: