From 48f763a4ecaa95444135739b83e077d9dbeba0ea Mon Sep 17 00:00:00 2001
From: Seyed Yahya Shirazi <shirazi@ieee.org>
Date: Fri, 12 Sep 2025 11:37:47 -0700
Subject: [PATCH 1/4] feat: Add generic root-level template macro for
 non-datatype directories

- Create make_root_filename_template macro for root-level directories like /stimuli
- Update bidsschematools to skip path-based rules (without datatypes) in entity table and filename templates
- Remove stimuli from entity-table.md as it doesn't follow subject-scoped entity ordering
- Dynamically look up entity definitions from schema instead of hardcoding mappings
---
 src/appendices/entity-table.md                |  4 ---
 tools/mkdocs_macros_bids/macros.py            | 35 ++++++++++++++-----
 .../src/bidsschematools/render/tables.py      |  4 +++
 .../src/bidsschematools/render/text.py        |  3 ++
 4 files changed, 34 insertions(+), 12 deletions(-)

diff --git a/src/appendices/entity-table.md b/src/appendices/entity-table.md
index 549b0685fb..bf69bdc863 100644
--- a/src/appendices/entity-table.md
+++ b/src/appendices/entity-table.md
@@ -61,7 +61,3 @@ while entity definitions are in the [Entities Appendix](entities.md).
 ## Motion
 
 {{ MACROS___make_entity_table(datatypes=["motion"]) }}
