Validator

Validation tools for HED data structures and annotations.

Core validator classes

HedValidator

class hed.validator.hed_validator.HedValidator(hed_schema, def_dicts=None, definitions_allowed=False)[source]

Bases: object

Top level validation of HED strings.

This module contains the HedValidator class which is used to validate the tags in a HED string or a file. The file types include .tsv, .txt, and .xlsx. To get the validation issues after creating a HedValidator class call the get_validation_issues() function.

__init__(hed_schema, def_dicts=None, definitions_allowed=False)[source]

Constructor for the HedValidator class.

Parameters:
validate(hed_string, allow_placeholders, error_handler=None) → list[dict][source]

Validate the HED string object using the schema.

Parameters:

  • hed_string (HedString) – the string to validate.

  • allow_placeholders (bool) – allow placeholders in the string.

  • error_handler (ErrorHandler or None) – the error handler to use, creates a default one if none passed.

Returns:

A list of issues for HED string.

Return type:

list[dict]

run_basic_checks(hed_string, allow_placeholders) → list[dict][source]

Run basic validation checks on a HED string.

Parameters:

  • hed_string (HedString) – The HED string to validate.

  • allow_placeholders (bool) – Whether placeholders are allowed in the HED string.

Returns:

A list of issues found during validation. Each issue is represented as a dictionary.

Return type:

list[dict]

Notes

  • This method performs initial validation checks on the HED string, including character validation and tag validation.

  • It checks for invalid characters, calculates canonical forms, and validates individual tags.

  • If any issues are found during these checks, the method stops and returns the issues immediately.

  • The method also validates definition tags if applicable.

run_full_string_checks(hed_string, *, required_tags=True, unique_tags=True) → list[dict][source]

Run all full-string validation checks on a HED string.

Parameters:

  • hed_string (HedString) – The HED string to validate.

  • required_tags (bool) – Run the required-tag check. Pass False for a fragment of a row (a HED cell, a sidecar string): the tag it lacks may come from another column, so the check needs the assembled row.

  • unique_tags (bool) – Run the unique-tag check. A unique tag repeated inside a fragment is repeated in the row too, so this check is safe on a fragment; pass False to leave it to assembly.

Returns:

A list of issues found during validation. Each issue is represented as a dictionary.

Return type:

list[dict]

Notes

  • This method iterates through a series of validation checks defined in the checks list.

  • Each check is a callable function that takes hed_string as input and returns a list of issues.

  • If any check returns issues, the method stops and returns those issues immediately.

  • If no issues are found, an empty list is returned.

  • The group-level checks (tag placement, reserved groups, duplicates, Onset and Offset) always run: a group in a fragment is a group of the row.

pattern_doubleslash = re.compile('([ \\t/]{2,}|^/|/$)')
check_tag_formatting(original_tag) → list[dict][source]

Report repeated or erroneous slashes.

Parameters:

original_tag (HedTag) – The original tag that is used to report the error.

Returns:

Validation issues. Each issue is a dictionary.

Return type:

list[dict]

validate_units(original_tag, validate_text=None, report_as=None, error_code=None, index_offset=0, allow_placeholders=True) → list[dict][source]

Validate units and value classes

