Writing HED annotations correctly

Why syntax matters

HED is not just a vocabulary. It is also a formal annotation syntax. This is important because HED annotations are meant to be processed by software tools.

A HED string that is scientifically meaningful but syntactically wrong may fail validation or behave unexpectedly in search and analysis.

This page gives a practical guide to the most important writing rules for researchers working with HED in BIDS.

1. A HED annotation is a comma-separated list of tags

The basic unit of annotation is a HED string.

A simple HED string looks like this:

Sensory-event, Visual-presentation, (Image, Face)

Rule

Separate tags with commas.

Correct

Sensory-event, Visual-presentation, (Image, Face)

Wrong

Sensory-event Visual-presentation (Image, Face)

The second example is invalid because HED tags and groups must be separated by commas.

2. HED strings are unordered at the same level

At the same level, HED tags do not depend on order.

These mean the same thing:

Sensory-event, Visual-presentation, (Image, Face)

(Image, Face), Sensory-event, Visual-presentation

What this means in practice

You do not need to worry about placing tags in a special order for meaning. What matters is:

which tags are present
which tags are grouped together

3. Parentheses show association

Parentheses are one of the most important parts of HED. They show that tags belong together.

Example without grouping

Red, Triangle, Blue, Square

This is ambiguous. It does not tell us whether the stimulus contains:

a red triangle and a blue square
a blue triangle and a red square
one object with all four properties

Correct grouped version

(Red, Triangle), (Blue, Square)

Now the meaning is clear:

one red triangle
one blue square

Practical rule

Use parentheses whenever tags should be interpreted as describing the same object, action, context, or event component.

4. Parentheses must match and be properly nested

Correct

Sensory-event, (Visual-presentation, (Image, Face))

Wrong

Sensory-event, (Visual-presentation, (Image, Face)

Wrong

Sensory-event, Visual-presentation), (Image, Face)

Every opening parenthesis must have a matching closing parenthesis, and groups must be properly nested.

5. Do not create empty tags or empty groups

These are invalid:

Sensory-event,, Visual-presentation

Sensory-event, ()

, Sensory-event, Visual-presentation

Sensory-event, Visual-presentation,

Practical rule

Avoid:

double commas
empty parentheses
leading commas
trailing commas

6. Do not repeat the same expression at the same level

Wrong

Red, Blue, Red

Wrong

(Image, Face), (Face, Image)

HED treats these as repeated expressions at the same level.

Practical rule

If the same tag or same group appears twice in the same place, remove the duplicate.

7. Short-form and long-form tags

HED tools allow you to write tags in short form.

Short form

Square

Long form

Item/Object/Geometric-object/2D-shape/Rectangle/Square

In normal annotation work, short form is usually preferred because it is easier to read and write.

Important caution

Short-form works only if the tag name is unique in the active schema set.

If multiple schemas are used and a term is ambiguous, a namespace or fuller form may be needed.

8. Use tag extensions only when truly necessary

Sometimes researchers want to invent a new term that is not in the schema. This is called a tag extension.

In practice, beginners should avoid this whenever possible.

Why

Extensions make annotations less standardized and less reusable across datasets. Many supposed extensions are actually:

spelling mistakes
unnecessary synonyms
concepts already available elsewhere in the schema

Good practice

Before creating an extension:

Search the schema browser carefully.
Try broader or related terms.
Use a more general tag plus additional properties if possible.

9. Some tags require values

Certain HED tags are meant to take a value. For example, identifiers, labels, parameters, file paths, or numeric values may be attached through tags that expect a child value.

Examples you may see in BIDS sidecars include:

Pathname/u032.bmp

Label/Face-image

ID/13

Practical rule

If a tag is used to store a concrete value, the value is written as the child of the tag using a slash.

10. The `#` placeholder is for sidecars and definitions

One of the most important BIDS-related HED rules is the use of the # placeholder.

The # symbol stands for:

insert the actual value from the event table here

Example in an events.json sidecar

{
  "stim_file": {
    "Description": "Path to the stimulus image file",
    "HED": "(Image, Pathname/#)"
  }
}

If a row in events.tsv contains:

stim_file = faces/u032.bmp

