Skip to content

DOC: Clarify pitfall of ontological overreach in BEP definitions #669

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
oesteban wants to merge 4 commits into
base: main
Choose a base branch
from
Open

DOC: Clarify pitfall of ontological overreach in BEP definitions #669

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
016c705
enh: add a pitfall to the guidelines
oesteban Jun 10, 2025
85162c8
fix: missing word
oesteban Jun 10, 2025
a051af6
fix: replace 'neuroimaging' -> 'neuroscientific'
oesteban Jun 16, 2025
52427a0
Merge branch 'main' into enh/bep-development-tip
julia-pfarr May 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions docs/extensions/guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -203,6 +203,26 @@ We recommend that the core team has representatives from 3 different labs,
preferably also with a mix of more junior and more senior contributors.
You may also consider requesting explicit support letters from external labs.

### Confusing operational definitions with ontological ones

A common pitfall in BEP development is the attempt to define neuroscientific constructs—such as "participant", "atlas", or "template"—as if writing a comprehensive ontology or reference manual for the field.
While this effort may be intellectually rigorous and well-intentioned, it does not align with the purpose of the BIDS specification.

!!! warning "BIDS is not a general-purpose neuroscientific ontology."

BIDS is a pragmatic standard for organizing and describing data in a way that maximizes shareability, and supports automated tools, validation, and reproducible workflows.

BEPs should focus on definitions that are strictly necessary to enable BIDS to function. Definitions should be:

- **Operational**: they must serve a specific purpose in the file naming, metadata structure, or schema validation.
- **Internally consistent**: they should align with existing BIDS conventions and avoid redefining core concepts already in use.
- **Minimal and scoped**: they should avoid generalizing beyond what is needed for BIDS to interpret, validate, and process the data.

For example, rather than attempting to define what an experimental "run" means in all of neuroscience, BIDS specifies what qualifies as a `run-<index>` entity.
BEPs should make clear that the definitions they include are specific to BIDS and not intended to settle broader disciplinary debates.

Avoiding ontological overreach helps the community focus on implementation, adoption, and consensus-building, rather than epistemological disagreements that can delay or derail otherwise useful proposals.

## Specific guidelines

If multiple BEPs need coordination, this document (section below)
Expand Down
Loading