-
-## Stimulus Files
-
-{{ MACROS___make_entity_table(datatypes=["stimuli"]) }}
diff --git a/tools/mkdocs_macros_bids/macros.py b/tools/mkdocs_macros_bids/macros.py
index 03d0ddc57b..09f9f3ecb5 100644
--- a/tools/mkdocs_macros_bids/macros.py
+++ b/tools/mkdocs_macros_bids/macros.py
@@ -112,7 +112,18 @@ def make_root_filename_template(
     if src_path is None:
         src_path = _get_source_path()
 
-    schema_obj = schema.load_schema()
+    # Load schema with explicit path to avoid caching issues
+    import os
+
+    schema_path = os.path.join(
+        os.path.dirname(os.path.dirname(os.path.dirname(__file__))),
+        "src",
+        "schema.json",
+    )
+    if os.path.exists(schema_path):
+        schema_obj = schema.load_schema(schema_path)
+    else:
+        schema_obj = schema.load_schema()
 
     # Look for rules that have a specific path (root-level organization)
     target_path = kwargs.get("path", "stimuli")  # Default to stimuli
@@ -147,17 +158,25 @@ def make_root_filename_template(
                     template_lines.append(f"    {rule.stem}{ext}")
 
         elif hasattr(rule, "suffixes"):
-            # Handle entity-based files (like stim-<label>_audio.wav)
+            # Handle entity-based files generically using entity definitions from schema
             entities_part = ""
             if hasattr(rule, "entities"):
                 entity_parts = []
                 for entity_name, requirement in rule.entities.items():
-                    if entity_name == "stimulus":
-                        entity_parts.append("stim-<label>")
-                    elif entity_name == "part":
-                        entity_parts.append("[_part-<label>]")
-                    elif entity_name == "annotation":
-                        entity_parts.append("_annot-<label>")
+                    # Look up the entity in the schema to get its prefix
+                    if entity_name in schema_obj.objects.entities:
+                        entity_def = schema_obj.objects.entities[entity_name]
+                        entity_prefix = entity_def.get("name", entity_name)
+
+                        # Format based on requirement (required vs optional)
+                        if requirement == "optional":
+                            entity_parts.append(f"[_{entity_prefix}-<label>]")
+                        else:
+                            # First entity doesn't need underscore prefix
+                            if not entity_parts:
+                                entity_parts.append(f"{entity_prefix}-<label>")
+                            else:
+                                entity_parts.append(f"_{entity_prefix}-<label>")
                 entities_part = "".join(entity_parts)
 
             for suffix in rule.suffixes:
diff --git a/tools/schemacode/src/bidsschematools/render/tables.py b/tools/schemacode/src/bidsschematools/render/tables.py
index e650136fc1..e7ab4062b4 100644
--- a/tools/schemacode/src/bidsschematools/render/tables.py
+++ b/tools/schemacode/src/bidsschematools/render/tables.py
@@ -309,6 +309,10 @@ def make_entity_table(schema, tablefmt="github", src_path=None, **kwargs):
         if not suffixes:
             continue
 
+        # Skip rules that don't have datatypes (e.g., stimuli rules with path-based organization)
+        if not hasattr(rule, "datatypes"):
+            continue
+
         entities = []
         for ent in schema.rules.entities:
             val = rule.entities.get(ent, "")
diff --git a/tools/schemacode/src/bidsschematools/render/text.py b/tools/schemacode/src/bidsschematools/render/text.py
index 6333869f23..6b889cf560 100644
--- a/tools/schemacode/src/bidsschematools/render/text.py
+++ b/tools/schemacode/src/bidsschematools/render/text.py
@@ -324,6 +324,9 @@ def make_filename_template(
     file_rules = schema.rules.files[dstype]
     file_groups = {}
     for rule in file_rules.values(level=2):
+        # Skip rules that don't have datatypes (e.g., stimuli rules with path-based organization)
+        if not hasattr(rule, "datatypes"):
+            continue
         for datatype in rule.datatypes:
             file_groups.setdefault(datatype, []).append(rule)
 

From 4a440e6ba2ce1130149f215fb537f333aad31c43 Mon Sep 17 00:00:00 2001
From: Seyed Yahya Shirazi <shirazi@ieee.org>
Date: Fri, 12 Sep 2025 12:07:36 -0700
Subject: [PATCH 2/4] fix: Update test_make_filename_template to skip rules
 without datatypes

The test was failing because it tried to access datatypes attribute on all rules,
including the new stimuli rules that use path-based organization instead.
---
 tools/schemacode/src/bidsschematools/tests/test_render_text.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/tools/schemacode/src/bidsschematools/tests/test_render_text.py b/tools/schemacode/src/bidsschematools/tests/test_render_text.py
index e4029e49f6..299f1de7e7 100644
--- a/tools/schemacode/src/bidsschematools/tests/test_render_text.py
+++ b/tools/schemacode/src/bidsschematools/tests/test_render_text.py
@@ -93,6 +93,7 @@ def test_make_filename_template(schema_obj, schema_dir, placeholders):
     datatypes = {
         datatype
         for rule in schema_obj.rules.files.raw.values(level=2)
+        if hasattr(rule, "datatypes")  # Skip rules without datatypes (e.g., stimuli)
         for datatype in rule.datatypes
     }
 

From 7155ee4cef8f5a81ee10ecf0d9aa15a56d9a9283 Mon Sep 17 00:00:00 2001
From: Seyed Yahya Shirazi <shirazi@ieee.org>
Date: Fri, 12 Sep 2025 12:18:13 -0700
Subject: [PATCH 3/4] fix: Update schema loading for sidecar tables and
 temporarily disable stimuli tables

- Add explicit schema path loading to make_sidecar_table to avoid caching issues
- Temporarily comment out stimuli.Stimuli tables that need namespace fixes
- File tree generation from schema is now working for /stimuli directory
---
 src/modality-agnostic-files/stimuli.md |  6 +++---
 tools/mkdocs_macros_bids/macros.py     | 13 ++++++++++++-
 2 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/src/modality-agnostic-files/stimuli.md b/src/modality-agnostic-files/stimuli.md
index 04b0a6b7ca..f3e58a5f22 100644
--- a/src/modality-agnostic-files/stimuli.md
+++ b/src/modality-agnostic-files/stimuli.md
@@ -58,7 +58,7 @@ The definitions of the fields specified in these tables may be found in
 A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-{{ MACROS___make_sidecar_table("stimuli.Stimuli") }}
+<!-- Table for stimulus metadata fields will be inserted here once schema loading issue is resolved -->
 
 In some cases, such as observing the copyright of a stimulus file, the actual stimulus file may not be shared. In such cases, the `stim-<label>_<suffix>.json` file SHOULD be used to provide metadata about the stimulus file, including the license, copyright, URL, and description.
 
@@ -89,7 +89,7 @@ The definitions of these fields can be found in
 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("stimuli.Stimuli") }}
+<!-- Columns table to be fixed: stimuli.Stimuli -->
 
 ### Example `stimuli.tsv`
 
@@ -125,7 +125,7 @@ The definitions of these fields can be found in
 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("stimuli.Annotations") }}
+<!-- Columns table to be fixed: stimuli.Annotations -->
 
 ### Example `*_annotations.tsv`
 
diff --git a/tools/mkdocs_macros_bids/macros.py b/tools/mkdocs_macros_bids/macros.py
index 09f9f3ecb5..470890bac3 100644
--- a/tools/mkdocs_macros_bids/macros.py
+++ b/tools/mkdocs_macros_bids/macros.py
@@ -372,7 +372,18 @@ def make_sidecar_table(table_name, src_path=None):
     if src_path is None:
         src_path = _get_source_path()
 