then the assembled HED annotation becomes:

(Image, Pathname/faces/u032.bmp)

Important rules

Use # in sidecar entries for value columns.
Do not use # directly in row-wise event annotations unless the syntax specifically requires it through definitions.
A value-column HED string should contain exactly one placeholder for the inserted value.

11. Categorical columns and value columns are handled differently

In BIDS, columns often fall into two practical types.

A. Categorical columns

These contain a fixed set of repeated values such as:

show_face
left_press
unfamiliar_face

For these columns, the sidecar usually maps each category to its own HED annotation.

Example

{
  "event_type": {
    "Levels": {
      "show_face": "Face image is shown",
      "left_press": "Participant presses left button"
    },
    "HED": {
      "show_face": "Sensory-event, Visual-presentation, Experimental-stimulus, (Image, Face)",
      "left_press": "Agent-action, Press, Left-side, (Experiment-participant, Human-agent)"
    }
  }
}

B. Value columns

These contain row-specific values such as:

file names
IDs
reaction times
labels

For these, use a HED string with #.

Example

{
  "stim_file": {
    "Description": "Stimulus file name",
    "HED": "(Image, Pathname/#)"
  }
}

12. Definitions let you reuse complex concepts

HED allows reusable named concepts through Definition, Def, and Def-expand.

This is useful when the same complex concept appears many times.

Example concept definition

(Definition/Face-image, (Visual-presentation, Experimental-stimulus, (Image, Face)))

Later, you can refer to it using:

Def/Face-image

Why this helps

Definitions are useful for:

repeated event structures
trial structure
onset/offset pairs
cover stories or experimental contexts
keeping annotations readable

13. Common HED writing mistakes

Mistake	Example	Why it is a problem
Missing comma	`Sensory-event Visual-presentation`	Tags must be comma-separated
Unmatched parentheses	`(Image, Face`	Groups must be balanced
Empty group	`()`	Empty groups are invalid
Duplicate tag	`Red, Blue, Red`	Repeated expressions are invalid
Misused placeholder	`Label/#, Pathname/#` in one value string	Multiple placeholders in one value-column HED string are invalid
Placeholder in wrong place	`Label/ #`	Placeholder must follow the slash directly
Treating order as meaning	`Red, Square, Blue, Triangle`	Without grouping, associations are ambiguous

14. A practical checklist before saving an annotation

Before you validate your HED annotations, ask:

Are all tags separated by commas?
Are all parentheses balanced?
Did I group tags that belong together?
Did I avoid duplicates at the same level?
Did I use # only where a sidecar value should be inserted?
Did I choose standard tags instead of inventing my own?
Does the annotation describe the event in a way another lab could understand?

15. A minimal writing pattern for beginners

For many neuroscience and psychology events, this template works well:

Event-tag, presentation-or-action-tag, task-role-tag, (main-item, important-properties)

Example stimulus

Sensory-event, Visual-presentation, Experimental-stimulus, (Image, Face)

Example response

Agent-action, Press, Correct-action, (Experiment-participant, Human-agent)

This is not the only way to annotate, but it is a good practical starting pattern.

Key takeaway

Good HED annotation depends on two things:

choosing scientifically meaningful tags
writing them with correct syntax

For beginners, the most important syntax habits are:

use commas
use parentheses for association
keep groups balanced
avoid duplicates
use # correctly in sidecars

If those rules are followed, HED annotations become much easier to validate, search, and reuse.

Writing HED annotations correctly

Why syntax matters

1. A HED annotation is a comma-separated list of tags

2. HED strings are unordered at the same level

3. Parentheses show association

4. Parentheses must match and be properly nested

5. Do not create empty tags or empty groups

6. Do not repeat the same expression at the same level

7. Short-form and long-form tags

8. Use tag extensions only when truly necessary

9. Some tags require values

10. The # placeholder is for sidecars and definitions

11. Categorical columns and value columns are handled differently

A. Categorical columns

B. Value columns

12. Definitions let you reuse complex concepts

13. Common HED writing mistakes

14. A practical checklist before saving an annotation

15. A minimal writing pattern for beginners

Key takeaway

10. The `#` placeholder is for sidecars and definitions