Move and extend description and definition of DatasetType "project"

Author: yarikoptic

src/common-principles.md

@@ -275,51 +275,6 @@ However, in the case that these data are to be included:
     We RECOMMEND including the PDF print-out with the actual sequence
     parameters generated by the scanner in the `sourcedata`  directory.
 
-Alternatively one can organize their data in the following way
-
-<!-- This block generates a file tree.
-A guide for using macros can be found at
- https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
--->
-{{ MACROS___make_filetree_example(
-    {
-    "my_dataset-1": {
-        "sourcedata": {
-            "dicoms": {},
-            "raw": {
-                "sub-01": {},
-                "sub-02": {},
-                "...": "",
-                "dataset_description.json": "",
-				"...": "",
-            },
-            "..." : "",
-        },
-        "derivatives": {
-            "pipeline_1": {},
-            "pipeline_2": {},
-            "...": "",
-        },
-        "dataset_description.json": "",
-        "...": "",
-    }
-   }
-) }}
-
-In this example, `sourcedata/dicoms` is not nested inside
-`sourcedata/raw`, **and only the `sourcedata/raw` subdirectory** is a BIDS-compliant dataset among `sourcedata/` subfolders.
-The subdirectories of `derivatives` MAY be BIDS-compliant derivatives datasets
-(see [Non-compliant derivatives](#non-compliant-derivatives) for further discussion).
-The above example is a fully compliant BIDS dataset, providing a convention useful for organizing source, raw BIDS, and derived BIDS data while maintaining overall BIDS compliance.
-When using this convention it is RECOMMENDED to set the `SourceDatasets`
-field in `dataset_description.json` of each subdirectory of `derivatives` to:
-
-```JSON
-{
-  "SourceDatasets": [ {"URL": "../../sourcedata/raw/"} ]
-}
-```
-
 !!! danger "Caution"
 
     Sharing source data may help amend errors and missing data discovered
@@ -443,6 +398,53 @@ In particular, if a BIDS dataset contains a `derivatives/` subdirectory,
 the contents of that directory may be a heterogeneous mix of BIDS Derivatives
 datasets and non-compliant derivatives.
 
+## Project dataset
+
+BIDS allows one to organize the data for the entire project (original source data, raw BIDS, derivatives) as a valid BIDS dataset in the following way
+
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example(
+    {
+    "my_project-1": {
+        "sourcedata": {
+            "dicoms": {},
+            "raw": {
+                "sub-01": {},
+                "sub-02": {},
+                "...": "",
+                "dataset_description.json": "",
+				"...": "",
+            },
+            "..." : "",
+        },
+        "derivatives": {
+            "pipeline_1": {},
+            "pipeline_2": {},
+            "...": "",
+        },
+        "dataset_description.json": "",
+        "...": "",
+    }
+   }
+) }}
+
+In this example, `sourcedata/dicoms` is not nested inside
+`sourcedata/raw`, **and only the `sourcedata/raw` subdirectory** is a BIDS-compliant dataset among `sourcedata/` subfolders.
+The subdirectories of `derivatives` MAY be BIDS-compliant derivatives datasets
+(see [Non-compliant derivatives](#non-compliant-derivatives) for further discussion).
+The above example is a fully compliant BIDS dataset, providing a convention useful for organizing source, raw BIDS, and derived BIDS data while maintaining overall BIDS compliance.
+When using this convention, `dataset_description.json` MUST have `DatasetType` to be set to `"project"`.  It is also RECOMMENDED to set the `SourceDatasets`
+field in `dataset_description.json` of each subdirectory of `derivatives` to:
+
+```JSON
+{
+  "SourceDatasets": [ {"URL": "../../sourcedata/raw/"} ]
+}
+```
+
 ## File format specification
 
 ### Imaging files

src/schema/objects/enums.yaml

@@ -1319,6 +1319,11 @@ derivative:
   display_name: derivative
   description: |
     A derived BIDS dataset.
+project:
+  value: project
+  display_name: project
+  description: |
+    A project BIDS dataset.
 balanced:
   value: balanced
   display_name: balanced

src/schema/objects/metadata.yaml

@@ -583,6 +583,7 @@ DatasetType:
   enum:
     - $ref: objects.enums.raw.value
     - $ref: objects.enums.derivative.value
+    - $ref: objects.enums.project.value
 DecayCorrectionFactor:
   name: DecayCorrectionFactor
   display_name: Decay Correction Factor

src/schema/rules/checks/dataset.yaml

@@ -6,10 +6,11 @@ SubjectFolders:
   issue:
     code: SUBJECT_FOLDERS
     message: |
-      There are no subject directories (labeled "sub-*") in the root of this dataset.
+      There are no subject directories (labeled "sub-*") in the root of this raw BIDS dataset.
     level: error
   selectors:
     - path == '/dataset_description.json'
+    - dataset.dataset_description.DatasetType == "raw"
   checks:
     - length(dataset.subjects.sub_dirs) > 0