From 0215e790eabd710e4afee932e01db8e815dca13f Mon Sep 17 00:00:00 2001
From: Taylor Salo <tsalo006@fiu.edu>
Date: Thu, 15 Feb 2024 11:47:05 -0500
Subject: [PATCH 1/7] Add descriptions.tsv to schema.

---
 src/schema/objects/files.yaml                            | 5 +++++
 src/schema/rules/files/deriv/tables.yaml                 | 7 +++++++
 .../tabular_data/derivatives/common_derivatives.yaml     | 9 +++++++++
 3 files changed, 21 insertions(+)
 create mode 100644 src/schema/rules/files/deriv/tables.yaml

diff --git a/src/schema/objects/files.yaml b/src/schema/objects/files.yaml
index 10cadf3bfa..acd9d84895 100644
--- a/src/schema/objects/files.yaml
+++ b/src/schema/objects/files.yaml
@@ -126,3 +126,8 @@ stimuli:
     A directory to store any stimulus files used during an experiment.
     See the [relevant section](SPEC_ROOT/modality-specific-files/task-events.md#stimuli-directory)
     for more information.
+descriptions:
+  display_name: Descriptions Definitions
+  file_type: regular
+  description: |
+    A TSV file describing labels found for the `desc` entity in a Derivatives dataset.
diff --git a/src/schema/rules/files/deriv/tables.yaml b/src/schema/rules/files/deriv/tables.yaml
new file mode 100644
index 0000000000..558390afd3
--- /dev/null
+++ b/src/schema/rules/files/deriv/tables.yaml
@@ -0,0 +1,7 @@
+---
+descriptions:
+  level: optional
+  stem: descriptions
+  extensions:
+    - .tsv
+    - .json
diff --git a/src/schema/rules/tabular_data/derivatives/common_derivatives.yaml b/src/schema/rules/tabular_data/derivatives/common_derivatives.yaml
index 3fef5e88fa..b101f314a1 100644
--- a/src/schema/rules/tabular_data/derivatives/common_derivatives.yaml
+++ b/src/schema/rules/tabular_data/derivatives/common_derivatives.yaml
@@ -10,3 +10,12 @@ SegmentationLookup:
     color: optional
     mapping: optional
   index_columns: [index]
+
+Descriptions:
+  selectors:
+    - path == "descriptions.tsv"
+  columns:
+    desc_id: required
+    description: required
+  index_columns: [desc_id, description]
+  additional_columns: allowed

From f21a6b9ce2b5bea161d890c2a6a651b6e2b130aa Mon Sep 17 00:00:00 2001
From: Taylor Salo <tsalo006@fiu.edu>
Date: Thu, 15 Feb 2024 11:53:59 -0500
Subject: [PATCH 2/7] Fix up column names.

---
 src/schema/objects/columns.yaml                     | 13 +++++++++++++
 .../derivatives/common_derivatives.yaml             |  4 ++--
 2 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/src/schema/objects/columns.yaml b/src/schema/objects/columns.yaml
index ba9f86ba31..d9e633c966 100644
--- a/src/schema/objects/columns.yaml
+++ b/src/schema/objects/columns.yaml
@@ -110,6 +110,13 @@ derived_from:
     for example a slice of tissue (`sample-02`) derived from a block of tissue (`sample-01`).
   type: string
   pattern: ^sample-[0-9a-zA-Z]+$
+desc_id:
+  name: desc_id
+  display_name: Description Label
+  description: |
+    A `desc-<label>` entity present in the derivatives dataset.
+  type: string
+  pattern: ^desc-[0-9a-zA-Z]+$
 description:
   name: description
   display_name: Description
@@ -122,6 +129,12 @@ description__optode:
   description: |
     Free-form text description of the optode, or other information of interest.
   type: string
+description__descriptions:
+  name: description
+  display_name: Description
+  description: |
+    Free-form text description of the desc entity's label (defined in `desc_id`).
+  type: string
 dimension:
   name: dimension
   display_name: Dimension
diff --git a/src/schema/rules/tabular_data/derivatives/common_derivatives.yaml b/src/schema/rules/tabular_data/derivatives/common_derivatives.yaml
index b101f314a1..21d8c86b8f 100644
--- a/src/schema/rules/tabular_data/derivatives/common_derivatives.yaml
+++ b/src/schema/rules/tabular_data/derivatives/common_derivatives.yaml
@@ -16,6 +16,6 @@ Descriptions:
     - path == "descriptions.tsv"
   columns:
     desc_id: required
-    description: required
-  index_columns: [desc_id, description]
+    description__descriptions: required
+  index_columns: [desc_id]
   additional_columns: allowed

From dd2d5911125739d3fa90de41bc0ce2baf3c8250c Mon Sep 17 00:00:00 2001
From: Taylor Salo <tsalo006@fiu.edu>
Date: Thu, 15 Feb 2024 12:27:20 -0500
Subject: [PATCH 3/7] Keep working on schema.

---
 src/derivatives/common-data-types.md          | 20 +++++++++----------
 src/schema/objects/columns.yaml               |  8 ++++++++
 src/schema/objects/suffixes.yaml              | 12 +++++++++++
 src/schema/rules/files/deriv/tables.yaml      |  6 +++++-
 .../derivatives/common_derivatives.yaml       |  6 +++++-
 5 files changed, 39 insertions(+), 13 deletions(-)

diff --git a/src/derivatives/common-data-types.md b/src/derivatives/common-data-types.md
index 55ad6e3bf1..d525164416 100644
--- a/src/derivatives/common-data-types.md
+++ b/src/derivatives/common-data-types.md
@@ -257,23 +257,21 @@ static volume, a `RepetitionTime` property would no longer be relevant).
 ## descriptions.tsv
 
 To keep a record of processing steps applied to the data, a `descriptions.tsv` file MAY be used.
