Skip to content

Release Notes

0.2.1 [2026-01-20]

Enhancements:

  • Added save_pdf_report configuration option to export validation results as a PDF report with clickable links to relevant job, session, and JSON schema used
  • Enhanced error reporting to extract and display field descriptions from JSON schemas by walking up the schema path to find the nearest description
  • Added session path, job URL, session URL, and schema file metadata to validation reports for improved traceability

Maintenance:

  • Updated python from 3.12 to 3.13 in CI configuration
  • Added reportlab>=4.2 dependency for PDF generation

Documentation:

  • Fixed line length in CONTRIBUTING.md pre-commit hook example to meet 88 character limit

0.2.0 [2025-12-11]

Breaking Changes:

  • Redesigned ValidationErrorReport dataclass structure with new fields: error_message, instance_path, label, schema_path, validator_type (dict), validator_value, and schema_definition (optional)
  • Removed old fields: error_type, error_value, error_context, and item
  • Code consuming validation reports must be updated to use new field names

Enhancements:

  • Updated JSON Schema from draft-07 to 2020-12 with Draft202012Validator
  • Changed definitions keyword to $defs with updated $ref paths from #/definitions/ to #/$defs/
  • Added force_rerun configuration option to allow re-validation of sessions that have already passed validation
  • Improved error message handling with new errors.py module and create_simple_error_message() function
  • Error messages now include structured validator details with dynamic constraint extraction
  • Large instance dumps replaced with concise placeholders (e.g., [array of 2 items]) to prevent oversized error messages
  • Human-readable labels derived from schema definitions when using $ref
  • Schema path shows full path to constraint (e.g., properties → acquisitions → allOf → 1 → contains)
  • Hybrid approach combines custom logic for special validators with automatic extraction of constraint keywords
  • Removed message truncation logic in favor of cleaner error messages
  • Both validation_report and validation_report_meta use consistent structure
  • schema_definition field automatically populated when validator references a $ref
  • Validator details automatically include related constraints (e.g., minContains, maxContains for contains validator)

Documentation:

  • Updated README.md schema examples to use 2020-12 syntax
  • Added comprehensive "Interpreting Validation Results" section to README.md
  • Added docs/examples/ directory with JSONSchema examples and validation error examples
  • Added docs/examples/README.md with usage examples and common schema patterns
  • Added example schema files: schema_acquisition_labels.json, schema_with_file_classification.json, and schema_with_session_metadata.json
  • Added example error files: validation_error_missing_required.json, validation_error_type_mismatch.json, validation_error_pattern_mismatch.json, validation_error_const_mismatch.json, validation_error_missing_acquisition.json, and validation_error_number_constraint.json
  • Updated test schema files to 2020-12 format

Maintenance:

  • Migrated from flywheel/python:3.13-main to flywheel.azurecr.io/flywheel/python:3.13-wolfi-build base image
  • Refactored Dockerfile with multi-stage build improvements
  • Updated python from 3.13.7 to 3.13.9

Note: Existing draft-07 schemas remain compatible with the validator, but users are encouraged to update their schemas to 2020-12 format for future compatibility.

0.1.1 [2025-08-18]

Fixes:

  • Fixed session-qc-FAIL tag deletion when re-running validation on previously failed sessions
  • Gear now exits gracefully without error when attempting to run on sessions already tagged with session-qc-PASS
  • Updated README.md for improved clarity and consistency throughout documentation

Maintenance:

  • Refactored ValidationErrorReport dataclass usage to use asdict() conversion for metadata serialization
  • Updated PYTHON_VERSION from 3.13.6 to 3.13.7 in manifest environment variables

0.1.0 [2025-08-18]

Enhancements:

  • Added session validation functionality using JSONSchema to validate Flywheel session containers against user-defined schemas
  • Added support for validating session, acquisition, and file-level metadata including modality, classification, and DICOM header fields
  • Added automatic QC tagging of sessions with session-qc-PASS or session-qc-FAIL based on validation results
  • Added optional validation report output as JSON file for detailed error analysis
  • Added session-level QC metadata object session-validator with validation results and job information
  • Added smart re-validation logic that skips sessions already tagged as passed but re-runs validation for failed sessions
  • Added comprehensive error reporting with Flywheel path context (acquisition label and file name)

Documentation:

  • Added comprehensive README.md with detailed usage examples for five common validation use cases
  • Added CONTRIBUTING.md with development setup instructions, dependency management using poetry, and pre-commit hook configuration
  • Added FAQ.md for frequently asked questions
  • Added release notes documentation in docs/release_notes.md

Maintenance:

  • Added CI/CD pipeline configuration in .gitlab-ci.yml using qa-ci reference with python 3.13
  • Added pre-commit hooks configuration for code quality checks including ruff, pytest, gearcheck, and various linters
  • Added multi-stage Dockerfile using flywheel/python:3.13-main base image with uv for dependency management
  • Added .dockerignore to optimize Docker build context
  • Added comprehensive test suite with unit tests for all modules achieving full code coverage
  • Added MIT license