BIDS Schema Tools

Common errors

• AttributeError: module 'bidsschematools.schema' has no attribute 'load_schema'

  cause Attempting to use the `load_schema()` function which was removed in `bidsschematools` v1.2.0.
  fix Use `from bidsschematools import schema; bids_schema = schema.BIDS_SCHEMA.from_path('/path/to/schema')` instead.

• ModuleNotFoundError: No module named 'bidsschematools.schema.rules'

  cause Trying to import a module (`rules` or `objects`) that was removed in `bidsschematools` v1.1.0.
  fix Access schema properties directly from the main schema object, e.g., `bids_schema.rules` or `bids_schema.entities` after loading the schema.

• jsonschema.exceptions.ValidationError: '<value>' is not one of [<expected_values>]

  cause This is a generic JSON schema validation error indicating that a value in your BIDS metadata or filename does not conform to the expected values or format defined in the BIDS schema.
  fix Review the BIDS specification for the field or entity causing the error and adjust your data to match the required format or allowed values. The error message usually provides specific context on what was expected.

Warnings

• breaking The `bidsschematools.schema.load_schema()` function was removed and replaced by `BIDS_SCHEMA.from_path()` for loading custom or specific schema versions.
  Fix: Replace calls to `load_schema(path)` with `schema.BIDS_SCHEMA.from_path(path)`.
• breaking The modules `bidsschematools.schema.rules` (previously `rules_schema`) and `bidsschematools.schema.objects` were removed as part of internal refactoring to simplify schema access.
  Fix: These internal modules are no longer exposed. Access schema components directly through the `bids_schema` object (e.g., `bids_schema.entities`, `bids_schema.datatypes`).
• gotcha The library, by default, loads the latest stable version of the BIDS specification available at the time of its own release. If you need to validate against an older or a custom BIDS specification, you must explicitly load it using `BIDS_SCHEMA.from_path()`.
  Fix: Always confirm which BIDS specification version is loaded (`bids_schema.version`) and use `schema.BIDS_SCHEMA.from_path('/path/to/your/bids-specification')` if a specific version or custom schema is required.

Install

• pip install bidsschematools Install stable version

Imports

• BIDS_SCHEMA
  wrong:

  from bidsschematools.schema import BIDS_SCHEMA

  correct:

  from bidsschematools import schema
  bids_schema = schema.BIDS_SCHEMA

  While this import works, the official documentation encourages accessing BIDS_SCHEMA through the `schema` module to maintain consistency and allow easier access to other schema-related utilities.
• load_schema
  wrong:

  from bidsschematools.schema import load_schema

  correct:

  from bidsschematools import schema
  bids_schema = schema.BIDS_SCHEMA.from_path('/path/to/schema')

  `load_schema()` was removed in v1.2.0; use `BIDS_SCHEMA.from_path()` to load custom or specific schema versions.

Quickstart

This quickstart demonstrates how to load the default BIDS schema, inspect its properties like version and entities, and perform a basic check for filename pattern validity. For full dataset validation, a more complete BIDS dataset structure would be required.

from bidsschematools import schema
import pprint

# Load the default, current BIDS schema
bids_schema = schema.BIDS_SCHEMA

print(f"BIDS Schema Version: {bids_schema.version}")
print(f"Number of entities in schema: {len(bids_schema.entities)}")

# Accessing a specific entity definition
entity_sub = bids_schema.entities.get("subject")
if entity_sub:
    print("\n'subject' entity definition:")
    pprint.pprint(entity_sub)

# Example: Check if a filename pattern is valid according to schema rules
# Note: Full file validation requires a dataset context.
filename_pattern = "sub-<label>[_ses-<label>][_task-<label>]_bold.nii.gz"
is_valid_pattern = bids_schema.validate_pattern_string(filename_pattern)
print(f"\nIs example filename pattern valid according to schema? {is_valid_pattern}")

# To load a specific schema from a path:
# custom_schema = schema.BIDS_SCHEMA.from_path("path/to/your/custom_bids_schema_directory")