Skip to content

hed-validator v4.0.0
Compare
Choose a tag to compare
@happy5214 happy5214 released this 08 Mar 20:51
v4.0.0
This tag was signed with the committer’s verified signature.
happy5214 Alexander Jones
GPG key ID: B36A288B9D4005D3
Verified
Learn about vigilant mode.
d698bee
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

NOTE: This was inadvertently released to NPM as version 5.0.0 due to a typo in the package.json. That release has been pulled. Please use this release instead.

This fourth major version of hed-validator is a substantial rewrite of the code and interface. It provides feature-completeness, including full compliance with the current version of the HED-3G specification. Support for earlier generations of HED and syntax-only validation has been removed.

Previous versions did not properly implement definition or temporal tag validation. This version completely reimplements the validation code, fixing these and other bugs. The validator now fails as soon as it finds an error, rather than trying to return all errors. This reduces spurious errors that make no sense.

Reliability is now assured by overlapping sets of testcases. The original JavaScript-based tests were completely rewritten to use JSON-based datasets and templated scripts, while the specification itself also provides a rich set of JSON-based tests, shared with the Python-based HED validator, that ensures conformance with the HED-3G standard.

API

The API has been completely remodeled and greatly reduced compared to version 3 of this validator. The original APIs, which allowed direct access to the validator's parsing, schema-loading, and validation code, have been removed entirely. The API to validate entire BIDS datasets at once has also been removed, due to issues that arose when validating large BIDS datasets using that model.

The version 4.0.0 API only supports validating BIDS-format files, specifically JSON and TSV files. The API is as follows:

  • BidsSidecar - JSON sidecars
  • BidsJsonFile - Non-sidecar JSON files
  • BidsTsvFile - TSV files
  • BidsHedIssue - The generated issues returned from the validator, type-compatible with the BIDS Issue type.
  • buildBidsSchemas(datasetDescription) - An async function which returns a Schemas object (this type is not part of the public API and should be treated as opaque). datasetDescription is a BidsJsonFile object representing dataset_description.json.

The constructors of BidsSidecar and BidsJsonFile take three arguments as part of the public API:

  1. The name of the file.
  2. An object representing the file itself.
  3. The parsed contents of the JSON file in object form.

The constructor of BidsTsvFile takes four arguments as part of the public API:

  1. The name of the file.
  2. An object representing the file itself.
  3. The parsed contents of the TSV file (preferably as either a string of the entire file contents, or as a Map, with the column names as keys and the column values in an array as values).
  4. (Optional) The merged sidecar contents in object form.

The constructor of BidsHedIssue should not be called from external code. buildBidsSchemas() may throw IssueError objects (another opaque internal type), which should be passed, along with the file object of the dataset_description.json BidsJsonFile, to the static method BidsHedIssue.fromHedIssues(), which will return an array of BidsHedIssue objects. This is a bug in the interface that will be fixed in a future release.

Validation is performed by calling the BidsFile.validate(schemas) method on any file object (BidsSidecar, BidsJsonFile, and BidsTsvFile are all subclasses of BidsFile), passing the Schemas object returned by buildBidsSchemas(). This method returns an array of BidsHedIssue objects corresponding to the validation issues found.

Further changes to the API may be considered in a future release.

What's Changed

Full Changelog: v3.15.5...v4.0.0

Contributors

VisLab, happy5214, and dependabot
Assets 2
Loading