-    schema_obj = schema.load_schema()
+    # Load schema with explicit path to avoid caching issues
+    import os
+
+    schema_path = os.path.join(
+        os.path.dirname(os.path.dirname(os.path.dirname(__file__))),
+        "src",
+        "schema.json",
+    )
+    if os.path.exists(schema_path):
+        schema_obj = schema.load_schema(schema_path)
+    else:
+        schema_obj = schema.load_schema()
     table = render.make_sidecar_table(schema_obj, table_name, src_path=src_path)
     return table
 

From 5725810eba4fa098ee5a58f58df1f240ac95d196 Mon Sep 17 00:00:00 2001
From: Seyed Yahya Shirazi <shirazi@ieee.org>
Date: Fri, 12 Sep 2025 12:43:44 -0700
Subject: [PATCH 4/4] fix: Complete stimuli documentation with working
 schema-driven templates

- Fix entity format labels in root template macro (use <label> instead of hardcoded)
- Add explicit schema loading to make_columns_table to avoid caching issues
- Re-enable all stimuli tables (sidecar and columns) that now work correctly
- File tree now properly shows stim-<label>[_part-<label>] format
---
 src/modality-agnostic-files/stimuli.md |  6 +++---
 tools/mkdocs_macros_bids/macros.py     | 26 +++++++++++++++++++++-----
 2 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/src/modality-agnostic-files/stimuli.md b/src/modality-agnostic-files/stimuli.md
index f3e58a5f22..04b0a6b7ca 100644
--- a/src/modality-agnostic-files/stimuli.md
+++ b/src/modality-agnostic-files/stimuli.md
@@ -58,7 +58,7 @@ The definitions of the fields specified in these tables may be found in
 A guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-<!-- Table for stimulus metadata fields will be inserted here once schema loading issue is resolved -->
+{{ MACROS___make_sidecar_table("stimuli.Stimuli") }}
 
 In some cases, such as observing the copyright of a stimulus file, the actual stimulus file may not be shared. In such cases, the `stim-<label>_<suffix>.json` file SHOULD be used to provide metadata about the stimulus file, including the license, copyright, URL, and description.
 
@@ -89,7 +89,7 @@ The definitions of these fields can be found in
 and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-<!-- Columns table to be fixed: stimuli.Stimuli -->
+{{ MACROS___make_columns_table("stimuli.Stimuli") }}
 
 ### Example `stimuli.tsv`
 
@@ -125,7 +125,7 @@ The definitions of these fields can be found in
 and a guide for using macros can be found at
  https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
 -->
-<!-- Columns table to be fixed: stimuli.Annotations -->
+{{ MACROS___make_columns_table("stimuli.Annotations") }}
 
 ### Example `*_annotations.tsv`
 
diff --git a/tools/mkdocs_macros_bids/macros.py b/tools/mkdocs_macros_bids/macros.py
index 470890bac3..6395ca9641 100644
--- a/tools/mkdocs_macros_bids/macros.py
+++ b/tools/mkdocs_macros_bids/macros.py
@@ -163,20 +163,25 @@ def make_root_filename_template(
             if hasattr(rule, "entities"):
                 entity_parts = []
                 for entity_name, requirement in rule.entities.items():
-                    # Look up the entity in the schema to get its prefix
+                    # Look up the entity in the schema to get its prefix and format
                     if entity_name in schema_obj.objects.entities:
                         entity_def = schema_obj.objects.entities[entity_name]
                         entity_prefix = entity_def.get("name", entity_name)
+                        entity_format = entity_def.get("format", "label")
 
                         # Format based on requirement (required vs optional)
                         if requirement == "optional":
-                            entity_parts.append(f"[_{entity_prefix}-<label>]")
+                            entity_parts.append(f"[_{entity_prefix}-<{entity_format}>]")
                         else:
                             # First entity doesn't need underscore prefix
                             if not entity_parts:
-                                entity_parts.append(f"{entity_prefix}-<label>")
+                                entity_parts.append(
+                                    f"{entity_prefix}-<{entity_format}>"
+                                )
                             else:
-                                entity_parts.append(f"_{entity_prefix}-<label>")
+                                entity_parts.append(
+                                    f"_{entity_prefix}-<{entity_format}>"
+                                )
                 entities_part = "".join(entity_parts)
 
             for suffix in rule.suffixes:
@@ -442,7 +447,18 @@ def make_columns_table(table_name, src_path=None):
     if src_path is None:
         src_path = _get_source_path()
 
-    schema_obj = schema.load_schema()
+    # Load schema with explicit path to avoid caching issues
+    import os
+
+    schema_path = os.path.join(
+        os.path.dirname(os.path.dirname(os.path.dirname(__file__))),
+        "src",
+        "schema.json",
+    )
+    if os.path.exists(schema_path):
+        schema_obj = schema.load_schema(schema_path)
+    else:
+        schema_obj = schema.load_schema()
     table = render.make_columns_table(schema_obj, table_name, src_path=src_path)
     return table