How can you use HED?

HED (Hierarchical Event Descriptors) serves different needs throughout the research lifecycle. Whether you’re collecting data, annotating datasets, or analyzing results, HED provides tools and frameworks to make your work more efficient and your data more valuable.

New to HED?

If this is your first time learning about HED, start with the Introduction to HED for basic concepts and quick start paths. This guide provides detailed workflows for each research role.

Choose your path

Research roles and HED workflows

HED serves researchers in different capacities throughout the data lifecycle. Choose your primary role to find relevant tools and guidance:

🧪 Experimenter

Planning experiments, collecting data with proper event logging, and preparing data for analysis.

Key needs: Event logging best practices, data collection standards, log-to-event conversion

🧪 As an experimenter
📝 Data annotator

Adding HED annotations to existing datasets, curating data for sharing, BIDS/NWB integration.

Key needs: Annotation tools, validation workflows, standardized formats

📝 As a data annotator
📊 Data analyst

Searching and analyzing HED-annotated data, extracting design matrices, cross-study comparisons.

Key needs: Search tools, programming APIs, analysis workflows

📊 As a data analyst
🛠️ Tool developer

Building software that integrates with HED, creating analysis pipelines, extending HED functionality.

Key needs: APIs, schema specifications, integration guidelines

🛠️ As a tool developer
🏗️ Schema builder

Developing domain-specific vocabularies (HED library schemas) to capture domain specific concepts in metadata.

Key needs: Schema development tools, community coordination, validation frameworks

🏗️ As a schema builder

🧪 As an experimenter

Planning experiments, collecting data, and preparing for analysis

You’re designing and running experiments to test hypotheses and study behavior. HED helps you capture what actually happened during data collection in a way that maximizes downstream usability and enables powerful analyses.

Challenges for experimenters

❌ Without HED

  • Meaningless event codes (1, 2, 3)

  • Log files require constant documentation

  • Analysis code breaks when events change

  • Difficult to compare across experiments

  • Data sharing requires extensive explanation

✅ With HED

  • Self-documenting event annotations

  • Standardized vocabulary across studies

  • HED-enabled analysis works automatically

  • Easy cross-experiment comparisons

  • Data ready for sharing in BIDS/NWB

🎯 Data collection

Planning and running experiments

Key questions to address

  • What events should be logged during data collection?

  • How will experimental design and conditions be recorded?

  • How will logs be synchronized with neuroimaging data?

  • What participant responses need to be captured?

Critical principle: Data that isn’t recorded is lost forever!

Event logging best practices

  • Mark ALL events visible to participants (stimuli, cues, instructions, feedback)

  • Record participant responses with precise timing

  • Include experimental control markers (trial/block boundaries, condition changes)

  • Capture incidental events that might affect neural responses

  • Plan for pilot testing to identify missing events

Example event types to capture:

  • Sensory presentations: Visual stimuli, auditory cues, tactile feedback

  • Participant actions: Button presses, eye movements, verbal responses

  • Experimental control: Trial starts, condition changes, break periods

  • Environmental events: Equipment issues, interruptions, calibration

🔄 Post-processing

Post-processing and data transformation

After data collection, raw logs need processing before analysis. The table-remodeler tools help transform experimental logs into analysis-ready event files.

Common transformations

  1. Log summarization: Get overview of collected events

  2. Code expansion: Convert numeric codes to meaningful categories

  3. Column restructuring: Create BIDS-compliant event files

  4. Data validation: Check for missing or invalid events

Ideally, your experiment control software should be adjusted to produce event files in a tabular format that are suitable for BIDS or NWB. The table-remodeler allows users to perform these operations effectively. The tools can be run over an entire BIDS dataset using the table remodeler command line interface (CLI) or on a single file using the HED online tools with the Execute remodel script action for events. The table-remodeler allows users to assemble a complex list of command to execute but specifying in JSON as illustrated by the following example:

Workflow to summarize column values

[{
   "operation": "summarize_column_values",
   "description": "Get overview of log contents",
   "parameters": {
       "summary_name": "Log_summary",
       "skip_columns": ["onset"],
       "value_columns": ["description"]
   }
}]

📋 Data sharing

Standardizing data format for sharing

An important aspect of data collection is organizing your data in a standardized format so that analysis tools can read and manipulate the data without special-purpose reformatting code. BIDS and NWB are the most widely-used standards for organizing brain and behavioral data in neuroscience.

BIDS (Brain Imaging Data Structure)

