From 7d3b90e5acc83d77eae2b0a2e48eb7891404aa1a Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Thu, 19 Dec 2024 11:17:37 -0500
Subject: [PATCH] Add another example to inheritance principle for .json
 without entities

Upon re-reading current Inheritance principle formulation, nothing seems to
forbid that, and such use in general is great since allows to generalize
common metadata across all files of that datatype.

Notes on possible side-effects from "embracing" such approach (which in
principle I think is not disallowed ATM).

- per rule 4, presence of `bold.json` forbids presence of another `_bold.json`
  (i.e with entity) on the same level. So if further specialization e.g. per
  each task- is needed, common metadata needs to be duplicated across them
  (that is what heudiconv does ATM).

  Such restrictions could potentially be elevated if we adopt
  "summarization" refactoring of inheritance principle
  https://github.com/bids-standard/bids-2-devel/issues/65
  since order would stop to matter and thus multiple files can apply.

- I think that bids-validators are fine as checked on a single
  ds000248/T1w.json in bids-examples and modified 7t_trt.

- I do not know if tools implement it though but since there was precedence
  for ds000248/T1w.json - they better do ;-)
---
 src/common-principles.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/src/common-principles.md b/src/common-principles.md
index 9c2ff6c9f1..a407bb6586 100644
--- a/src/common-principles.md
+++ b/src/common-principles.md
@@ -852,6 +852,28 @@ A guide for using macros can be found at
     }
 ) }}
 
+Example 5: Generalization of Examples 1 and 4 for a sidecar file without entities
+
+<!-- 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(
+    {
+    "sub-01": {
+        "anat": {},
+        "func": {
+            "sub-01_task-xyz_acq-test1_run-1_bold.nii.gz": "",
+            "sub-01_task-xyz_acq-test1_run-2_bold.nii.gz": "",
+            }
+        },
+    "bold.json": "",
+    }
+) }}
+
+where `bold.json` in top directory would be applicable to all `_bold.nii.gz`
+regardless of any other entity in their filename.
+
 ## Participant names and other labels
 
 BIDS allows for custom user-defined `<label>`s and `<index>`es for example,