HED Specification

Welcome to the official specification for Hierarchical Event Descriptors (HED), a system for annotating events and experimental structure using controlled vocabularies.

Quick links

• PDF released version (V3.3.0)

• HED resources

• HED homepage

About HED

HED (Hierarchical Event Descriptors) is a system for annotating events and experimental structure using controlled vocabularies. The HED ecosystem includes:

• Vocabularies - Standardized terms organized in hierarchical schemas

• Annotation tools - Software for creating and validating HED annotations

• Analysis tools - Methods for searching and analyzing HED-annotated data

• Community schemas - Domain-specific extensions to the base vocabulary

Specification contents

• 1. Introduction
  • 1.1. Scope of HED
  • 1.2. Brief history of HED
  • 1.2. Goals of HED
  • 1.3. HED design principles
  • 1.4. Specification organization
• 2. Terminology
  • 2.1. Definitions
    • Agent [*]
    • Condition-variable [*]
    • Control-variable [*]
    • Dataset
    • Event [*]
    • Event-context [*]
    • Event marker
    • Event-stream [*]
    • Experiment-participant [*]
    • Experimental-trial [*]
    • HED schema [*]
    • HED string
    • HED tag
    • Indicator-variable [*]
    • Parameter [*]
    • Recording [*]
    • Tag-group
    • Task [*]
    • Temporal scope
    • Time-block [*]
  • 2.2. Character sets and restrictions
• 3. HED formats
  • 3.1. Schema formats
    • 3.1.1. Official schema releases
    • 3.1.2. Schema layout overview
    • 3.1.3. Naming conventions
    • 3.1.4. MediaWiki schema format
    • 3.1.5. XML schema format
  • 3.2. Annotation formats
    • 3.2.1. Vocabulary organization
    • 3.2.2. Tag forms
    • 3.2.3. Tag case-sensitivity
    • 3.2.4. Tags that take values
    • 3.2.5. Tag extensions
    • 3.2.6. Tag namespace prefixes
    • 3.2.7. Strings and groups
    • 3.2.8. Special tags
    • 3.2.9. Sidecars
    • 3.2.10. Tabular files
  • 3.3. Semantic versioning
• 4. Basic annotation
  • 4.1. Instantaneous events
  • 4.2. Sensory presentations
  • 4.3. Task role
  • 4.4. Agent actions
  • 4.5. Experimental control
  • 4.6. Data features
  • 4.7. What else?
• 5. Advanced annotation
  • 5.1. Creating definitions
  • 5.2. Using definitions
    • 5.2.1. The Def tag
    • 5.2.2. The Def-expand tag
  • 5.3. Temporal scope
    • 5.3.1. Using Onset and Offset
    • 5.3.2. Using Inset
    • 5.3.3. Using Duration
    • 5.3.4. Using Delay
  • 5.4. Event streams
  • 5.5. Event contexts
  • 5.6. Experimental design
  • 5.7. Specialized annotation
    • 5.7.1. Parameter tags
• 6. Infrastructure and tools
  • 6.1. Basic tag handling
    • 6.1.1. Tag forms
    • 6.1.2. Parentheses and commas
    • 6.1.3. Tag ordering
    • 6.1.4. Definitions
  • 6.2. File-level handling
  • 6.3. HED support of BIDS
    • 6.3.1. BIDS tabular files
    • 6.3.2. BIDS timeseries
    • 6.3.3. BIDS sidecars
    • 6.3.4. Annotation assembly
    • 6.3.5. HED version in BIDS
    • 6.3.6. HED in the BIDS validator
    • 6.3.7. HED python tools
• 7. Library schemas
  • 7.1. Why library schemas?
  • 7.2. Standalone schemas
  • 7.3. Partnered schemas
    • 7.3.1. Partnered files
    • 7.3.2. Partnered formats
    • 7.3.3. Auxiliary sections
    • 7.3.4. Partnered attributes
    • 7.2.5. Motivation for partners
  • 7.4. Library schema design
    • 7.4.1. General design rules
    • 7.4.2. Standalone design rules
    • 7.4.3. Partnered design rules
    • 7.4.4. Schema namespaces
  • 7.5. Library schemas in BIDS
• 8. HED ontology
  • 8.1. HED views and representations
    • 8.1.1. The annotator’s view
    • 8.1.2. The ontologist’s view
    • 8.1.3. HED information space
    • 8.1.4. HED representations
  • 8.2. HED schema to ontology
    • 8.2.1. Overall ontology structure
    • 8.2.2. HED Tags
    • 8.2.3. Schema attributes
    • 8.2.4 Other auxiliary sections
  • 8.3. HED global identifiers
    • 8.3.1. Schema identifiers
    • 8.3.2. Ontology namespace
    • 8.3.3. HED IRIs
• Appendix A
  • A.1. Auxiliary schema sections
    • A.1.1. Unit classes and units
    • A.1.2. Unit modifiers
    • A.1.3. Value classes
    • A.1.4. Schema attributes
    • A.1.5. Schema properties
  • A.2. MediaWiki file format
    • A.2.1. Overall file layout
    • A.2.2. MediaWiki header
    • A.2.3. MediaWiki prologue and epilogue
    • A.2.4. MediaWiki schema section
    • A.2.5. MediaWiki auxiliary sections
  • A.3. XML file format
    • A.3.1. XML file layout
    • A.3.2. XML header
    • A.3.3. XML prologue and epilogue
    • A.3.4. XML schema section
    • A.3.5. XML auxiliary sections
• Appendix B
  • B.1. HED validation errors
    • CHARACTER_INVALID
    • COMMA_MISSING
    • DEF_EXPAND_INVALID
    • DEF_INVALID
    • DEFINITION_INVALID
    • ELEMENT_DEPRECATED*
    • PARENTHESES_MISMATCH
    • PLACEHOLDER_INVALID
    • REQUIRED_TAG_MISSING
    • SCHEMA_LOAD_FAILED
    • SIDECAR_BRACES_INVALID
    • SIDECAR_INVALID
    • SIDECAR_KEY_MISSING*
    • TAG_EMPTY
    • TAG_EXPRESSION_REPEATED
    • TAG_EXTENDED*
    • TAG_EXTENSION_INVALID
    • TAG_GROUP_ERROR
    • TAG_INVALID
    • TAG_NAMESPACE_PREFIX_INVALID
    • TAG_NOT_UNIQUE
    • TAG_REQUIRES_CHILD
    • TEMPORAL_TAG_ERROR
    • UNITS_INVALID
    • VALUE_INVALID
  • B.2. Schema validation errors
    • B.2.1. General validation errors
    • B.2.3. MediaWiki format errors
    • B.2.4. XML format errors
    • B.2.5 Schema loading errors