BIDS is a widely used data organization standard for neuroimaging and behavioral data. BIDS focuses on file organization with appropriate experimental metadata.

HED in BIDS

There are two strategies for incorporating HED annotations in a BIDS dataset:

Method 1: Use a JSON (sidecar) file to hold the annotations (recommended)

Method 2: Annotate each line in each event file using the HED column

Method 1 is typical for most annotations. The HED online tools generate annotation templates. The BIDS annotation quickstart walks through this process.

Method 2 is usually used for instrument-generated annotations or manual marking (bad sections, special features).

When using HED in BIDS, specify HED schema versions in dataset_description.json in the dataset root directory. See HED schema versions for examples.

HED in NWB (Neurodata Without Borders)

NWB is a data standard for neurophysiology, providing specifications for storing cellular, intracellular, and extracellular physiology data, along with experimental metadata and behavior. A single NWB file holds all session data synchronized to a common timeline.

HED annotations in NWB use the ndx-hed extension with three main classes:

  • HedLabMetaData: Required for all HED-annotated NWB files; specifies HED schema version

  • HedTags: Used for row-specific HED annotations in any NWB DynamicTable

  • HedValueVector: Used for column-wide HED templates with value placeholders

Installation: pip install -U ndx-hed

BIDS allows NWB file format for recording sessions within a BIDS-organized experiment. HED is well-integrated into both standards.

Resources for experimenters

📝 As a data annotator

Curating datasets, adding HED annotations, and validating data quality

You’re adding meaningful annotations to event data, ensuring consistency and completeness, and validating that datasets meet quality standards. HED provides tools and workflows to make your data FAIR (Findable, Accessible, Interoperable, Reusable).

Annotator challenges

❌ Without HED

  • Events meaningless without docs

  • Each dataset needs custom interpretation

  • Hard to validate metadata completeness

  • Manual coding for every analysis

  • Hard to find similar datasets

✅ With HED

  • Self-documenting event annotations

  • Standardized vocabulary across datasets

  • Automated validation and quality checks

  • Analysis tools work out of the box

  • Easy cross-dataset search and comparison

📚 Basic background

Getting started resources

✏️ Adding HED annotations

Annotation strategies

This section discusses strategies for adding HED annotations to event data. The primary method for BIDS datasets is using JSON sidecar files. For NWB, annotations are added using the ndx-hed extension classes.

Basic annotation workflow

HED annotations come in a variety of levels and complexity. Start simple and incrementally improve annotations:

  1. Generate template: Use HED online tools to create a JSON sidecar template from your event file

  2. Add descriptions: Replace the template dummy descriptions with actual descriptions.

  3. Add core tags: Annotate sensory presentations, agent actions, and experimental structure

  4. Validate frequently: Use the online tools to validate after each addition to catch errors early

  5. Expand gradually: Add temporal scope, conditions, and definitions as needed

Key annotation principles

  • Start with descriptions: A good description clarifies what information to capture in tags

  • Be specific: Use the most specific tags that accurately describe events

  • Include context: Capture participant actions, stimuli properties, and experimental conditions

  • Beware of semantics: Follow guidelines in HED annotation semantics

A proper HED annotation can be translated back into a meaningful sentence.

Viewing available tags

The HED vocabulary is hierarchically organized. Use the HED schema browser to explore standard and library schema tags interactively.

Cross-format workflows

For NWB users, you can convert an NWB Events table to a BIDS _events.tsv file, generate templates, annotate, and transform back. See the BIDS to NWB conversion example.

Advanced annotation concepts

For complete experimental descriptions, HED supports several advanced features:

  • Definitions: Define complex, reusable concepts that can be referenced throughout annotations

  • Temporal scope: Annotate processes extending over time using Duration, Delay, Onset, Offset, and Inset tags

    • Enables detection of everything happening at any time point

    • Supports complex, interleaved event processes

    • See Temporal scope

  • Experimental design: Express conditions, tasks, and temporal organization

The Advanced annotation chapter explains complete rules and usage patterns.

✓ Validating HED annotations

Validation workflow and resources

Validation workflow

Checking for errors is an ongoing, iterative process. Build complex annotations on a foundation of valid annotations by validating frequently as you add tags.

Validation resources

  • Guide: HED validation guide - Different validator types and usage

  • Error reference: HED errors - Error types and causes

  • Online validation: HED online tools - Validate strings, JSON sidecars, and tabular files easily

  • Python validation: Use hedtools package for programmatic validation

