From 917ddb7fe7ac84206fa9c312459df29aa3f4ea55 Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Mon, 11 Nov 2024 18:02:00 -0500
Subject: [PATCH] RF(schema): harmonize into dirs, ids, ids_phenotype

Current names duplicate their "domain" (subject_ or session_), inconsistent in
plurality (_id although for all ids), and not clear really what
'phenotype' corresponds to without reading the description.

With proposed change there is no duplication of the domain, consistency
in plurality (albeit 'id' is an abbreviation so 'ids' is a non-word), and
IMHO clearer meaning in `ids_phenotype`.

This would also allow for generalization across other entities in a perspective
https://github.com/bids-standard/bids-2-devel/issues/54 - where then any entity
with folders for its level could have `dirs`. Also it could come handy to
determine `ids` for some other entities in tests.

Ref: https://github.com/bids-standard/bids-validator/pull/94#discussion_r1836876737

TODOs
- [ ] introduce corresponding changes to bids-validator
---
 src/schema/meta/context.yaml         | 16 ++++++++--------
 src/schema/rules/checks/dataset.yaml |  8 ++++----
 tools/typescript/generate.test.ts    |  8 ++++----
 3 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/src/schema/meta/context.yaml b/src/schema/meta/context.yaml
index 8783b46371..5f120d877e 100644
--- a/src/schema/meta/context.yaml
+++ b/src/schema/meta/context.yaml
@@ -67,20 +67,20 @@ properties:
         description: 'Collections of subjects in dataset'
         type: object
         required:
-          - sub_dirs
+          - dirs
         additionalProperties: false
         properties:
-          sub_dirs:
+          dirs:
             description: 'Subjects as determined by sub-* directories'
             type: array
             items:
               type: string
-          participant_id:
+          ids:
             description: 'The participant_id column of participants.tsv'
             type: array
             items:
               type: string
-          phenotype:
+          ids_phenotype:
             description: 'The union of participant_id columns in phenotype files'
             type: array
             items:
@@ -96,20 +96,20 @@ properties:
         description: 'Collections of sessions in subject'
         type: object
         required:
-          - ses_dirs
+          - dirs
         additionalProperties: false
         properties:
-          ses_dirs:
+          dirs:
             description: 'Sessions as determined by ses-* directories'
             type: array
             items:
               type: string
-          session_id:
+          ids:
             description: 'The session_id column of sessions.tsv'
             type: array
             items:
               type: string
-          phenotype:
+          ids_phenotype:
             description: 'The union of session_id columns in phenotype files'
             type: array
             items:
diff --git a/src/schema/rules/checks/dataset.yaml b/src/schema/rules/checks/dataset.yaml
index 69444aed9e..79c2956dbc 100644
--- a/src/schema/rules/checks/dataset.yaml
+++ b/src/schema/rules/checks/dataset.yaml
@@ -11,7 +11,7 @@ SubjectFolders:
   selectors:
     - path == '/dataset_description.json'
   checks:
-    - length(dataset.subjects.sub_dirs) > 0
+    - length(dataset.subjects.dirs) > 0
 
 # 49
 ParticipantIDMismatch:
@@ -24,7 +24,7 @@ ParticipantIDMismatch:
   selectors:
     - path == '/participants.tsv'
   checks:
-    - allequal(sorted(columns.participant_id), sorted(dataset.subjects.sub_dirs))
+    - allequal(sorted(columns.participant_id), sorted(dataset.subjects.dirs))
 
 # 51
 PhenotypeSubjectsMissing:
@@ -35,9 +35,9 @@ PhenotypeSubjectsMissing:
     level: error
   selectors:
     - path == '/dataset_description.json'
-    - type(dataset.subjects.phenotype) != 'null'
+    - type(dataset.subjects.ids_phenotype) != 'null'
   checks:
-    - allequal(sorted(dataset.subjects.phenotype), sorted(dataset.subjects.sub_dirs))
+    - allequal(sorted(dataset.subjects.ids_phenotype), sorted(dataset.subjects.dirs))
 
 # 214
 SamplesTSVMissing:
diff --git a/tools/typescript/generate.test.ts b/tools/typescript/generate.test.ts
index dc9342f7f3..296c14c07a 100644
--- a/tools/typescript/generate.test.ts
+++ b/tools/typescript/generate.test.ts
@@ -53,14 +53,14 @@ Deno.test('generateTypes() supports generic array type', () => {
 Deno.test('generateTypes() supports typed array type', () => {
   const file = createSourceFile('test.ts')
   file.statements = generateTypes({
-    sub_dirs: {
+    dirs: {
       description: 'Subjects as determined by sub-*/ directories',
       type: 'array',
       items: { type: 'string' },
     },
   })
 
-  assertEquals(print(file), 'sub_dirs: string[];\n')
+  assertEquals(print(file), 'dirs: string[];\n')
 })
 
 // Object without defined properties
@@ -134,7 +134,7 @@ Deno.test('generateTypes() supports object trees', () => {
           description: 'Collections of subjects in dataset',
           type: 'object',
           properties: {
-            sub_dirs: {
+            dirs: {
               description: 'Subjects as determined by sub-*/ directories',
               type: 'array',
               items: { type: 'string' },
@@ -148,7 +148,7 @@ Deno.test('generateTypes() supports object trees', () => {
   assertEquals(
     print(file),
     `export interface DatasetSubjects {
-    sub_dirs: string[];
+    dirs: string[];
 }
 export interface Dataset {
     dataset_description: object;