Brain Imaging Data Structure
Published May 6, 2026 | Version 3.0.0-alpha.3
Software Open

bids-validator

Authors/Creators

  • 1. Northern California Institute for Research and Education, San Francisco CA
  • 2. Stanford University
  • 3. MIT
  • 4. Google
  • 5. Dartmouth College
  • 6. Research Center Jülich; Heinrich-Heine University Düsseldorf
  • 7. Indiana University
  • 8. Berkeley Institute for Data Science; University of California at Berkeley
  • 9. AA Martinos Center for Biomedical Imaging, USA
  • 10. University of Texas at San Antonio
  • 11. Stony Brook University School of Medicine
  • 12. CYCERON imaging plateform, Caen, France
  • 13. Radboud University
  • 14. Heinrich-Heine University Düsseldorf
  • 15. National Institutes of Health
  • 16. Florida International University
  • 17. Pasteur Institute

Description

This is a release candidate for a major release that includes breaking changes to the public API. The CLI remains unchanged, but library users should review the changes below and update their code accordingly.

The primary user-facing changes in this release are the support for validating git trees and passing custom schemas to the web validator.

Thanks to Charan Sai Guttala, Yaroslav Halchenko and Dimitri Papadopoulos for their contributions to this release.

Added

  • --git-ref [REF] will validate a git tree at the given reference (tag, branch, tree or commit, defaulting to HEAD). Work trees and bare git repositories are supported. If omitted, the directory will be walked as a normal file tree, including untracked files, preserving the default behavior.

  • Allow custom schemas to be uploaded or passed by URL to the web validator.

  • Support symlinks to directories in git tree validation.

  • Report broken symbolic links as issues instead of crashing or silently ignoring. .bidsignored links are not reported. If resolution is not implemented, warnings are issued instead of errors.

  • Documented the library API: added a usage guide under docs/dev/using-the-api.md, JSDoc on validate(), and JSDoc with @throws on DatasetIssues.add().

  • New public subpaths expose primitives for building custom file sources: FileOpener, BIDSFile, FileTree, FileIgnoreRules, filesToTree, subtree, loadBidsIgnore, readBidsIgnore, and cross-environment openers (HTTPOpener, NullFileOpener).

  • detectErrors() is now part of the public surface under /validate.

  • UnknownIssueCodeError — DatasetIssues.add() now throws a typed error (instead of a plain Error) when called with an unrecognized issue code.

  • Stream helpers (createUTF8Stream, streamFromUint8Array, streamFromString, UnicodeDecodeError) exported from /files for custom opener authors.

Changed

  • Reorganized public API surface for v3. Library imports now use subpath-specific entry points (/validate, /files, /filetree, /files/deno, /files/browser, /files/git, /issues, /output, /cli). The root export (.) remains the CLI entry point.

Fixed

  • Use absolute path to .js within Dockerfile ENTRYPOINT, so could be found by singularity execution from arbitrary working directory

  • Treat symbolic links to directories as directories instead of files.

  • Compute opaque directories from the rules for the dataset's actual DatasetType instead of always using rules.directories.raw. This lets study-type datasets correctly ignore the rawbids/ subdataset (added in bids-standard/bids-specification#2191). Fixed in #389.

  • Derivative datasets no longer generate warnings or errors for sidecar keys that don't explicitly apply to derivative datasets.

  • Lazy-load the HED validator to reduce initial bundle size and resolve fs/promises background timer leaks during Deno tests.

Deprecated

  • @bids/validator/main — use /validate, /files/browser, /files/git instead. main() is preserved for back-compat; it has no replacement and will be removed in v4.
  • @bids/validator/options — use /validate (types) and /cli (validateCommand) instead. parseOptions() is preserved for back-compat; it has no replacement and will be removed in v4.
  • readFileTree and BIDSFileDeno re-exported from /files — use /files/deno instead.

Infrastructure

  • Addressed or ignored all deno lint issues. Future work should lint clean.

  • Added a developer environment guide under docs/dev/environment.md.

  • The main.js build target has been renamed web.js for clarity. It will no longer be saved to the deno-build branch.

  • Code-splitting was enabled in bundle configuration to make the validator more friendly to load in the browser or include in downstream bundled applications. The initial validator load transfers less than 400kB and only loads an additional 1.2MB if HED validation is required.

New Contributors

  • @DimitriPapadopoulos made their first contribution in https://github.com/bids-standard/bids-validator/pull/383

Full Changelog: https://github.com/bids-standard/bids-validator/compare/2.4.1...3.0.0-alpha.3

Notes

The bids-validator is a software tool to check neuroimaging datasets for adherence to the Brain Imaging Data Structure (BIDS) format. More information about BIDS can be found at bids.neuroimaging.io.

Files

bids-standard/bids-validator-3.0.0-alpha.3.zip

Files (5.0 MB)

Name Size Download all
md5:7d7a441adbd1552d8cba1b9538e0a98d
5.0 MB Preview Download

Additional details

Related works

Is supplement to
Software: https://github.com/bids-standard/bids-validator/tree/3.0.0-alpha.3 (URL)

Software

Repository URL
https://github.com/bids-standard/bids-validator