Validation strategy

  1. Validate JSON sidecars first: Contains most annotations; easier to fix than full dataset

  2. Use standalone validation: Validate HED separately before full BIDS validation

  3. Fix errors incrementally: Address errors as you build annotations

  4. Validate after changes: Revalidate whenever you modify annotations

Common validation issues

  • Misspelled tags

  • Improper use of values or units

  • Duplicate tags or tag groups (particularly from multiple rows)

  • Invalid tag combinations or groupings (tagGroup and topLevelTagGroup)

  • Misunderstanding of how temporal tags such as onset are used

🔍 Checking for consistency

Consistency checking tools and strategies

Consistency checking tools

Beyond syntactic validation, check that annotations are logically consistent and complete.

Summary-based checking

These summaries help detect:

  • Missing or unexpected event codes

  • Incomplete annotations

  • Data entry errors

  • Inconsistent trial structures

Experiment-specific checks

Some consistency issues require domain knowledge:

Example: Trial sequence validation

Suppose each trial should follow: stimulus → key-press → feedback

Participants may:

  • Forget to press the key

  • Press the wrong key

  • Press multiple times

  • Press before feedback

Annotators should mark these anomalies in the event file so downstream analysis handles them correctly.

Checking strategies

  • Use summary tools to identify anomalies

  • Write custom code for experiment-specific checks (work underway to add standard checks to table-remodeler)

  • Mark bad trials or unusual events explicitly

  • Consider reorganizing event files using remodeling tools (see Remap columns)

Resources for data annotators:

📊 As a data analyst

Using HED-annotated data for scientific discovery and cross-study analysis

Whether you are analyzing your own data or using shared data produced by others to answer a scientific question, fully understanding the data and its limitations is essential for accurate and reproducible analysis. HED annotations and tools enable powerful analysis workflows that work consistently across different experiments.

Challenges for data analysts

❌ Without HED

  • Each dataset requires custom code

  • Event meanings buried in documentation

  • Cannot compare across studies

  • Manual data inspection for every analysis

  • Difficult to validate assumptions

✅ With HED

  • Standardized search across datasets

  • Self-documenting event structure

  • Automatic design matrix extraction

  • Consistent analysis workflows

  • Built-in data quality summaries

📊 Understanding the data

Data quality and content assessment

Before running any analysis, you need to understand what events are actually present in your data. Most shared datasets have minimal documentation, so HED summary tools help you quickly assess data quality and content without manual inspection.

Column value summaries

The column value summary compiles a summary of the values in the various columns of the event files in a dataset.

  • Does not require HED annotations

  • Shows all unique values and their frequencies

  • Helps identify missing or unexpected event codes

  • Useful for detecting data entry errors

You can generate this summary using the HED online tools for debugging by uploading a single event file (e.g., a BIDS _events.tsv) and its associated JSON sidecar.

HED tag summaries

The HED tag summary creates a summary of the HED tags used to annotate the data.

  • Shows what types of events are present

  • Works across different event coding schemes

  • Enables comparison between datasets

  • Requires HED annotations in the dataset

Experimental design summaries

The experimental design summary gives a summary of the condition variables or other structural tags relating to experimental design, task, or temporal layout of the experiment.

  • Extracts experimental conditions automatically

  • Shows task structure and organization

  • Identifies temporal markers (Onset/Offset/Duration)

  • Requires HED annotations with condition variables

Additional resources:

  • The table-remodeler documentation gives an overview of the remodeling tools and how to use them.

  • The HED conditions and design matrices guide explains how information structure information is encoded in HED and how to interpret the summaries of this information.

🛠️ Preparing the data

Data transformation and restructuring

After understanding your data, you may need to transform or reorganize event files to support your analysis goals.

Data transformation

HED remodeling tools allow you to transform event files without writing custom code:

  • Remap columns: Reorganize column structure for analysis tools

  • Factor extraction: Create binary factor vectors for event selection

  • Column merging: Combine information from multiple columns

  • Value renaming: Standardize event codes across sessions

Event file restructuring

Common restructuring tasks include:

  • Converting wide-format to long-format event files

  • Extracting condition variables into separate columns

  • Adding computed columns (e.g., reaction times, trial types)

  • Filtering events based on criteria

See the table-remodeler documentation for detailed examples and operation descriptions.

📈 Analyzing the data

Event selection and analysis workflows

HED enables powerful, flexible analysis through standardized event selection and design matrix extraction. The key advantage is that HED queries work consistently across different experiments using different event codes.

Factor vectors and selection

The most common analysis application is to select events satisfying particular criteria, and compare some measure on signals containing these events with a control.

