{"id":7980,"library":"bidsschematools","title":"BIDS Schema Tools","description":"bidsschematools is a Python library providing utilities for programmatic interaction with the Brain Imaging Data Structure (BIDS) schema. It enables loading, parsing, and validating BIDS datasets against the official specification. The current version is 1.2.2, with releases typically coinciding with major BIDS specification updates or essential bug fixes and enhancements.","status":"active","version":"1.2.2","language":"en","source_language":"en","source_url":"https://github.com/bids-standard/bidsschematools","tags":["BIDS","neuroscience","schema","validation","data-standard","brain-imaging"],"install":[{"cmd":"pip install bidsschematools","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for JSON schema validation.","package":"jsonschema","optional":false},{"reason":"Used for data validation and settings management.","package":"pydantic","optional":false},{"reason":"Used for parsing YAML-based schema definitions.","package":"pyyaml","optional":false}],"imports":[{"note":"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.","wrong":"from bidsschematools.schema import BIDS_SCHEMA","symbol":"BIDS_SCHEMA","correct":"from bidsschematools import schema\nbids_schema = schema.BIDS_SCHEMA"},{"note":"`load_schema()` was removed in v1.2.0; use `BIDS_SCHEMA.from_path()` to load custom or specific schema versions.","wrong":"from bidsschematools.schema import load_schema","symbol":"load_schema","correct":"from bidsschematools import schema\nbids_schema = schema.BIDS_SCHEMA.from_path('/path/to/schema')"}],"quickstart":{"code":"from bidsschematools import schema\nimport pprint\n\n# Load the default, current BIDS schema\nbids_schema = schema.BIDS_SCHEMA\n\nprint(f\"BIDS Schema Version: {bids_schema.version}\")\nprint(f\"Number of entities in schema: {len(bids_schema.entities)}\")\n\n# Accessing a specific entity definition\nentity_sub = bids_schema.entities.get(\"subject\")\nif entity_sub:\n    print(\"\\n'subject' entity definition:\")\n    pprint.pprint(entity_sub)\n\n# Example: Check if a filename pattern is valid according to schema rules\n# Note: Full file validation requires a dataset context.\nfilename_pattern = \"sub-<label>[_ses-<label>][_task-<label>]_bold.nii.gz\"\nis_valid_pattern = bids_schema.validate_pattern_string(filename_pattern)\nprint(f\"\\nIs example filename pattern valid according to schema? {is_valid_pattern}\")\n\n# To load a specific schema from a path:\n# custom_schema = schema.BIDS_SCHEMA.from_path(\"path/to/your/custom_bids_schema_directory\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Replace calls to `load_schema(path)` with `schema.BIDS_SCHEMA.from_path(path)`.","message":"The `bidsschematools.schema.load_schema()` function was removed and replaced by `BIDS_SCHEMA.from_path()` for loading custom or specific schema versions.","severity":"breaking","affected_versions":">=1.2.0"},{"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`).","message":"The modules `bidsschematools.schema.rules` (previously `rules_schema`) and `bidsschematools.schema.objects` were removed as part of internal refactoring to simplify schema access.","severity":"breaking","affected_versions":">=1.1.0"},{"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.","message":"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()`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Use `from bidsschematools import schema; bids_schema = schema.BIDS_SCHEMA.from_path('/path/to/schema')` instead.","cause":"Attempting to use the `load_schema()` function which was removed in `bidsschematools` v1.2.0.","error":"AttributeError: module 'bidsschematools.schema' has no attribute 'load_schema'"},{"fix":"Access schema properties directly from the main schema object, e.g., `bids_schema.rules` or `bids_schema.entities` after loading the schema.","cause":"Trying to import a module (`rules` or `objects`) that was removed in `bidsschematools` v1.1.0.","error":"ModuleNotFoundError: No module named 'bidsschematools.schema.rules'"},{"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.","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.","error":"jsonschema.exceptions.ValidationError: '<value>' is not one of [<expected_values>]"}]}