-The `descriptions.tsv` file MUST contain at least the following two columns:
+The `descriptions.tsv` file consists of one row for each unique `desc-<label>`
+entity used in the dataset and a set of REQUIRED and OPTIONAL columns:
 
--   `desc_id`
--   `description`
+<!-- This block generates a columns table.
+The definitions of these fields can be found in
+  src/schema/rules/tabular_data/*.yaml
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_columns_table("derivatives.common_derivatives.Descriptions") }}
 
 This file MAY be located at the root of the derivative dataset,
 or at the subject or session level
 ([Inheritance Principle](../common-principles.md#the-inheritance-principle)).
 
-The `desc_id` column contains the labels used with the [`desc entity`](../appendices/entities.md#desc),
-within the particular nesting that the `descriptions.tsv` file is placed.
-For example, if the `descriptions.tsv` file is placed at the root of the derivative dataset,
-its `desc_id` column SHOULD contain all labels of the [`desc entity`](../appendices/entities.md#desc)
-used across the entire derivative dataset.
-
-The `description` column contains human-readable descriptions of the processing steps.
-
 The use of `descriptions.tsv` files together with the [`desc entity`](../appendices/entities.md#desc)
 are helpful to document how files are generated, even if their use may not be sufficient
 to provide full computational reproducibility.
diff --git a/src/schema/objects/columns.yaml b/src/schema/objects/columns.yaml
index d9e633c966..34d279e470 100644
--- a/src/schema/objects/columns.yaml
+++ b/src/schema/objects/columns.yaml
@@ -115,6 +115,14 @@ desc_id:
   display_name: Description Label
   description: |
     A `desc-<label>` entity present in the derivatives dataset.
+
+    The `desc_id` column contains the labels used with the
+    [`desc` entity](SPEC_ROOT/appendices/entities.md#desc),
+    within the particular nesting that the `descriptions.tsv` file is placed.
+
+    For example, if the `descriptions.tsv` file is placed at the root of the derivative dataset,
+    its `desc_id` column SHOULD contain all labels of the `desc` entity)
+    used across the entire derivative dataset.
   type: string
   pattern: ^desc-[0-9a-zA-Z]+$
 description:
diff --git a/src/schema/objects/suffixes.yaml b/src/schema/objects/suffixes.yaml
index 16e410c70d..bb474357bf 100644
--- a/src/schema/objects/suffixes.yaml
+++ b/src/schema/objects/suffixes.yaml
@@ -549,6 +549,18 @@ defacemask:
   description: |
     A binary mask that was used to remove facial features from an anatomical MRI
     image.
+descriptionts:
+  value: descriptionts
+  display_name: Description Entity Definitions
+  description: |
+    A TSV file describing labels found for the `desc` entity in a Derivatives dataset.
+
+    This file MAY be located at the root of the derivative dataset,
+    or at the subject or session level.
+
+    The use of `descriptions.tsv` files together with the desc entity are helpful to
+    document how files are generated,
+    even if their use may not be sufficient to provide full computational reproducibility.
 dseg:
   value: dseg
   display_name: Discrete Segmentation
diff --git a/src/schema/rules/files/deriv/tables.yaml b/src/schema/rules/files/deriv/tables.yaml
index 558390afd3..170f21b8ba 100644
--- a/src/schema/rules/files/deriv/tables.yaml
+++ b/src/schema/rules/files/deriv/tables.yaml
@@ -1,7 +1,11 @@
 ---
 descriptions:
   level: optional
-  stem: descriptions
+  suffixes:
+    - sessions
   extensions:
     - .tsv
     - .json
+  entities:
+    subject: optional
+    session: optional
diff --git a/src/schema/rules/tabular_data/derivatives/common_derivatives.yaml b/src/schema/rules/tabular_data/derivatives/common_derivatives.yaml
index 21d8c86b8f..424ed6cf08 100644
--- a/src/schema/rules/tabular_data/derivatives/common_derivatives.yaml
+++ b/src/schema/rules/tabular_data/derivatives/common_derivatives.yaml
@@ -13,7 +13,11 @@ SegmentationLookup:
 
 Descriptions:
   selectors:
-    - path == "descriptions.tsv"
+    - suffix == "descriptions"
+    - extension == ".tsv"
+  initial_columns:
+    - desc_id
+    - description__descriptions
   columns:
     desc_id: required
     description__descriptions: required

From cea7e0b343c8d8ca255cc975e8451b028caf8f11 Mon Sep 17 00:00:00 2001
From: Taylor Salo <tsalo006@fiu.edu>
Date: Thu, 15 Feb 2024 13:15:55 -0500
Subject: [PATCH 4/7] Fix mistakes and add template.

---
 src/derivatives/common-data-types.md     | 11 +++++++++++
 src/schema/objects/suffixes.yaml         |  4 ++--
 src/schema/rules/files/deriv/tables.yaml |  2 +-
 3 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/src/derivatives/common-data-types.md b/src/derivatives/common-data-types.md
index d525164416..bf3cbbe680 100644
--- a/src/derivatives/common-data-types.md
+++ b/src/derivatives/common-data-types.md
@@ -256,6 +256,17 @@ static volume, a `RepetitionTime` property would no longer be relevant).
 
 ## descriptions.tsv
 
+Template:
+
+```Text
+sub-<label>/
+    [ses-<label>/]
+        sub-<label>[_ses-<label>]_descriptions.tsv
+        sub-<label>[_ses-<label>]_descriptions.json
+```
+
+Optional: Yes
+
 To keep a record of processing steps applied to the data, a `descriptions.tsv` file MAY be used.
 The `descriptions.tsv` file consists of one row for each unique `desc-<label>`
 entity used in the dataset and a set of REQUIRED and OPTIONAL columns:
diff --git a/src/schema/objects/suffixes.yaml b/src/schema/objects/suffixes.yaml
index bb474357bf..1f36efe1d6 100644
--- a/src/schema/objects/suffixes.yaml
+++ b/src/schema/objects/suffixes.yaml
@@ -549,8 +549,8 @@ defacemask:
   description: |
     A binary mask that was used to remove facial features from an anatomical MRI
     image.
-descriptionts:
-  value: descriptionts
+descriptions:
+  value: descriptions
   display_name: Description Entity Definitions
   description: |
     A TSV file describing labels found for the `desc` entity in a Derivatives dataset.
diff --git a/src/schema/rules/files/deriv/tables.yaml b/src/schema/rules/files/deriv/tables.yaml
index 170f21b8ba..107be3fa7a 100644
--- a/src/schema/rules/files/deriv/tables.yaml
+++ b/src/schema/rules/files/deriv/tables.yaml
@@ -2,7 +2,7 @@
 descriptions:
   level: optional
   suffixes:
-    - sessions
+    - descriptions
   extensions:
     - .tsv
     - .json

From d384ff00c0ccd7c8c69dee54800b419cd4ebfe7b Mon Sep 17 00:00:00 2001
From: Taylor Salo <tsalo006@fiu.edu>
Date: Thu, 15 Feb 2024 16:44:56 -0500
Subject: [PATCH 5/7] Update src/derivatives/common-data-types.md

Co-authored-by: Chris Markiewicz <effigies@gmail.com>
---
 src/derivatives/common-data-types.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/derivatives/common-data-types.md b/src/derivatives/common-data-types.md
index bf3cbbe680..5a2e725e91 100644
--- a/src/derivatives/common-data-types.md
+++ b/src/derivatives/common-data-types.md
@@ -259,10 +259,10 @@ static volume, a `RepetitionTime` property would no longer be relevant).
 Template:
 
 ```Text
-sub-<label>/
+[sub-<label>/]
     [ses-<label>/]
-        sub-<label>[_ses-<label>]_descriptions.tsv
-        sub-<label>[_ses-<label>]_descriptions.json
+        [sub-<label>_][ses-<label>_]descriptions.tsv
+        [sub-<label>_][ses-<label>_]descriptions.json
 ```
 
 Optional: Yes

From 4d154602a630aeb8052fd29257d4d70ac06c6ca8 Mon Sep 17 00:00:00 2001
From: Taylor Salo <tsalo006@fiu.edu>
Date: Fri, 16 Feb 2024 12:12:47 -0500
Subject: [PATCH 6/7] Make description column generic.

---
 src/schema/objects/columns.yaml                            | 4 ++--
 .../rules/tabular_data/derivatives/common_derivatives.yaml | 7 +++++--
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/src/schema/objects/columns.yaml b/src/schema/objects/columns.yaml
index 34d279e470..49655a2584 100644
--- a/src/schema/objects/columns.yaml
+++ b/src/schema/objects/columns.yaml
@@ -137,11 +137,11 @@ description__optode:
   description: |
     Free-form text description of the optode, or other information of interest.
   type: string
-description__descriptions:
+description__entities:
   name: description
   display_name: Description
   description: |
-    Free-form text description of the desc entity's label (defined in `desc_id`).
+    Free-form text description of the entity's label (defined in `<entity>_id` column).
   type: string
 dimension:
   name: dimension
diff --git a/src/schema/rules/tabular_data/derivatives/common_derivatives.yaml b/src/schema/rules/tabular_data/derivatives/common_derivatives.yaml
index 424ed6cf08..01b8bb04ea 100644
--- a/src/schema/rules/tabular_data/derivatives/common_derivatives.yaml
+++ b/src/schema/rules/tabular_data/derivatives/common_derivatives.yaml
@@ -17,9 +17,12 @@ Descriptions:
     - extension == ".tsv"
   initial_columns:
     - desc_id
-    - description__descriptions
+    - description__entities
   columns:
     desc_id: required
-    description__descriptions: required
+    description__entities:
+      level: required
+      description_addendum: |
+        The corresponding label column is `desc_id`.
   index_columns: [desc_id]
   additional_columns: allowed

From 1ae874fa84737eef39b5bce0bdbed86a08af4f01 Mon Sep 17 00:00:00 2001
From: Taylor Salo <tsalo006@fiu.edu>
Date: Thu, 22 Feb 2024 14:01:50 -0500
Subject: [PATCH 7/7] Remove duplicate file definition.

descriptions is a suffix, rather than a file.
---
 src/schema/objects/files.yaml | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/src/schema/objects/files.yaml b/src/schema/objects/files.yaml
index acd9d84895..10cadf3bfa 100644
--- a/src/schema/objects/files.yaml
+++ b/src/schema/objects/files.yaml
@@ -126,8 +126,3 @@ stimuli:
     A directory to store any stimulus files used during an experiment.
     See the [relevant section](SPEC_ROOT/modality-specific-files/task-events.md#stimuli-directory)
     for more information.
-descriptions:
-  display_name: Descriptions Definitions
-  file_type: regular
-  description: |
-    A TSV file describing labels found for the `desc` entity in a Derivatives dataset.