Development environment

This page covers setting up a local environment to develop and test the BIDS Validator. For the higher-level fork-and-PR workflow, branching policy, and changelog conventions, see the contributing guide.

Prerequisites

• Deno (the BIDS Validator targets the Deno runtime).

• git.

• Optional: uv so you can run Python tools like scriv and pre-commit via uvx without installing them globally.

Cloning

Clone your fork of the repository (see contributing.md for the full fork workflow):

$ git clone https://github.com/<your-user>/bids-validator
$ cd bids-validator

Test datasets (required for the full test suite)

Several tests exercise the validator against sample BIDS datasets that live in a git submodule under tests/data/bids-examples/ (about 60 MB). Initialize it before running tests:

$ git submodule update --init tests/data/bids-examples

Running the CLI from source

You can run the validator directly from the source tree without installing it. The same -ERWN permission flags used by the published CLI (see Using the command line) work against the source entry point:

$ deno run -ERWN src/bids-validator.ts <path-to-dataset>

For example, against one of the example datasets:

$ deno run -ERWN src/bids-validator.ts tests/data/bids-examples/ds001

The -ERWN shorthand grants the four permissions the validator needs: environment variables (-E), filesystem read (-R), filesystem write (-W), and network (-N). Using these specific flags is preferred over -A (allow everything) because they document what the validator actually needs.

Installing the CLI locally

To install the validator as a regular bids-validator command on your PATH:

$ deno install -Agf --reload src/bids-validator.ts

Deno places the binary in its bin directory (typically $HOME/.deno/bin on Unix systems), which you may need to add to your PATH. The -Agf form here matches the existing contributing guide; to install with the same tighter permissions used above for deno run, substitute -ERWNgf --reload and the installed bids-validator will still work.

Running tests

After initializing the bids-examples submodule (see above), run the full test suite with:

$ deno task test

This is equivalent to deno test -A src/. To run a single test file:

$ deno test -A src/path/to/file.test.ts

Formatting and linting

Format code with:

$ deno fmt

Check formatting without modifying files:

$ deno fmt --check

Lint with:

$ deno lint

The deno fmt configuration in deno.json is scoped to the src/ directory; Markdown files under docs/ are not auto-formatted by deno fmt. Use your editor’s Markdown formatter (or leave them alone and match the surrounding style).

Pre-commit hooks (recommended)

The repository ships with a pre-commit configuration that runs basic file hygiene checks (trailing whitespace, end-of-file newlines, JSON/YAML/TOML syntax) and deno fmt. Install the hooks once after cloning:

$ uvx pre-commit install

After installation, the hooks run automatically on every git commit.

Changelog fragments

Most pull requests should include a changelog entry. The repository uses scriv to manage changelog fragments under changelog.d/. To create a fragment:

$ uvx scriv create --edit

Pick the appropriate section (Added, Changed, Fixed, Deprecated, Removed, Security, or Infrastructure) and write a one- to three-line description of your change. See contributing.md for the full changelog conventions.

Schema development

If you need to develop against an unreleased version of the BIDS schema, see the schema section of the README.