HED facilitates this selection through factor vectors. A factor vector for an event file has the same number of rows as the event file (each row corresponding to an event marker). Factor vectors contain 1’s for rows in which a specified criterion is satisfied and 0’s otherwise.

Types of factor operations:

  • factor column operation: Creates factor vectors based on the unique values in specified columns. This operation not require HED annotations.

  • factor HED tags: Creates factor vectors based on a HED tag query. Enables flexible, generalizable event selection.

  • factor HED type: Creates factors based on HED tags representing structural information such as Condition-variable, Task, or Temporal-marker.

HED search queries

HED search queries allow you to find events based on their semantic properties rather than specific event codes. This enables:

  • Cross-study analysis: Same query works on different datasets

  • Flexible criteria: Complex boolean logic with AND, OR, NOT

  • Hierarchical matching: Search at any level of tag hierarchy

  • Temporal context: Find events within ongoing processes

The HED search guide explains the HED query structure and available search options in detail.

HED analysis in EEGLAB

EEGLAB, the interactive MATLAB toolbox for EEG/MEG analysis, supports HED through the EEGLAB HEDTools plugin.

Key capabilities:

  • Event search and epoching based on HED queries

  • Automated design matrix extraction

  • Integration with EEGLAB’s analysis pipeline

  • Support for both GUI and scripting workflows

Getting started with HED in EEGLAB:

The End-to-end processing of EEG with HED and EEGLAB book chapter, which can be found at https://doi.org/10.1007/978-1-0716-4260-3_6, works through the entire analysis process, including porting the analysis to high performance computing platforms. The site includes sample data to use in running the examples.

HED support in other tools

Work is underway to integrate HED support in other analysis packages:

  • FieldTrip: Search and epoching integration in development

  • MNE-Python: Planned support for HED search and summary

  • NEMAR/EEGNET: Platform integration for large-scale analysis

If you are interested in helping with HED integration in other tools, please email hed.maintainers@gmail.com.

Resources for data analysts

🛠️ As a tool developer

Building software that integrates with HED and expanding the HED ecosystem

The HED ecosystem relies on tools that read, understand, and incorporate HED as part of analysis. Whether you’re adding HED support to existing software or creating new analysis tools, HED provides well-documented APIs and validation libraries to make integration straightforward.

Challenges for tool developers

❌ Without HED

  • Custom event parsing for each dataset

  • Hard-coded event interpretations

  • Difficult to support multiple studies

  • Manual validation of event structure

  • Limited cross-tool compatibility

✅ With HED

  • Standardized event parsing

  • Semantic event interpretation

  • Works across any HED-annotated dataset

  • Automated validation with clear errors

  • Interoperable with HED ecosystem

🚀 Getting started with HEDTools

Understanding HED structure and choosing your platform

Before diving into code, understanding HED’s structure and choosing the right platform will save time and ensure your integration follows HED best practices.

Understanding HED schemas

HED schemas define the vocabulary available for annotations:

  • HED standard schema: Contains basic terms common across neuroimaging experiments

  • HED library schemas: Domain-specific vocabularies (e.g., SCORE for clinical EEG)

  • Schema versions: Schemas evolve with numbered versions (e.g., 8.3.0)

####Key concepts for developers

  • Schema loading: Most HED tools require a schema version (e.g., 8.4.0) in order to operate. The most recent versions are cached internally so that a given version of the schema is only loaded once.

  • Validation: Use HED validator libraries rather than implementing your own

  • Short vs long form: Tags can be written in short form (single tag: e.g., Face) or long form (full path to the root of the schema hierarchies: e.g., Item/Biological-item/Anatomical-item/Body-part/Head/Face). Tools should be able to handle all forms, including intermediate partial paths. Rely on the HED tools to transform when needed. The long form is needed mostly for search – searching for Body-part should also return more specific annotations such as Face.

See HED schemas guide for detailed information about the HED schemas.

Choosing your platform

HED provides official tools in three languages:

  • Python: Most comprehensive, includes validation, analysis, and schema development tools

  • JavaScript: Focuses on validation, used by BIDS validator. A completely browser-based validator allows a complete data directory to be validated

  • MATLAB: Analysis-focused, integrates with EEGLAB - uses the Python tools underneath.

Decision guide:

  • Web applications: Use JavaScript validator or call REST services

  • Analysis pipelines: Use Python for maximum flexibility

  • MATLAB workflows: Use HEDTools plugin or MATLAB wrappers

  • Custom needs: Consider calling REST services from any language

