[SCHEMA] Support structured survey data as a BIDS modality

[karl-koschutnig]

Summary

This PR proposes adding schema support for structured instrument-based survey data as a valid BIDS representation, organized in the same subject-, session-, and run-resolved way as other BIDS modalities.

The goal is not to replace aggregated tabular phenotypic data. It is to complement them with a canonical acquisition-facing structure that preserves provenance, timing, and instrument context, while still allowing aggregated tables to be generated later when needed.

A working reference implementation already exists in PRISM Studio, with documentation at prism-studio.readthedocs.io.

Rationale

BIDS is strongest when its canonical structures reflect how data are actually acquired. For imaging, physio, events, and other modalities, the normative pattern is a subject-resolved structure first, with higher-level summaries and
derivatives produced later.

Instrument-based phenotypic data fit this same pattern. Treating phenotype/ as the only primary home for those data flattens acquisition context at the point where BIDS usually preserves it.

A structured survey modality would:

• preserve provenance and administration context,
• support repeated assessments across sessions and runs,
• keep sidecar metadata next to the corresponding data files, and
• still allow aggregated phenotype tables to be generated later.

That direction is structurally stronger because aggregated tables can be written from a structured survey layout with little ambiguity, whereas reconstructing the original structure from only an aggregate table often requires extra
assumptions.

Proposed Changes

This PR implements a minimal but complete first pass:

File	What changed
src/modality-specific-files/survey.md	New documentation page: file naming conventions, sidecar structure, instrument-level and item-level field tables, worked dataset structure and JSON/TSV examples
src/schema/objects/datatypes.yaml	Added survey datatype
src/schema/objects/modalities.yaml	Added survey modality
src/schema/objects/suffixes.yaml	Added survey suffix
src/schema/rules/files/raw/survey.yaml	New file rule using task entity template; .tsv and .json extensions
src/schema/rules/modalities.yaml	Mapped survey modality → survey datatype
mkdocs.yml	Added navigation entry

Example Structure

Below is the subject-, session-, and run-resolved structure this PR supports. A root-level sidecar applies to all matching files via the Inheritance Principle, avoiding duplication across sessions and runs. Per-file sidecars remain valid when instrument versions or languages differ between sessions.

study/
├── dataset_description.json
├── participants.tsv
├── task-pss_survey.json          ← shared sidecar via inheritance
├── sub-01/
│   ├── ses-baseline/
│   │   └── survey/
│   │       └── sub-01_ses-baseline_task-pss_run-01_survey.tsv
│   └── ses-week04/
│       └── survey/
│           ├── sub-01_ses-week04_task-pss_run-01_survey.tsv
│           └── sub-01_ses-week04_task-pss_run-02_survey.tsv
└── phenotype/
    └── pss_summary.tsv           ← optional aggregated downstream view

The phenotype/ directory in this example is deliberate. It shows that aggregated outputs remain compatible with this proposal, but they are downstream views of structured data rather than the only canonical form.

Reference Implementation

This proposal is grounded in an existing toolchain rather than a purely abstract design discussion:

• PRISM Studio repository
• PRISM Studio documentation
• Survey import template
• Survey schema and modality schemas
• Template validation documentation
• Dataset validation documentation

These references show that the proposed structure is already practical for curation, metadata authoring, template-based reuse, and validation.

Scope

This PR does not propose removing aggregated phenotype tables. It proposes that BIDS should also recognize a canonical modality-style structure for instrument-based phenotypic data, especially when those data are acquired repeatedly across sessions and runs.

Questions for Reviewers

• Should instrument-based phenotypic data be representable in a subject-, session-, and run-resolved modality structure in the schema?
• If so, should phenotype/ remain an optional aggregate or derived representation rather than the only primary representation?
• Is survey the right directory and suffix label, or should the working group prefer another term such as pheno, assess, form, inst, or meas?
• The current sidecar spec uses the task entity to identify the instrument (e.g. task-pss). Should a dedicated instrument entity be considered instead?
• The sidecar fields (TaskName, OriginalName, StimulusType, Respondent, etc.) follow existing BIDS conventions — are there missing fields, or any that should move between REQUIRED and OPTIONAL?

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.07%. Comparing base (308395f) to head (9c1a560).
⚠️ Report is 4 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #2404   +/-   ##
=======================================
  Coverage   83.07%   83.07%           
=======================================
  Files          22       22           
  Lines        1696     1696           
=======================================
  Hits         1409     1409           
  Misses        287      287           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[yarikoptic]

quick one (edited/expanded 2026/05/12):
Overall, I like this approach but immediate question -- is there semantical difference between "phenotype" and "survey" in this PR? if not, I would have preferred to stay consistent and make it phenotype/ (or pheno/) (I think I expressed smth like that elsewhere TODO: find refs here). It would then be a consistent principle we already have overall and distilling more for BEPs, e.g. for stimuli/ (@bids-standard/bep044 ; TODO: find/add refs). See:

• [ENH] BEP044 - Stim-BIDS #2022
  • rendered section on stimuli/
• BIDS 2̶.̶0̶1.0: flex BIDS layout (bids-2-devel/issues/54) #1809
• Formalize the concept of [{leading entities}_]{entity_plural}.{tsv,json} file(s) #2283

and potentially others, one way or another hinting on it, e.g

• Classify "phenotype/" as a datatype directory with no subject/session parent #1828

Then, if there is a desire to generalize "phenotype" into "survey" -- could be done for bids 2.0... WDYT?