Parameters:

  • original_tag (HedTag) – The source tag

  • validate_text (str) – the text we want to validate, if not the full extension.

  • report_as (HedTag) – Report the error tag as coming from a different one. Mostly for definitions that expand.

  • error_code (str) – The code to override the error as. Again mostly for def/def-expand tags.

  • index_offset (int) – Offset into the extension validate_text starts at

  • allow_placeholders (bool) – Whether placeholders are allowed (affects value class validation for “#”)

Returns:

Issues found from units

Return type:

list[dict]

Specialized validators

SidecarValidator

class hed.validator.sidecar_validator.SidecarValidator(hed_schema)[source]

Bases: object

Validates HED annotations in a BIDS JSON sidecar against a HED schema.

reserved_column_names = ['HED']
reserved_category_values = ['n/a']
__init__(hed_schema)[source]

Constructor for the SidecarValidator class.

Parameters:

hed_schema (HedSchema) – HED schema object to use for validation.

validate(sidecar, extra_def_dicts=None, name=None, error_handler=None) → list[dict][source]

Validate the input data using the schema

Parameters:

  • sidecar (Sidecar) – Input data to be validated.

  • extra_def_dicts (list or DefinitionDict) – extra def dicts in addition to sidecar

  • name (str) – The name to report this sidecar as. If empty, no FILE_NAME context is added, so a caller that manages its own location context (for example a table inside a larger file) sees only the context it pushed.

  • error_handler (ErrorHandler) – Error context to use. Creates a new one if None.

Returns:

A list of issues associated with each level in the HED string.

Return type:

list[dict]

validate_structure(sidecar, error_handler) → list[dict][source]

Validate the raw structure of this sidecar.

Parameters:

  • sidecar (Sidecar) – the sidecar to validate

  • error_handler (ErrorHandler) – The error handler to use for error context.

Returns:

A list of issues found with the structure.

Return type:

list[dict]

Notes

A top-level key that begins or ends with whitespace is SIDECAR_INVALID, whether or not its entry has a "HED" key, and is reported before the entries’ own structure.

SpreadsheetValidator

class hed.validator.spreadsheet_validator.SpreadsheetValidator(hed_schema, def_dicts=None)[source]

Bases: object

Validates HED annotations in tabular data against a HED schema, in four stages after a header check.

The stages run in order and each stops the run when it finds an error (never on a warning alone):

  1. Column names: a table with a padded, blank or repeated column name gets one TABULAR_INVALID per such name and nothing else: neither the sidecar nor any row is checked or assembled (specification 3.2.10). Names are compared exactly. A BaseInput supplies the names it recorded from its header (padded_columns, blank_columns, duplicate_columns); for any other column source they are found in column_names().

  2. Sidecar: every template and categorical string of the sidecar (SidecarValidator). A sidecar string is a fragment of a row, so the required-tag check waits for assembly.

  3. Column values: the column structure (mapper issues, sidecar references to columns the table lacks), then, for each value and categorical column, its distinct values: one TABULAR_INVALID per value that begins or ends with whitespace (validate_padded_values), then the other values, each value column’s against the units or value class of its # tag and each categorical column’s against its sidecar keys.

  4. HED column: each distinct string of every HED-tags column, the basic (single-string) checks. For a source that offers no assembly, the group-level checks follow on the same strings, since no stage 4 will run them on the whole row. The required-tag check belongs to the assembled row and never runs on a cell; the unique-tag check does, since a repeat inside a cell is a repeat of the row.

  5. Assembly: the rows assembled from all columns, the group-level checks, and the onset and temporal checks of a timeline file.

Stages 2 and 3 work from a ColumnSource, which answers with column names and distinct values and never has to involve pandas; a source that returns None from as_base_input never reaches stage 4. BaseInput is the source for BIDS files. Each stage is also a public method, so a caller can run one column at a time.

Rows are reported as the 0-based row index plus row_offset. For a BaseInput the default offset counts the header line and reports 1-based file lines, as before. An issue found for a value or HED-column string is reported once, at the first row holding the value, with the number of rows holding it in row_count. The categorical check keeps its column-level form: one SIDECAR_KEY_MISSING warning per column naming every unknown value, with no row, as before.

ONSET_TOLERANCE = 1e-07
TIMELINE_TAGS = frozenset({'Delay', 'Inset', 'Offset', 'Onset'})
TEMPORAL_ANCHORS = re.compile('delay|inset|offset|onset')
__init__(hed_schema, def_dicts=None)[source]

Constructor for the SpreadsheetValidator class.

Parameters:

  • hed_schema (HedSchema) – HED schema object to use for validation.

  • def_dicts (DefinitionDict, list, str, or None) – Definitions for the stage methods when they are called on their own. validate replaces them with the sidecar’s definitions plus its extra_def_dicts for the duration of the run.

validate(source, sidecar=None, extra_def_dicts=None, name=None, error_handler=None, row_offset=None, validate_sidecar=True, def_dicts=None) → list[dict][source]

Run the stages on a column source, stopping at the first stage that finds an error.

A table with a padded, blank or repeated column name is reported by stage 0 alone: one TABULAR_INVALID per padded name, then per blank name, then per repeated name, with the FILE_NAME context when name is given (see validate_column_names).

Parameters:

  • source (ColumnSource) – The table to validate. A BaseInput (TabularInput, SpreadsheetInput) or any object with the ColumnSource methods.

  • sidecar (Sidecar or None) – The sidecar describing the columns. For a BaseInput this must be the sidecar it was constructed with (None takes it), since the input’s mapper and assembly come from that sidecar; anything else raises ValueError.

  • extra_def_dicts (list of DefinitionDict or DefinitionDict or None) – Definitions in addition to the sidecar’s.

  • name (str or None) – The name to report errors from this table as. If empty, no FILE_NAME context is added, so a caller that manages its own location context (for example a table inside a larger file) sees only the context it pushed.

  • error_handler (ErrorHandler) – Error context to use. Creates a new one if None.

  • row_offset (int or None) – Added to the 0-based row index in every reported row. None means 1 plus 1 for the header line for a BaseInput (1-based file lines), and 0 otherwise.

  • validate_sidecar (bool) – If False, skip stage 1 because the caller has validated the sidecar already. The sidecar is still used for its definitions and column descriptions. A sidecar error that the caller did not catch is not found by the later stages: a template or categorical string with an invalid tag simply contributes nothing to check.

  • def_dicts – Deprecated name for extra_def_dicts (removed in hedtools 2.0.0). Before the stages, this was the second positional parameter; a positional definition dictionary is now caught and reported as a TypeError rather than validated as a sidecar.

Returns:

The issues found, sorted by location.

Return type:

list[dict]

static validate_column_names(padded, blank, repeated, error_handler) → list[dict][source]

Stage 0: report the column names that break the column-name rules, as TABULAR_INVALID.

The issues are kept in the order given (not sorted): (b) each padded name, then (c) each blank name, then (a) each repeated name. A padded or repeated name carries the COLUMN context; a blank name has no name to give, so its message names its 1-based position instead.

Parameters:
Returns:

The issues found.

Return type:

list[dict]

validate_column_structure(column_names, mapper, sidecar, error_handler) → list[dict][source]

Report the column-level issues that need no data: mapper issues and sidecar references to columns the table does not have.

Parameters:

  • column_names (list) – The table’s column names.

  • mapper (ColumnMapper) – The mapper for these columns.

  • sidecar (Sidecar or None) – The sidecar whose column references are checked.

  • error_handler (ErrorHandler) – Holds context.

Returns:

The issues found.

Return type:

list[dict]

static validate_padded_values(column_name, distinct, error_handler, row_offset=0) → list[dict][source]

Report each distinct value of a value or categorical column that begins or ends with whitespace.

Values are used exactly as written (specification 3.2.9.1), so a padded value would match no annotation key or be substituted with its whitespace; it is TABULAR_INVALID (specification 3.2.10.2). Whitespace is blank, tab, line feed and carriage return; a value made only of whitespace and n/a `` count, while the missing values ``"" and n/a are not in distinct at all.

Parameters:

  • column_name (str or int) – The column, for the error context.

  • distinct (dict[str, list[int]]) – Distinct cell text -> 0-based rows holding it.

  • error_handler (ErrorHandler) – Holds context.

  • row_offset (int) – Added to the first row of each reported value.

Returns:

One issue per distinct padded value, at its first row, each with row_count.

Return type:

list[dict]

validate_value_column(column_name, template, distinct, error_handler, row_offset=0, check_template=False, from_prefix=False) → list[dict][source]

Check each distinct value of a value column as the template’s # tag with the value in place.

Only that one tag is checked, with HedValidator.validate_units: a unit class tag needs valid units and a numeric value, a value class tag needs a value of that class, and any other tag needs an extension made of allowed characters. A value that passes is then spliced into the tag and the result parsed with the basic single-string checks, so a value that would break the HED string it lands in (an unbalanced parenthesis, a tilde, a pound sign) is rejected too. The other tags of the template and its {column} references play no part; they are the sidecar validator’s business. For a Def/Name/# template the placeholder tag inside the definition is the one checked.

Parameters:

  • column_name (str or int) – The column, for the error context.

  • template (str) – The column’s HED string with its #.

  • distinct (dict[str, list[int]]) – Distinct cell text -> 0-based rows holding it.

  • error_handler (ErrorHandler) – Holds context.

  • row_offset (int) – Added to the first row of each reported value.

  • check_template (bool) – If True, run the basic checks on the template itself first (with placeholders allowed) and skip the values if it has an error. For a template that no sidecar validation has covered.

  • from_prefix (bool) – True if the template was built from a column_prefix_dictionary prefix ending in /. Its # was not written by the user but stands for the cell, so under an extension-allowed tag it is the TAG_EXTENDED warning it always was, not the PLACEHOLDER_INVALID that a # written as an extension is (specification 3.2.5 rule 5).

Returns:

The issues found, one per distinct bad value, each with row_count.

Return type:

list[dict]

static validate_categorical_column(column_name, keys, distinct, error_handler) → list[dict][source]

Report the distinct values of a categorical column that its sidecar does not annotate.

Parameters:

  • column_name (str or int) – The column, for the error context.

  • keys (iterable) – The sidecar keys for this column.

  • distinct (dict[str, list[int]]) – Distinct cell text -> 0-based rows holding it.

  • error_handler (ErrorHandler) – Holds context.

Returns:

One SIDECAR_KEY_MISSING issue (a warning) naming every unknown value, or nothing.

Return type:

list[dict]

validate_hed_column(column_name, distinct, error_handler, row_offset=0, full_string=False) → list[dict][source]

Run the single-string checks on each distinct string of a HED-tags column, once per string.

Parameters:

  • column_name (str or int) – The column, for the error context.

  • distinct (dict[str, list[int]]) – Distinct cell text -> 0-based rows holding it.

  • error_handler (ErrorHandler) – Holds context.

  • row_offset (int) – Added to the first row of each reported string.

  • full_string (bool) – If True, also run the group-level checks on each string that passes the basic checks. For a caller that will never assemble rows; otherwise those checks belong to the assembly stage, where the row is whole. The required-tag check needs the assembled row and never runs here; the unique-tag check does, since a repeat inside a cell is a repeat of the row.

Returns:

The issues found, each with row_count.

Return type:

list[dict]

validate_assembled(data, error_handler, row_offset=None) → list[dict][source]

Validate the assembled rows of a BaseInput: the group-level checks on each whole row, and for a timeline file the onset ordering, time conversions, and temporal relations.

The single-string checks are not repeated here; stages 2 and 3 have covered every column’s values.

Parameters:

  • data (BaseInput) – The table, with its sidecar attached.

  • error_handler (ErrorHandler) – Holds context.

  • row_offset (int or None) – Added to the 0-based row index. None means 1 plus 1 for the header.

Returns:

The issues found.

Return type:

list[dict]

DefValidator

class hed.validator.def_validator.DefValidator(def_dicts=None, hed_schema=None)[source]

Bases: DefinitionDict

Validates Def/ and Def-expand/, as well as Temporal groups: Onset, Inset, and Offset

__init__(def_dicts=None, hed_schema=None)[source]

Initialize for definitions in HED strings.

Parameters:

  • def_dicts (list or DefinitionDict or str) – DefinitionDicts containing the definitions to pass to baseclass

  • hed_schema (HedSchema or None) – Required if passing strings or lists of strings, unused otherwise.

validate_def_tags(hed_string_obj) → list[dict][source]

Validate Def/Def-Expand tags.

Parameters:

  • hed_string_obj (HedString) – The HED string to process.

  • hed_validator (HedValidator) – Used to validate the placeholder replacement.

Returns:

Issues found related to validating defs. Each issue is a dictionary.

Return type:

list[dict]

validate_def_value_units(def_tag, hed_validator, allow_placeholders=False) → list[dict][source]

Equivalent to HedValidator.validate_units for the special case of a Def or Def-expand tag

validate_onset_offset(hed_string_obj) → list[dict][source]

Validate onset/offset

Parameters:

hed_string_obj (HedString) – The HED string to check.

Returns:

A list of issues found in validating onsets (i.e., out of order onsets, unknown def names).

Return type:

list[dict]

OnsetValidator

class hed.validator.onset_validator.OnsetValidator[source]

Bases: object

Validates onset/offset pairs.

__init__()[source]
validate_temporal_relations(hed_string_obj) → list[dict][source]

Validate onset/offset/inset tag relations

Parameters:

hed_string_obj (HedString) – The HED string to check.

Returns:

A list of issues found in validating onsets (i.e., out of order onsets, repeated def names).

Return type:

list[dict]

static check_for_banned_tags(hed_string) → list[dict][source]

Returns an issue for every tag found from the banned list (for files without onset column).

Parameters:

hed_string (HedString) – The string to check.

Returns:

The validation issues associated with the characters. Each issue is dictionary.

Return type:

list[dict]

Notes

  • The banned tags are the rows of reserved_tags.json with requiresTimeline (specification 3.2.8 rule 4).

ReservedChecker

class hed.validator.reserved_checker.ReservedChecker[source]

Bases: object

Thread-safe singleton that loads reserved tag rules and checks groups for compliance.

reserved_reqs_path = '/home/runner/work/hed-python/hed-python/hed/validator/data/reserved_tags.json'
ORGANIZATIONAL_TAGS = frozenset({'Collection', 'Condition-variable', 'Control-variable', 'Event-stream', 'Experimental-intertrial', 'Experimental-trial', 'Indicator-variable', 'Recording', 'Task', 'Time-block'})
static get_instance()[source]

Return the singleton ReservedChecker instance, creating it on first call.

Returns:

The shared singleton instance.

Return type:

ReservedChecker

get_error_code(tag_name) → str | None[source]

Return the ERROR_CODE of the row for a tag name, or None if the name is not a row.

Parameters:

tag_name (str) – The short base tag name.

Returns:

The row’s error code (specification 3.2.8 rule 6).

Return type:

str or None

get_reserved(group)[source]

Return the list of reserved tags found directly within the given HED group.

Parameters:

group (HedGroup) – The group to inspect.

Returns:

Tags in the group whose short base tag is a reserved name.

Return type:

list[HedTag]

get_governing_tag(reserved_tags)[source]

Return the tag whose row gives the group rules, or None if the reserved tags cannot share a group.

Parameters:

reserved_tags (list of HedTag) – The reserved tags of one group, without duplicates.

Returns:

The only tag, or, for two tags of which one lists the other in its secondaryWith,

that other tag (specification 3.2.8 rule 3). None for any other combination.

Return type:

HedTag or None

check_reserved_compatibility(group, reserved_tags)[source]

Check to make sure that the reserved tags can be used together and no duplicates.

Parameters:

  • group (HedTagGroup) – A group to be checked.

  • reserved_tags (list of HedTag) – A list of reserved tags in this group.

Returns:

Validation issues. Each issue is a dictionary.

Return type:

list

Notes

  • These are placement errors, reported as TAG_GROUP_ERROR (specification 3.2.8 rule 6).

check_tag_requirements(group, reserved_tags)[source]

Check the group against the row of its governing tag.

Parameters:

  • group (HedTagGroup) – A group to be checked.

  • reserved_tags (list of HedTag) – A list of reserved tags in this group.

Returns:

Validation issues. Each issue is a dictionary.

Return type:

list

Notes

  • Call this only after check_reserved_compatibility found no issue, so a governing tag exists.

  • A missing or extra anchor and a wrong number of inner groups are content errors, reported with the row’s ERROR_CODE; a top-level tag the row does not allow is a placement error, reported as TAG_GROUP_ERROR (specification 3.2.8 rule 6).

  • An anchor is a Def tag or a Def-expand group; neither counts as an other tag or an inner group.

Validator utilities

CharValidator

class hed.validator.util.char_util.CharValidator(modern_allowed_char_rules=False)[source]

Bases: object

Class responsible for basic character level validation of a string or tag.

__init__(modern_allowed_char_rules=False)[source]

Does basic character validation for HED strings/tags

Parameters:

modern_allowed_char_rules (bool) – If True, use 8.3 style rules for unicode characters.

check_invalid_character_issues(hed_string, allow_placeholders) → list[dict][source]

Report characters no HED string may contain.

Parameters:

  • hed_string (str) – A HED string.

  • allow_placeholders (bool) – Allow placeholder and curly brace characters.

Returns:

Validation issues. Each issue is a dictionary.

Return type:

list

Notes

  • The forbidden characters come from character_sets.json hed_string.forbidden (specification Appendix B CHARACTER_INVALID a): [ ] ~ " and the control code ranges (0-31 and 127-159), whatever the schema version. Curly braces are forbidden where placeholders are not allowed (CHARACTER_INVALID b). Schemas before 8.3.0 also reject every non-ASCII character.

check_tag_invalid_chars(original_tag, allow_placeholders) → list[dict][source]

Report invalid characters in the given tag.

Parameters:

  • original_tag (HedTag) – The original tag that is used to report the error.

  • allow_placeholders (bool) – Allow placeholder characters(#) if True.

Returns:

Validation issues. Each issue is a dictionary.

Return type:

list

check_for_invalid_extension_chars(original_tag, validate_text, error_code=None, index_offset=0) → list[dict][source]

Report invalid characters in a tag extension.

Parameters:

  • original_tag (HedTag) – The original tag that is used to report the error.

  • validate_text (str) – the text we want to validate, if not the full extension.

  • error_code (str) – The code to override the error as. Again mostly for def/def-expand tags.

  • index_offset (int) – Offset into the extension validate_text starts at.

Returns:

Validation issues. Each issue is a dictionary.

Return type:

list

CharRexValidator

class hed.validator.util.char_util.CharRexValidator(modern_allowed_char_rules=False, hed_schema=None)[source]

Bases: CharValidator

Character validation of values against the value classes of the loaded schema.

__init__(modern_allowed_char_rules=False, hed_schema=None)[source]

Does basic character validation for HED strings/tags

Parameters:

  • modern_allowed_char_rules (bool) – If True, use 8.3 style rules for Unicode characters.

  • hed_schema (HedSchema, HedSchemaGroup or None) – The schema being validated against. It decides whether a value class’s own allowedCharacter declaration or the specification’s per-class defaults define its characters (see allowed_names). None trusts the declaration.

schema_for_tag(tag)[source]

Return the schema of the group that owns tag, or None when it is unknown.

Parameters:

tag (HedTag) – A tag whose schema_namespace names one schema of the group.

Returns:

The owning schema; None without a schema or for a namespace the group lacks.

Return type:

HedSchema or None

property character_sets: CharacterSets

The shared character-set table.

allowed_names(cname, declared_names=None, hed_schema=None) → list[str][source]

Return the character-set names that define the characters of value class cname.

From standard schema 8.5.0, and in libraries partnered with 8.5.0 or later, the schema’s own allowedCharacter declaration defines the class (decision D2, 2026-09-30), provided every name is a known set, an alias, or a single literal character; an unknown name is a schema compliance error and the defaults apply instead. On earlier standard versions the specification’s value_class_defaults define the five standard classes (D5), because their released declarations are incomplete (nameClass omits nonascii; the 8.0.0 to 8.2.0 textClass enumerates characters without the underscore, and the file records text there, as validators have always applied). A class the file has no defaults for (a library’s own value class) always follows its declaration.

Parameters:

  • cname (str) – The value class name.

  • declared_names (list of str or None) – The allowedCharacter names the schema declares for it.

  • hed_schema (HedSchema or None) – The schema that owns the tag being checked. Its standard version decides the policy; None uses the schema or group this validator was built with.

Returns:

The names; empty when nothing constrains the characters.

Return type:

list[str]

get_problem_chars(in_str, cname, declared_names=None, hed_schema=None)[source]

Return a list of (index, char) pairs for characters in in_str not allowed by the value class cname.

Parameters:

  • in_str (str) – The string to check.

  • cname (str) – The value class name used to look up allowed character classes.

  • declared_names (list of str or None) – The allowedCharacter names the schema declares for the class, if any. See allowed_names for when they are used.

  • hed_schema (HedSchema or None) – The schema that owns the value’s tag; see allowed_names.

Returns:

Each tuple contains the character index and the offending character.

Return type:

list[tuple[int, str]]

is_valid_value(in_string, cname)[source]

Check whether in_string is a valid whole-word value for class cname.

Parameters:

  • in_string (str) – The string to validate.

  • cname (str) – The value class name to look up the word-level regex for.

Returns:

  • True if no word-level regex is defined for cname (class imposes no constraint).

  • A re.Match object if in_string matches the word-level regex (valid value).

  • False if in_string does not match the word-level regex, or is a dateTimeClass value whose date does not exist (invalid value).

Return type:

True | re.Match | False

value_failure(in_string, cname) → str[source]

Say why in_string fails the whole-value rule of class cname, for the VALUE_INVALID message.

Parameters:

  • in_string (str) – The value.

  • cname (str) – The value class name.

Returns:

The rule the value breaks (the class description, or “an existing Gregorian calendar date; 2026-02-31 does not exist”); empty when the value passes or the class has no whole-value rule.

Return type:

str

UnitValueValidator

class hed.validator.util.class_util.UnitValueValidator(modern_allowed_char_rules=False, value_validators=None, hed_schema=None)[source]

Bases: object

Validates units.

__init__(modern_allowed_char_rules=False, value_validators=None, hed_schema=None)[source]

Validates the unit and value classes on a given tag.

Parameters:

  • modern_allowed_char_rules (bool) – If True, use the 8.3.0 and later character rules.

  • value_validators (dict or None) – Deprecated, removed in hedtools 2.0.0. Accepted so that existing callers keep working; it has no effect. The per-class validator functions it used to override were never reached by validation.

  • hed_schema (HedSchema, HedSchemaGroup or None) – The schema being validated against; it decides whether a value class’s own declaration or the specification’s defaults define its characters (CharRexValidator.allowed_names).

Notes

The per-character sets and the whole-value rules of each value class come from the specification’s character_sets.json (hed/validator/data/) through CharRexValidator; there is no per-class validator function.

check_tag_unit_class_units_are_valid(original_tag, validate_text, report_as=None, error_code=None, allow_placeholders=True, index_offset=0) → list[dict][source]

Report incorrect unit class or units.

Parameters:

  • original_tag (HedTag) – The original tag that is used to report the error.

  • validate_text (str) – The text to validate.

  • report_as (HedTag) – Report errors as coming from this tag, rather than original_tag.

  • error_code (str) – Override error codes.

  • allow_placeholders (bool) – Whether placeholders are allowed (affects value class validation for “#”)

  • index_offset (int) – Where validate_text starts within the extension of report_as, for the character index of an issue (a Def tag’s placeholder value follows its label).

Returns:

Validation issues. Each issue is a dictionary.

Return type:

list

check_tag_value_class_valid(original_tag, validate_text, report_as=None, index_offset=0) → list[dict][source]

Report an invalid value portion.

Parameters:

  • original_tag (HedTag) – The original tag that is used to report the error.

  • validate_text (str) – The text to validate.

  • report_as (HedTag) – Report errors as coming from this tag, rather than original_tag.

  • index_offset (int) – Where validate_text starts within the extension of report_as, for the character index of an issue.

Returns:

Validation issues.

Return type:

list

report_value_errors(error_dict, class_valid, report_as, allowed_names=None, rule_failures=None)[source]

Build validation issues from per-class character error and validity dicts.

Parameters:

  • error_dict (dict) – Mapping of class name to list of (char, index) problem tuples.

  • class_valid (dict) – Mapping of class name to a validity result (True, re.Match, or False) indicating whether the full value passed word-level format validation for that class.

  • report_as (HedTag) – The tag object used as context in error reporting.

  • allowed_names (dict or None) – Mapping of class name to the character-set names in force for it, for the messages and the char_set issue key.

  • rule_failures (dict or None) – Mapping of class name to the whole-value rule the value broke (CharRexValidator.value_failure); the class’s rule description when absent.

Returns:

Validation issue dictionaries.

Return type:

list[dict]

static report_value_char_errors(class_name, errors, report_as, char_set=None, allows=None)[source]

Build validation issues for specific invalid characters within a value class string.

Parameters:

  • class_name (str) – The value class name that detected the errors (”” for a value with no class).

  • errors (list[tuple[str, int]]) – Character/index pairs of invalid characters.

  • report_as (HedTag) – The tag object used as context in error reporting.

  • char_set (str or None) – The char_set issue key: the character-set names the value failed.

  • allows (str or None) – What the class allows, for the message.

Returns:

Validation issue dictionaries.

Return type:

list[dict]

DuplicateChecker

class hed.validator.util.dup_util.DuplicateChecker[source]

Bases: object

Detects duplicate tags and groups within a HED annotation.

__init__()[source]

Checker for duplications in HED groups.

Notes

This checker has an early out strategy – it returns when it finds an error.

check_for_duplicates(group) → list[dict][source]

Find duplicates in a HED group and return the errors found.

Parameters:

group (HedGroup) – The HED group to be checked.

Returns:

List of validation issues – which might be empty if no duplicates detected.

Return type:

list

get_hash(group) → int | None[source]

Return the unique hash for the group as long as no duplicates.

Parameters:

group (HedGroup) – The HED group to be checked.

Returns:

Unique hash or None if duplicates were detected within the group.

Return type:

Union[int, None]

Note: As a side effect, this method will clear the issues list if no duplicates are found.

GroupValidator

class hed.validator.util.group_util.GroupValidator(hed_schema)[source]

Bases: object

Validation for attributes across groups HED tags.

This is things like Required, Unique, top level tags, etc.

__init__(hed_schema)[source]

Constructor for GroupValidator

Parameters:

hed_schema (HedSchema) – A HedSchema object.

run_tag_level_validators(hed_string_obj) → list[dict][source]

Report invalid groups at each level.

Parameters:

hed_string_obj (HedString) – A HedString object.

Returns:

Issues associated with each level in the HED string. Each issue is a dictionary.

Return type:

list

Notes

  • This pertains to the top-level, all groups, and nested groups.

run_all_tags_validators(hed_string_obj) → list[dict][source]

Report invalid the multi-tag properties in a HED string, e.g. required tags.

Parameters:

hed_string_obj (HedString) – A HedString object.

Returns:

The issues associated with the tags in the HED string. Each issue is a dictionary.

Return type:

list

static check_tag_level_issue(original_tag_list, is_top_level, is_group) → list[source]

Report tags incorrectly positioned in hierarchy.

Parameters:

  • original_tag_list (list of HedTag) – HedTags containing the original tags.

  • is_top_level (bool) – If True, this group is a “top level tag group”.

  • is_group (bool) – If True group should be contained by parenthesis.

Returns:

Validation issues. Each issue is a dictionary.

Return type:

list

Notes

  • A tag is a tagGroup or topLevelTagGroup tag when its schema says so or its row in reserved_tags.json does: schemas 8.0.0 and 8.1.0 carry neither attribute on Delay and Duration, and the file supplies them (specification 3.2.8 rule 1).

check_for_required_tags(tags) → list[source]

Report missing required tags.

Parameters:

tags (list) – HedTags containing the tags.

Returns:

Validation issues. Each issue is a dictionary.

Return type:

list

check_multiple_unique_tags_exist(tags) → list[source]

Report if multiple identical unique tags exist

A unique Term can only appear once in a given HedString. Unique terms are terms with the ‘unique’ property in the schema.

Parameters:

tags (list) – HedTags containing the tags.

Returns:

Validation issues. Each issue is a dictionary.

Return type:

list

StringValidator

class hed.validator.util.string_util.StringValidator[source]

Bases: object

Runs checks on the raw string that depend on multiple characters, e.g. mismatched parentheses

OPENING_GROUP_CHARACTER = '('
CLOSING_GROUP_CHARACTER = ')'
COMMA = ','
run_string_validator(hed_string_obj)[source]

Run all string-level structural checks on a HED string object.

Parameters:

hed_string_obj (HedString) – The parsed HED string to validate.

Returns:

Validation issue dictionaries.

Return type:

list[dict]

static check_count_tag_group_parentheses(hed_string) → list[dict][source]

Report unmatched parentheses.

Parameters:

hed_string (str) – A HED string.

Returns:

A list of validation list. Each issue is a dictionary.

Return type:

list

check_delimiter_issues_in_hed_string(hed_string) → list[dict][source]

Report missing commas or commas in value tags.

Parameters:

hed_string (str) – A HED string.

Returns:

A validation issues list. Each issue is a dictionary.

Return type:

list

TagValidator

class hed.validator.util.tag_util.TagValidator[source]

Bases: object

Validation for individual HED tags.

CAMEL_CASE_EXPRESSION = '([A-Z]+\\s*[a-z-]*)+'
run_individual_tag_validators(original_tag, allow_placeholders=False, is_definition=False) → list[dict][source]

Runs the validators on the individual tags.

This ignores most illegal characters except in extensions.

Parameters:

  • original_tag (HedTag) – A original tag.

  • allow_placeholders (bool) – Allow value class or extensions to be placeholders rather than a specific value.

  • is_definition (bool) – This tag is part of a Definition, not a normal line.

Returns:

The validation issues associated with the tags. Each issue is dictionary.

Return type:

list

static check_tag_exists_in_schema(original_tag, allow_placeholders=True) → list[dict][source]

Report invalid tag or doesn’t take a value.

Parameters:

  • original_tag (HedTag) – The original tag that is used to report the error.

  • allow_placeholders (bool) – False if check_for_placeholder already reports every ‘#’ of the tag.

Returns:

Validation issues. Each issue is a dictionary.

Return type:

list

Notes

  • A reserved tag whose row in reserved_tags.json has noExtension may not be extended, although it inherits extensionAllowed (specification 3.2.5): TAG_EXTENSION_INVALID, also for Onset/#.

  • # used as an extension of any other tag is PLACEHOLDER_INVALID, whether or not the parent allows extension (specification 3.2.5 rule 5).

  • An extension term must contain at least one letter (specification 3.2.5 rule 6), for every schema version: Item/Blech/3 and Item/1-2 are TAG_EXTENSION_INVALID. A letter is any character for which str.isalpha is true. The specification limits letters to A-Z and a-z before 8.3.0, and that needs no separate test: before 8.3.0 every non-ASCII character is already CHARACTER_INVALID.

static check_tag_requires_child(original_tag) → list[dict][source]

Report if tag is a leaf with ‘requiredTag’ attribute.

Parameters:

original_tag (HedTag) – The original tag that is used to report the error.

Returns:

Validation issues. Each issue is a dictionary.

Return type:

list

Notes

  • A reserved tag whose row in reserved_tags.json has requireValue also needs a value: Delay and Duration carry requireChild only from schema 8.3.0 (TAG_REQUIRES_CHILD b).

check_capitalization(original_tag) → list[dict][source]

Report warning if incorrect tag capitalization.

Parameters:

original_tag (HedTag) – The original tag used to report the warning.

Returns:

Validation issues. Each issue is a dictionary.

Return type:

list

check_tag_is_deprecated(original_tag) → list[dict][source]

Return a validation issue if the tag carries the DeprecatedFrom attribute.

Parameters:

original_tag (HedTag) – The tag to check.

Returns:

A singleton list with a deprecation issue, or an empty list.

Return type:

list[dict]

static check_for_placeholder(original_tag, is_definition=False) → list[dict][source]

Report invalid placeholder characters.

Parameters:

  • original_tag (HedTag) – The HedTag to be checked

  • is_definition (bool) – If True, placeholders are allowed.

Returns:

Validation issues. Each issue is a dictionary.

Return type:

list

Notes

  • Invalid placeholder may appear in the extension/value portion of a tag.