Note: HED REST services are available at HED online tools.

💻 Working with code bases

Open-source HED implementations and tools

The GitHub HED standard organization maintains open-source code projects in Python, MATLAB, and JavaScript. All repositories welcome contributions, issue reports, and pull requests.

Core resources

Python HEDTools

Focus: Core HED technology including validation, analysis, and schema development

JavaScript HEDTools

Focus: HED validation for web applications and BIDS validator

MATLAB HEDTools

Focus: Analysis, annotation, and validation with EEGLAB integration

  • Repository: hed-matlab - Installation: Via EEGLAB plugin manager

  • Documentation: HED MATLAB tools

  • CTagger - a standalone annotation Java-based annotation tool with an EEGLAB plugin available.

Online tools and REST services

Focus: Web-based validation, debugging, and programmatic access

🤝 Contributing to HED development

The HED project welcomes contributions from the community. Whether you’re reporting bugs, suggesting features, or contributing code, your input helps improve HED for everyone.

Where to report:

Contributing code

All HED repositories welcome pull requests. See the CONTRIBUTING.md file in each repository for specific guidelines. If you have ideas or want to contribute to these efforts, please post an issue or email hed.maintainers@gmail.com.

Long-term vision

The HED community is actively working on expanding HED’s capabilities and integration:

  • Develop more sophisticated analysis methods

  • Leverage AI to reduce the cognitive burden on users

  • Better integrate experimental control software with annotation workflows

  • Capture event relationships for complex automated analysis

  • Expand library schemas for specialized domains

📚 Resources for tool developers

🏗️ As a schema builder

Extending HED vocabulary to support specialized domains and applications

HED annotations use terms from a hierarchically structured vocabulary called a HED schema. The HED standard schema contains basic terms common across most experiments, while HED library schemas extend the vocabulary for specialized domains like clinical EEG, movie annotation, or language studies.

Challenges for schema builders

❌ Without structured schemas

  • Inconsistent terminology across studies

  • Duplicate or conflicting terms

  • No validation of vocabulary structure

  • Difficult to share domain vocabularies

  • Hard to maintain backward compatibility

✅ With HED schema framework

  • Structured, hierarchical vocabulary

  • Automated validation of schema structure

  • Version control and compatibility tracking

  • Community review process

  • Standardized schema attributes and rules

🔍 Exploring existing schemas

Understanding existing HED vocabularies

Before proposing changes or creating a new schema, familiarize yourself with existing HED vocabularies to avoid duplication and understand HED’s organizational principles.

Viewing available schemas

The HED schema browser provides an interactive view of the HED standard schema, showing:

  • Hierarchical tag structure

  • Tag descriptions and attributes

  • Value classes and unit classes

  • Schema version history

All of the versions and prereleases of the schemas are available through the viewer.

Schema
version

Type

Description

Status

8.4.0

standard

Basic infrastructure and vocabulary needed to annotate experiments

released

score_2.1.0

library

Clinical EEG annotation vocabulary

released

lang_1.1.0

library

Language stimulation annotations

released

slam_1.0.0

library

Sensor positions vocabulary for EMG

prerelease

mouse_1.0.0

library

Annotations for mouse experiments

prerelease

media

Library

Tags for annotating images and video

proposed

Understanding schema structure

HED schemas have structured elements including:

  • Tags: Hierarchically organized terms (e.g., Sensory-event)

  • Attributes: Properties of tags (e.g., relatedTag, reserved, topLevelTagGroup)

  • Value classes: Allowed value types (e.g., textClass, numericClass)

  • Unit classes: Measurement units and conversions (e.g., timeUnits, angleUnits)

Tags are the main elements of interest. The tags have attributes that specify behavior. For example the topLevelTagGroup specifies that this tag is a special tag that can only appear inside parentheses at the top level of an annotation. The Definition tag is a special tag in the standard schema that has both the reserved and the topLevelTagGroup attributes.

The value classes and unit classes are mainly relevant for tags that take values. These tags have a # placeholder in the schema hierarchy, indicating that they can be specified with a value. For example, the Temperature tag’s # child has the numeric value class and the temperatureUnits unit class, allowing annotations such as Temperature/32 oC.

Key principles:

  • Is-a relationship: Every tag has an “is-a” relationship with its parents

  • Uniqueness: Each term must be unique and not redundant with existing terms

  • Self-contained: Tag descriptions should be understandable without external context

