Specifications and Schemas (PRISM vs BIDS)

This page explains PRISM’s specification layer: how schemas work, where they live, and how they relate to standard BIDS.

PRISM is an add-on to BIDS:

  • PRISM does not replace BIDS.

  • BIDS standards should not be changed in PRISM.

  • PRISM adds additional schemas (e.g., Survey, Biometrics, Environment) that are not fully standardized in BIDS yet.

  • A key design goal is that standard BIDS tools/apps still work on PRISM datasets.

1) Conceptual model

BIDS (core)

BIDS defines:

  • dataset structure conventions

  • filename conventions and entities (sub-, ses-, task-, etc.)

  • standard metadata files (e.g., dataset_description.json, participants.tsv)

PRISM (extensions)

PRISM adds:

  • additional modality-specific schemas (e.g., survey, biometrics, environment)

  • Mandatory Extensions to BIDS Core: For certain standard BIDS modalities (like events), PRISM mandates additional metadata blocks (e.g., StimulusPresentation) that are optional or unspecified in standard BIDS.

  • stricter sidecar requirements for certain data types

  • optional internationalization (i18n) support for variable-level descriptions

PRISM Studio (software)

PRISM Studio provides operational tooling on top of PRISM, including:

  • conversion/import workflows

  • validation execution (web and CLI)

  • scoring/derivatives execution

  • export workflows (e.g., SPSS or integration-specific exports)

2) Schema versions

PRISM schemas are versioned under the repository folder:

  • schemas/stable/ (default)

  • schemas/vX.Y/ (historical / pinned versions)

You can:

python prism-validator --list-versions
python prism-validator /path/to/dataset --schema-version stable

For details, see:

3) Files PRISM expects in a dataset

At minimum (BIDS core):

  • dataset_description.json (required)

  • participants.tsv (commonly required in practice)

For PRISM extensions, typical additions are:

  • per-subject survey TSVs under sub-*/ses-*/survey/

  • per-subject biometrics TSVs under sub-*/ses-*/biometrics/ for sports/performance tests (e.g., VO2max, Y-Balance, CMJ)

  • per-subject physiological signal files under sub-*/ses-*/physio/ (primarily EDF+/EDF, with TSV/TSV.GZ where applicable)

  • environment TSV/JSON files in environment-specific paths used by your workflow

  • JSON sidecars for each data file (PRISM requires sidecars for non-JSON data files it validates)

4) Filename conventions (high-level)

PRISM follows BIDS-like entity conventions. Examples:

Survey TSV:

  • sub-001_ses-1_task-ads_beh.tsv

Biometrics TSV:

  • sub-001_ses-1_biometrics-cmj_biometrics.tsv

Physio EDF+:

  • sub-001_ses-1_task-rest_physio.edf

Each data file should have a corresponding JSON sidecar with the same stem.

5) Derivatives

PRISM Studio supports generating derived variables (scores, subscales) from raw data using PRISM-compatible recipes. These are stored in a BIDS-compliant derivatives/ folder.

  • Location: derivatives/surveys/ or derivatives/biometrics/

  • Metadata: Each derivative dataset must contain its own dataset_description.json (BIDS-derivatives requirement). PRISM automatically generates this file, inheriting relevant metadata from the root dataset.

  • Recipes: Transformations are defined in JSON recipe files. See RECIPES.md for the full specification.

6) What is inside a PRISM schema?

PRISM uses JSON Schema documents to define:

  • required top-level blocks (commonly Technical, Study, Metadata)

  • required fields and allowed types

  • optional blocks like I18n and Scoring

The Study block now supports comprehensive metadata including:

  • Authors, DOI, Citation

  • Construct, Keywords

  • Reliability, Validity

  • Instructions

Many of these fields support i18n objects (e.g., {"de": "...", "en": "..."}) to allow for multi-language documentation.

Schemas live in schemas/<version>/.

7) Detailed Schema Keys

PRISM schemas are organized into logical blocks. Below are the most important keys for survey and biometrics modalities.

Technical Block

Contains technical metadata about the data collection.

For survey templates, treat these as project-local administration fields. The official library stores the canonical instrument, while the copied template in code/library/survey/ stores how that instrument was actually administered in the project.

  • SoftwarePlatform: Software used (e.g., LimeSurvey, REDCap, My Jump Lab).

  • SoftwareVersion: Version of the collection software.

  • Language: Primary language of the assessment (e.g., en, de-AT).

  • Respondent: Who provided the data (self, clinician, parent, etc.).

  • AdministrationMethod: How it was administered (online, paper, interview).

  • Equipment: Name of the hardware used (e.g., Stopwatch, Dynamometer).

  • Supervisor: Who supervised the test (investigator, physician, self).

  • Location: Where it took place (laboratory, clinic, home).

Study Block

Contains scientific and bibliographic metadata.

For surveys, this block is mostly instrument-level metadata. The main project-local exception is TaskName, which identifies how the instrument is referenced in the dataset.

  • OriginalName: Full canonical name of the instrument.

  • ShortName: Common abbreviation (e.g., DEMO-II).

  • Authors: List of authors.

  • DOI / Citation: Bibliographic references.

  • License / LicenseID / CopyrightHolder: Legal and usage information.

  • Construct: Psychological construct measured (e.g., depression).

  • Reliability / Validity: Psychometric properties.

  • AdministrationTime: Estimated time to complete.

  • References: Structured list of related papers (manuals, validations); each entry includes Type, Citation, canonical DOI (10.x/...), optional URL, Year, and Notes.

Scoring Block

Defines how the data should be interpreted or scored.

  • ScoringMethod: General method (e.g., sum, mean).

  • ScoreRange: Possible min/max scores.

  • Cutoffs: Clinical thresholds and their interpretations.

  • ReverseCodedItems: List of items that need inversion.

  • Subscales: Structured definitions of sub-scores (Name, Items, Method).

Item-Level Properties (Columns)

Each column in the TSV can have detailed metadata in the JSON sidecar.

  • Description: The exact question text or metric description.

  • Levels: Mapping of numeric values to labels (e.g., {"0": "Never", "1": "Always"}).

  • Unit: Unit of measurement (e.g., ms, cm, score).

  • MinValue / MaxValue: Hard bounds for validation.

  • WarnMinValue / WarnMaxValue: Soft bounds (triggers warnings).

  • Relevance: Logic for when this item is applicable (e.g., Q01 == 1).

  • DataType: Expected type (string, integer, float).

  • SessionHint / RunHint: Used for longitudinal/repeated data mapping.

Example (Biometrics schema path):

  • schemas/stable/biometrics.schema.json

6) Internationalization (i18n)

Some PRISM templates support bilingual/multilingual text fields (e.g., English + German). Depending on the schema, a descriptive field may be either:

  • a plain string, or

  • a language map like:

{
  "en": "Measures explosive leg power.",
  "de": "Misst die explosive Beinkraft."
}

This is especially useful for:

  • Study.Description

  • variable-level Description

7) Detailed modality specifications

PRISM’s modality-specific specifications are documented under docs/specs/.

Start here:

(These pages are intended to play the same role as BIDS specification pages: they describe the expected files, naming, and metadata semantics.)