B. HED errors

B. HED errors#

This appendix summarizes the error codes used by HED validators and other tools.

HED-compliant tools may assume that it if a HED annotation has been properly validated, it will comply with the rules of the HED specification. Annotators and analysts are mainly concerned with HED validation errors relating to incorrectly annotated events. See B.1: HED validation errors for a listing of errors keyed to the HED specification.

HED-compliant tools assume that the HED schemas available on the hed-standard/hed-schemas GitHub repository are error-free, and that schema errors can only occur due to failure to locate or read a HED schema.

HED schema developers are mainly concerned with errors and inconsistencies in the schema itself. Schemas under development should be validated at all stages of development. See B.2: Schema validation errors for a listing of errors keyed to the HED specification.

B.1. HED validation errors#

CHARACTER_INVALID#

a. A HED string cannot contain the following characters:

  • Character code <= 31 (hex 0x1f).

  • 127 (hex 0x7f) <= character code <= 159 (hex 0x9f).

  • Left or right square brackets ([, ]).

  • Tilde (~) character. Replace: the syntax (A ~ B ~ C) with (A, (B, C)).

  • Double quotes (").

b. Curly braces ({, }) can only appear in a sidecar and indicate a column template, not HED.

Notes:

  1. Starting with HED 8.3.0, HED supports UTF-8 encoding.

  2. Different parts of a HED string have different rules for acceptable characters. For example tag names must satisfy the rules for the HED name class. The values used after tag names depend on the value classes of the tag and the unit classes of the tag.

See also:

COMMA_MISSING#

HED tag groups and tags must be separated with commas. In the following A, B, C, and D represent HED expressions.

a. Two tag groups are not separated by commas: (A, B)(C, D).
b. A tag and a tag group are not separated by commas: A(B,D).

Note: Commas missing between two HED tags are generally detected as invalid HED tags, rather than as missing commas.

See 3.2.7.3. Empty tags and groups for an explanation of the rules for empty tags.

See also TAG_EMPTY.

DEF_EXPAND_INVALID#

a. A Def-expand tag’s name does not correspond to a definition.
b. A Def-expand is missing an expected placeholder value or has an unexpected placeholder value.
c. A Def-expand has a placeholder value of incorrect format or units for definition.
d. The tags within a Def-expand do not match the corresponding definition.
e. A Def-expand tag group is missing its inner tag group.
f. A Def-expand tag group has extra tags or groups.

See 3.2.8.2. The Def and Def-expand tags for an explanation of the rules for Def-expand and 5.2. Using definition for more details and examples.

DEF_INVALID#

a. A Def tag’s name does not correspond to a definition.
b. A Def tag is missing an expected placeholder value or has an unexpected placeholder value.
c. A Def has a placeholder value of incorrect format or units for definition.

See 3.2.8.2. The Def and Def-expand tags for an explanation of the rules for Def and 5.2. Using definition for more details and examples.

DEFINITION_INVALID#

A definition is a tag group containing a Definition tag and a single tag group with the definition’s contents.

a. A Definition tag does not appear in a tag group at the top level in an annotation.
b. A definition’s enclosing tag group contains an empty group (i.e., an actual inner ()).
c. A definition’s enclosing tag group contains more than a Definition tag and an inner group.
d. A definition’s inner tag group contains Definition, Def or Def-expand tags.
e. A definition uses curly braces.
f. A definition that includes a placeholder (#) does not have exactly two # characters.
g. A definition has placeholders (#) in incorrect positions.
h. Definitions of the same name appear with and without a #.
i. Multiple Definition tags with same name are encountered.
j. A tag with a required or unique attribute appears in a definition.
k. A definition appears in an unexpected place such as an events file or in a sidecar dictionary that contains non-definition entries.

See 3.2.8.1. The Definition tag for an explanation of the rules for definitions. See also 5.1. Creating definitions and 5.2. Using definitions for more details and examples of definition syntax.

ELEMENT_DEPRECATED*#

A schema element has been deprecated and should not be used. When an element is updated, its description is updated to include the reason for deprecation and a suggested path for updating usage.

a. A tag has been deprecated and an alternative method of tagging should be used. See tag description for how to replace.
b. A unit, unit class, value class has been deprecated and an alternative should be used.

See A.1.4. Schema attributes for additional information about the deprecatedFrom schema attribute.

PARENTHESES_MISMATCH#

a. A HED string does not have the same number of open and closed parentheses.
b. The open and closed parentheses are not correctly nested in the HED string.

See 3.2.7.1. Parentheses and order for the rules for parentheses in HED.

PLACEHOLDER_INVALID#

a. A # appears in a place that it should not (such as in the HED column of an events file).
b. A JSON sidecar has a placeholder (#) in the HED dictionary for a categorical column.
c. A JSON sidecar does not have exactly one placeholder (#) in each HED string representing a value column.
d. A placeholder (#) is used in JSON sidecar or definition, but its parent in the schema does not have a placeholder child. e. Multiple placeholders (#) appear in a HED string (e.g., "Label/#, Parameter-value/#").
f. A placeholder (#) does not appear directly after a slash (e.g., "Label/ #").

See 3.2.4. Tags that take values and 3.2.9.1. Sidecar entries for information on the use of placeholders in HED.

REQUIRED_TAG_MISSING#

a. An event-level annotation does not have a tag corresponding to a node with the required schema attribute.

Note: An assembled event string must include all tags having the required schema attribute.

See 3.2.10.2. Event-level processing for additional information on the required tag.

SCHEMA_LOAD_FAILED#

a. Different standard schema versions in a merge group.
b. Library schemas in merge group have the same tag.
c. A schema with that name, version, and namespace prefix cannot be found.

See [7.2.5.6 Loading multiple partnered schemas](./07_Library_schemas.md#7256-loading- multiple-partnered-schemas) for a more detailed description of the rules.

SIDECAR_BRACES_INVALID#

a. A name appearing in curly braces in a sidecar HED annotation is not the word HED or the name of a HED-annotated column in the sidecar.
b. A column name entry in a sidecar has a HED annotation with curly braces, but this name also appears in curly braces in another HED annotation.
c. The curly braces in a sidecar are nested or unmatched.
d. The curly braces appear as the substitution for a placeholder in another tag.

See 3.2.9. Sidecars for information on the requirements for using sidecars.

SIDECAR_INVALID#

a. The "HED" key is not a second-level dictionary key.
b. An annotation entry is provided for n/a.
c. A sidecar refers to a column in curly braces, but that column has no HED.

See 3.2.9. Sidecars for a general explanation of sidecar requirements.

SIDECAR_KEY_MISSING*#

(WARNING)

a. A value in a categorical column does not have an expected entry in a sidecar.
b. A {ref} in a sidecar does not correspond to a column in the associated tabular file.

Note: This warning is only triggered if the categorical column in which the value appears does have HED annotations.

See 3.2.9. Sidecars for a general explanation of sidecar requirements.

TAG_EMPTY#

a. A HED string has extra commas or parentheses separated by only white space, indicating empty tags.
b. A HED string begins or ends with a comma (ignoring white space), indicating an empty string.
c. A tag group is empty (i.e., empty parentheses are not allowed).

See 3.2.7.3. Empty tags and groups for the rules on empty tags and groups.

TAG_EXPRESSION_REPEATED#

a. A tag is repeated in the same tag group or level.

Suppose A, B, and C represent HED expressions. HED strings are not ordered, so (B, C) is equivalent to (C, B). Thus, (A, (A, B)) is not a duplicate, but (A, (B, C), A) and (A, (B, C), (C, B)) are duplicates.

See 3.2.7.4. Repeated expressions for additional information on the rules for duplication.

TAG_EXTENDED*#

(WARNING)

a. A tag represents an extension from the schema.

Note: Often such extensions are really spelling errors and not meant to extend the schema.

Note: Annotators are discouraged from extending the schema unless absolutely necessary. If an extension tag is needed, annotators should consider posting an issue explaining the tag extension so that an addition to the respective schema might be considered.

See 3.2.5 Tag extensions for additional information on the tag extension rules.

TAG_EXTENSION_INVALID#

a. A tag extension term is already in the schema.
b. A tag extension term does not comply with rules for schema nodes. c. A tag has extension, but an extension is not allowed.

See 3.2.5 Tag extensions for additional information on the tag extension rules.

TAG_GROUP_ERROR#

a. A tag has tagGroup or topLevelTagGroup attribute, but is not enclosed in parentheses.
b. A tag with the topLevelTagGroup does not appear at a HED tag group at the top level in an assembled HED annotation. c. Multiple tags with the topLevelTagGroup attribute appear in the same top-level tag group. Note: a single Duration and a single Delay may be in the same group.

See 3.2.7.2. Tag group attributes for additional information on the rules for group errors due to schema attributes.

See also: TEMPORAL_TAG_ERROR for errors involving Onset, Offset, Inset, Duration and Delay.

TAG_INVALID#

a. The tag is not valid in the schema it is associated with.
b. The tag has extra internal whitespace, including directly before or after forward slashes.
c. The tag has a leading, trailing, or consecutive forward slashes.
d. A tag or tag extension contains a non name character.

See 3.2.2. Tag forms for a discussion of tag forms and their relationship to the HED schema.

TAG_NAMESPACE_PREFIX_INVALID#

a. A tag prefix has invalid characters.

See 3.2.6. Tag namespace prefixes and 7. Library schema for additional information on using multiple schemas in annotation.

TAG_NOT_UNIQUE#

a. A tag with unique attribute appears more than once in an event-level HED string.

See 3.2.10.2. Event-level processing for additional information on the unique tag.

TAG_REQUIRES_CHILD#

a. A tag has the requireChild schema attribute but does not have a child.

See 3.2.4. Tags that take values for an explanation of the requireChild attribute.

TEMPORAL_TAG_ERROR#

Note: For the purpose of Onset/Offset matching, Def or Def-expand tags with different placeholder substitutions are considered to be different.

a. An Offset, Onset, Inset, Duration, or Delay tag does not appear in a tag group.
b. An Offset, Onset, Inset, Duration, or Delay tag appears in a nested tag group (not a top-level tag group).
c. An Onset, Offset or Inset tag is not grouped with exactly one Def tag or Def-expand group.
d. An Onset, Inset, Duration, or Delay tag group contains more than one additional tag group.
e. An Offset appears with one or more tags or additional tag groups.
f. An Offset tag appears before an Onset tag associated with the same definition.
g. An Offset tag associated with a given definition appears after a previous Offset tag. without the appearance of an intervening Onset of the same name.
h. An Onset or an Inset tag group with has tags besides the anchor Def tag or Def-expand group that are not in a tag group.
i. An Onset or Offset with a given Def tag or Def-expand group anchor appears in an event marker with the same time as with another Onset, Inset, or Offset that uses the same anchor.
j. An Inset tag is not grouped with a Def tag or a Def-expand group corresponding to an ongoing Onset.
k. An Onset, Inset, or Offset tag appears in an annotation for a non-time tabular file.
l. A Duration or Delay tag group contains extra tags or groups, or is missing the required group.
m. An Offset, Onset, Inset, Duration, or Delay tag appears with other top level tags, except Delay and Duration which can be paired.

See also: TAG_GROUP_ERROR.

Note: if the Onset tag group’s definition is in expanded form, the Def-expand will be an additional internal tag group.

See 3.2.8.3 Onset, Offset, and Inset for a specification of the required behavior of the Onset, Offset, and Inset tags.

5.3.1. Using Onset and Offset in Chapter 5 gives examples of usage and additional details.

UNITS_INVALID#

a. A tag has a value with units that are invalid or not of the correct unit class for the tag.
b. A unit modifier is applied to units that are not SI units.

See 3.2.4 Tags that take values for more information.

VALUE_INVALID#

a. The value substituted for a placeholder (#) is not valid.
b. A tag value is incompatible with the specified value class.
c. A tag value with no value class is assumed to be a text and contains invalid characters. d. The units are not separated from the value by a single blank.

See 3.2.4 Tags that take values for more information.

B.2. Schema validation errors#

This section is organized by the type of schema format that results in the error. Errors that might be detected regardless of the schema format start with HED_SCHEMA. Errors that are specific to the .mediawiki format start with HED_WIKI. Errors that occur in the construction of the XML version or that are detected by XML validators when the planned XSD validation is implemented start with HED_XML.

B.2.1. General validation errors#

SCHEMA_ATTRIBUTE_INVALID#

a. An attribute is used in the schema, but is not defined in the schema attribute section.
b. A schema attribute is applied to the incorrect type (e.g., an element with the unit definition does appear under an appropriate unit class).
c. A schema attribute is used in an invalid way

Attribute

Invalid Usage Location

deprecatedFrom

See SCHEMA_DEPRECATION_ERROR

rooted

See SCHEMA_LIBRARY_INVALID

takesValue

Used on a non-placeholder(#) node.

unitClass

Used on a non-placeholder(#) node.

valueClass

Used on a non-placeholder(#) node.

Notes:

  • A tag (referred to as a node element in the schema) can have schema attributes that have the nodeClassProperty or the elementProperty or have no type property designator.

  • A unitClass element can only have schema attributes that have the unitClassProperty or the elementProperty.

  • A unitModifier element can only have schema attributes that have the unitModifierProperty or the elementProperty.

  • A unit element can only have schema attributes that have the unitProperty or the elementProperty.

  • A valueClass element can only have schema attributes that have the valueClassProperty or the elementProperty.

SCHEMA_ATTRIBUTE_VALUE_INVALID#

a. A non-boolean schema attribute has an invalid value or usage as indicated by the following table.

Attribute

Invalid Attribute Value

allowedCharacter

Not a single character or one of:
letters, blank, digits, alphanumeric.

conversionFactor

Not a positive numeric value.

defaultUnits

Not a valid unit in this unit class.

deprecatedFrom

See SCHEMA_DEPRECATION_ERROR

inLibrary

The value of an inLibrary attribute is for the wrong library.

relatedTag

Not an existing tag.

rooted

See SCHEMA_LIBRARY_INVALID

suggestedTag

Not an existing tag.

unitClass

Not an existing unit class.

valueClass

Not an existing value class.

SCHEMA_CHARACTER_INVALID#

a. A non-placeholder schema node contains non-name characters. b. A unit class name contains non-name characters.
c. A value or unit class name contains non-name or blank characters. d. The prologue or epilogue contain characters other than text or newline.

See 2.2 Character sets and restrictions for definitions of the different types of characters.

Note: tag extensions may contain nonascii characters.

SCHEMA_DEPRECATION_ERROR#

a. The value of deprecatedFrom is not a previously released HED schema version.
b. A deprecated tag is used as a suggestedTag or a relatedTag in a non-deprecated tag.
c. A child tag of a deprecated tag does not have the deprecatedFrom attribute.
d. A deprecated attribute is used on a non-deprecated element. e. A deprecated property is used on a non-deprecated attribute. f. A deprecated unit class has non-deprecated units. g. A tag has deprecated unit or value classes. h. A deprecated unit class has non-deprecated units. i. A unit class has a deprecated default unit

SCHEMA_DUPLICATE_NODE#

a. A schema node name appears in the schema more than once.

SCHEMA_HEADER_INVALID#

a. The schema header has invalid characters or format.
b. The schema header has unrecognized attributes.

SCHEMA_LIBRARY_INVALID#

Library schema errors are specific to library schema. Library schema may also raise any of the other schema errors.
a. The specified library name is not alphabetic or lowercase.
b. The withStandard attribute is used in a header that does not also have the library attribute.
c. The withStandard attribute value does not correspond to a valid standard schema version.
d. The rooted attribute appears in a schema whose header does not have unmerged="true" as well as appropriate library and withStandard header values.
e. A node with the rooted attribute is not at the top level.
f. A node with the rooted attribute does not correspond to a node in its partnered standard schema.
g. A library schema with the unmerged="true" header attribute has an inLibrary attribute in some element.
h. A library schema with the unmerged="true" duplicates special section items found in its partnered standard schema.

SCHEMA_SECTION_MISSING#

a. A required schema section is missing.
b. The required sections (corresponding to the prologue, schema, unit classes, unit modifiers, value classes, schema attributes, properties and epilogue) are not in the correct order and hence not detected.

Note: Required schema sections may be empty, but still be given.

SCHEMA_VERSION_INVALID#

a. The schema version in the HED line or element is invalid.
b. A HED version specification does not have the correct syntax for the schema file format.
c. A HED schema version does not comply with semantic versioning.

B.2.3. MediaWiki format errors#

WIKI_DELIMITERS_INVALID#

a. Delimiters used in the wiki are invalid.
b. Schema line content after node name is not enclosed with <nowiki></nowiki> delimiters.
c. A line has unmatched or multiple <nowiki></nowiki>, [ ], or { } delimiters.
d. Attributes section of a node is malformed(e.g., hanging = character).

WIKI_LINE_START_INVALID#

a. Start of body line not ''' or *.

WIKI_SEPARATOR_INVALID#

a. A malformed section separator is present
b. A duplicate section separator is present.

B.2.4. XML format errors#

XML_SYNTAX_INVALID#

a. XML syntax or does not comply with specified XSD.

B.2.5 Schema loading errors#

Schema loading errors can occur because the file is inaccessible or is not proper XML. Schema loading errors are handled in different ways by the Python and JavaScript tools.

Python tools generally raise a HedFileError exception when a failure to load the schema occurs. The calling programs are responsible for deciding how to handle such a failure.

JavaScript tools in contrast are mainly used for validation in HED validation BIDS and are mainly called by the BIDS validator. If a BIDS dataset uses HED, it must provide a HED version specification in thedataset_description.json file. If the HED JavaScript validator cannot load a valid HED schema based on this specification it reports a SCHEMA_LOAD_FAILED issue. A BIDS dataset

None