See the HED specification for the rules that govern HED tag syntax and usage. See HED schema developer guide for detailed information on schema structure and design principles.

✏️ Contributing to existing schemas

Proposing improvements to HED schemas

The HED community welcomes suggestions for improving existing schemas. Whether you’ve found an error, need additional terms, or want to clarify descriptions, your input helps improve HED for everyone.

Improving an existing schema

If you see a need for additional terms in an existing schema, post an issue to hed-schemas/issues on GitHub.

Proposing changes to HED schemas

For new tags, include:

  • The name of the schema (standard or library name)

  • Proposed name of the new term

  • Brief and informative description of its meaning

  • Suggested location in the schema hierarchy

  • Explanation of why this term is needed and how it will be used

  • Examples of usage in annotations

For modifications to existing terms:

  • Current term name and location

  • Proposed changes (description, attributes, hierarchy)

  • Rationale for the change

  • Impact on existing annotations (if applicable)

For schema attributes or structure:

  • Description of the proposed new attribute, value class, or unit class

  • Use cases and examples

  • How it relates to existing schema features

Schema review process

Schema changes go through a community review process:

  1. Issue posted: You describe the proposed change on GitHub

  2. Community discussion: Others comment on the proposal

  3. Refinement: The proposal is refined based on feedback

  4. Implementation: Approved changes are implemented in the schema

  5. Version release: Changes are included in the next schema version

Important considerations:

  • Is-a relationship: New terms must satisfy the “is-a” relationship with parent tags

  • Uniqueness: Terms must not duplicate existing vocabulary

  • Clarity: Descriptions should be self-contained and unambiguous

  • Backward compatibility: Changes should minimize breaking existing annotations

All suggested changes should be reported using the hed-schemas/issues mechanism on GitHub.

🏛️ Creating new schemas

Developing new HED library schemas

If your domain requires extensive specialized vocabulary not appropriate for the standard schema, you may want to create a new HED library schema.

Creating a new library schema

Creating a library schema is a collaborative process that requires community engagement.

Getting started:

Post an issue on hed-schemas/issues to start the discussion.

Proposing a new HED library schema

Initial proposal should include:

  • Proposed name for the HED library schema

  • Brief description of the library’s purpose and scope

  • Example use cases and target audience

  • List of potential collaborators (GitHub handles)

  • Initial thoughts on vocabulary organization

  • Relationship to existing HED schemas (what’s missing from standard schema)

Requirements:

  • GitHub account: All schema development uses GitHub Pull Request mechanism

  • Community engagement: Willingness to participate in review discussions

  • Documentation: Commitment to documenting terms clearly

  • Long-term maintenance: Plan for maintaining the schema over time

Schema development workflow

The schema development process follows these general steps:

  1. Proposal and discussion: Post issue and gather community feedback

  2. Planning: Define scope, structure, and initial term list

  3. Initial schema creation: Develop first version following HED schema rules

  4. Validation: Use schema validation tools to check structure

  5. Community review: Gather feedback through GitHub discussions

  6. Iteration: Refine based on feedback

  7. Release: Publish to hed-schemas repository

Essential reading:

The HED specification is the definitive source for the syntax and rules of HED. If you are interested in developing The HED schema developer’s guide provides comprehensive information on:

  • Schema XML structure and syntax

  • Attribute definitions and usage

  • Value class and unit class design

  • Versioning and compatibility

  • Testing and validation

  • Best practices for schema development

Private vocabularies and extensions

Can I create my own private HED schema?

While technically possible, private schemas are not recommended and have limited tool support.

Why standardized schemas are preferred:

  • Tool compatibility: Many HED tools assume standardized schemas from the hed-schemas repository

  • Schema fetching: Tools automatically fetch/cache official schemas

  • Cross-dataset comparison: Standardized vocabularies enable meta-analyses

  • Community benefit: Shared vocabularies benefit the entire research community

  • Long-term maintainability: Official schemas are maintained by the community

Alternatives to private schemas:

  • Propose library schema: Work with the community to develop a standardized library

  • Extend existing schema: Suggest additions to standard or library schemas

  • Use definitions: Create complex concepts using existing vocabulary

  • Temporary extensions: Use descriptive tags (e.g., Description/...) until proper terms are available

Decision rationale:

The HED Working Group decided to prioritize standardized schemas after observing that unvetted private vocabularies would compromise HED’s ability to enable standardized dataset summaries and cross-study comparisons.

If you have a use case that genuinely requires a private vocabulary, please email hed.maintainers@gmail.com to discuss options.

Resources for schema developers