A sidecar entry named `HED` for a column named `HED` halts validation with INTERNAL ERROR (bids-validator 1.15.0)

[ttm]

Describing an events.tsv column named HED is impossible: any sidecar entry named HED is treated as HED annotations and handed to the parser, which throws on prose. The result is INTERNAL ERROR. SOME VALIDATION STEPS MAY NOT HAVE OCCURRED rather than a reported issue.

This came out of building a generated HED profile for an ontology (SSTIM), so it is reproducible from a minimal dataset rather than from anything unusual in our data.

Environment

• bids-validator 1.15.0
• HED schema 8.4.0
• Minimal BIDS Behavioral dataset wrapping a single events.tsv + sidecar

Reproduction

events.tsv has a column literally named HED, carrying inline annotations, which is the BIDS convention. BIDS warns when a custom column has no sidecar description (CUSTOM_COLUMN_WITHOUT_DESCRIPTION), so we tried to describe it. Measured 2026-08-18, changing nothing but the sidecar:

Sidecar entry	Result
"HED": {"Description": "...", "Definitions": [...]}	INTERNAL ERROR. SOME VALIDATION STEPS MAY NOT HAVE OCCURRED
"HED": {"Definitions": [...]}	same internal error
"HED": {"Description": "..."}	same internal error
no HED entry; definitions under their own non-column key	0 errors, 1 warning: CUSTOM_COLUMN_WITHOUT_DESCRIPTION

The stack lands in BidsSidecar._filterHedStrings, which maps over the entry's values and hands each to the HED parser. Prose and a Definitions array are not HED strings, so it throws instead of reporting an issue.

What we did

We took the last row: definitions live in their own non-column entry (sstim_hed_definitions, with the definitions under its HED key), and there is no HED entry. All three of our bundles then validate with zero errors and one warning. We preferred a warning to an unvalidated dataset — an internal error is not a failed validation, it is no validation, and we would rather not publish artifacts whose validator stopped early.

Questions

1. Is a sidecar entry named HED simply not allowed when a column of that name exists? If so, the CUSTOM_COLUMN_WITHOUT_DESCRIPTION warning is expected and correct to ignore, and it would help to say so in the docs — the two conventions currently pull in opposite directions.
2. If it is allowed, this looks like a validator defect: prose reaching the HED parser should surface as an issue, not an uncaught throw that halts validation. Happy to open this against bids-standard/bids-validator instead if that is the right home.
3. Is the entry key for definitions arbitrary? We used sstim_hed_definitions; if the ecosystem expects a particular name we would rather match it.

Glad to supply the minimal dataset or a PR with a regression fixture if useful.

---

Context, if wanted: this is one of six questions written up while building an SSTIM → HED crosswalk — full write-up. The other five are schema-modelling questions and are filed separately against hed-standard/hed-schemas.

[happy5214]

The current version of bids-validator is 3.0.1, according to https://github.com/bids-standard/bids-validator. Please re-test with that version and let me know if you're still getting the original BIDS issue.

[ttm]

Thanks — re-tested on 3.0.1 and the original crash is gone. There is a quieter successor, though, which I think you will want.

Setup: deno run -A jsr:@bids/validator@3.0.1, deno 2.9.4, minimal beh dataset, BIDSVersion 1.10.0, HEDVersion 8.4.0, same events.tsv as before. (Worth noting for other reporters: npm's latest for bids-validator is still 1.15.0 with no 2.x/3.x published, which is how we ended up on the old line.)

The crash is fixed, and it answered my first question

The sidecar that used to produce INTERNAL ERROR. SOME VALIDATION STEPS MAY NOT HAVE OCCURRED now produces a proper, actionable error:

[ERROR] HED_ERROR
  IssueError: ERROR: [SIDECAR_INVALID] The string 'HED' or 'n/a' was illegally
  used as a top-level sidecar key. Sidecar key: "HED".

That settles question 1 above: a top-level HED key is not allowed, so the CUSTOM_COLUMN_WITHOUT_DESCRIPTION warning was expected and correct to ignore. And that warning no longer appears in 3.0.1 anyway. The layout we ship — no HED entry, definitions under their own non-column key — validates with 0 errors. Both of those are improvements over 1.15.0 from our side.

The new problem: the illegal key is only caught when something else triggers HED parsing

SIDECAR_INVALID fires only when the sidecar also contains another entry carrying an HED sub-key. When the top-level HED key is the only HED-bearing entry, it is silently ignored — and so is the HED column of events.tsv.

Same events.tsv throughout, changing only the sidecar:

Sidecar	Result
no top-level HED; definitions under sstim_hed_definitions (what we ship)	0 errors
↑ same, but with Totally-not-a-hed-tag injected into the HED column	HED_ERROR — correctly caught
top-level HED: {"Description": "..."} only	0 errors — illegal key not reported
top-level HED: {"Definitions": [...]} only	0 errors — illegal key not reported
top-level HED: {"Definitions": [...]} only, plus Totally-not-a-hed-tag in the HED column	0 errors — annotation never validated
top-level HED and a separate sstim_hed_definitions entry	SIDECAR_INVALID — correctly reported

Rows 1–2 are the control: HED validation is demonstrably live in this dataset, and catches a bogus tag. Row 5 is the same bogus tag under a lone top-level HED key, and it passes.

So the failure mode is the same class as the one I originally reported — not a failed validation but no validation — except it now presents as a clean pass rather than an internal error, which is harder to notice. Anyone who writes the intuitive-but-illegal "HED": {"Description": ...} gets a green result and an unvalidated events file.

Two things that would fix it, as far as I can see: report SIDECAR_INVALID for a top-level HED key whenever it appears, independent of the other entries; and treat "sidecar contained an illegal HED key" as a reason to fail rather than to skip the column.

Happy to attach the six probe datasets or open a PR with them as regression fixtures — they are tiny and differ only in the sidecar. Let me know which you would prefer.

[happy5214]

Please attach them. I would like to see which repo this issue actually belongs to (as a lot of what you're describing sound like it should be bids-validator's domain).

Edit: Also, bids-validator, being a Deno package since v2.0.0, is now published on JSR.

[VisLab]

You cannot use "HED" as a top-level key (representing a column name). The purpose of the "HED" column is to encode things that are speciic to that row in the events file. It can be use as {HED} in other annotations and the individual annotations for each row will be inserted when the annotation for that row is assembled.

[happy5214]

If I'm reading row 5 correctly, in that case it's not returning an error for either the illegal HED column/top-level key in the sidecar or the invalid HED data in the HED column. That would be an actual bug if true. (It should probably prefer the first error and immediately stop with that.)

[ttm]

@happy5214 your reading of row 5 is right (neither error is reported), and your #442 fixes it. I rebuilt all six probes from scratch and tested against your branch rather than taking yesterday's run on trust.

bids-validator at af530c2 (parent of your commit) vs 85dbb87 (#442 head), same six datasets, deno 2.9.4, HED 8.4.0, BIDSVersion 1.10.0. events.tsv is identical throughout; only the sidecar differs:

Probe (sidecar)	af530c2	#442
1. no top-level HED; definitions under sstim_hed_definitions (what we ship)	0 errors	0 errors
2. ↑ plus Totally-not-a-hed-tag in the HED column	TAG_INVALID	TAG_INVALID
3. top-level HED: {"Description": …} only	0 errors	SIDECAR_INVALID
4. top-level HED: {"Definitions": […]} only	0 errors	SIDECAR_INVALID
5. ↑ plus Totally-not-a-hed-tag in the HED column	0 errors	SIDECAR_INVALID
6. top-level HED plus a separate sstim_hed_definitions entry	SIDECAR_INVALID	SIDECAR_INVALID

One line, context.columns.has('HED') for 'HED' in context.columns, closes all three silent rows. Row 5 reports only the sidecar error and not the bad tag, which is the "prefer the first error and stop" behaviour you described. Probe 1, the layout we ship, stays at 0 errors, so the legal arrangement doesn't regress.

Which repo, then: yours. The skipped validation is bids-validator's and #442 is the fix. The only residue I can see on the hed-javascript side is cosmetic: probe 6's SIDECAR_INVALID surfaces as HED_ERROR → INTERNAL_ERROR wrapping an IssueError, rather than as a first-class issue. Happy to file that separately if it is worth having, or to let it go if it is by design.

@VisLab: thank you, that settles the convention question. With #442 the illegal key is reported in every configuration, so nobody reaches it silently.

The probes. Six directories differing only in the sidecar, so a generator seemed more reviewable than an attachment: this writes all six, and each is then deno run -A jsr:@bids/validator@3.0.1 probe-N. If you would rather have them as regression fixtures, say so and I will open a PR against #442 adding them.

make-probes.py

#!/usr/bin/env python3
"""Build the six minimal BIDS datasets from hed-standard/hed-javascript#836."""

import json
import pathlib
import sys

OUT = pathlib.Path(sys.argv[1] if len(sys.argv) > 1 else "probes")

DATASET_DESCRIPTION = {
    "Name": "SSTIM HED sidecar probe",
    "BIDSVersion": "1.10.0",
    "DatasetType": "raw",
    "HEDVersion": "8.4.0",
}

EVENTS_HEADER = "onset\tduration\tevent_id\tevent_type\tHED"
EVENTS_ROWS = [
    "0.000\tn/a\tevent-open\teventSessionOpen\t(Def/Sstim-session, Onset)",
    "0.300\tn/a\tevent-start\teventPlaybackStart\t(Def/Sstim-delivery, Onset)",
    "190.000\tn/a\tevent-pause\teventPlaybackPause\t(Def/Sstim-delivery, Pause)",
]
# Probes 2 and 5 replace the first annotation with a tag that is not in the
# schema, to prove whether the HED column is being validated at all.
BOGUS_ROWS = ["0.000\tn/a\tevent-open\teventSessionOpen\tTotally-not-a-hed-tag"] + EVENTS_ROWS[1:]

DEFINITIONS = {
    "Sstim-session": "(Definition/Sstim-session, (Experiment-structure, Time-block))",
    "Sstim-delivery": "(Definition/Sstim-delivery, (Sensory-event, Experimental-stimulus, Sensory-presentation))",
}

COMMON_COLUMNS = {
    "onset": {"Description": "Seconds from the session clock origin.", "Units": "s"},
    "event_id": {"Description": "Local name of the source session event."},
    "event_type": {"Description": "SSTIM session event type."},
}

LEGAL_DEFINITIONS_ENTRY = {
    "sstim_hed_definitions": {
        "Description": "HED definitions the HED column references. Not a column of events.tsv.",
        "HED": DEFINITIONS,
    }
}

TOP_LEVEL_HED_DESCRIPTION = {"HED": {"Description": "Inline HED annotations for this row."}}
TOP_LEVEL_HED_DEFINITIONS = {"HED": {"Definitions": list(DEFINITIONS.values())}}

PROBES = [
    ("probe-1-shipped-layout", {**COMMON_COLUMNS, **LEGAL_DEFINITIONS_ENTRY}, EVENTS_ROWS,
     "no top-level HED; definitions under sstim_hed_definitions (what we ship)"),
    ("probe-2-shipped-layout-bogus-tag", {**COMMON_COLUMNS, **LEGAL_DEFINITIONS_ENTRY}, BOGUS_ROWS,
     "same, but with Totally-not-a-hed-tag in the HED column"),
    ("probe-3-toplevel-hed-description", {**COMMON_COLUMNS, **TOP_LEVEL_HED_DESCRIPTION}, EVENTS_ROWS,
     "top-level HED: {Description} only"),
    ("probe-4-toplevel-hed-definitions", {**COMMON_COLUMNS, **TOP_LEVEL_HED_DEFINITIONS}, EVENTS_ROWS,
     "top-level HED: {Definitions} only"),
    ("probe-5-toplevel-hed-definitions-bogus-tag", {**COMMON_COLUMNS, **TOP_LEVEL_HED_DEFINITIONS}, BOGUS_ROWS,
     "top-level HED: {Definitions} only, plus Totally-not-a-hed-tag in the HED column"),
    ("probe-6-toplevel-hed-plus-legal-entry",
     {**COMMON_COLUMNS, **TOP_LEVEL_HED_DEFINITIONS, **LEGAL_DEFINITIONS_ENTRY}, EVENTS_ROWS,
     "top-level HED and a separate sstim_hed_definitions entry"),
]


def write(path, payload):
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(payload if isinstance(payload, str) else json.dumps(payload, indent=2) + "\n")


for name, sidecar, rows, description in PROBES:
    root = OUT / name
    write(root / "dataset_description.json", {**DATASET_DESCRIPTION, "Name": f"{name}: {description}"})
    beh = root / "sub-01" / "beh"
    write(beh / "sub-01_task-sstim_events.tsv", "\n".join([EVENTS_HEADER, *rows]) + "\n")
    write(beh / "sub-01_task-sstim_events.json", sidecar)
    print(f"{name}: {description}")

[VisLab]

@ttm There are two resources that may make development easier. We recommend that users validate the HED in their BIDS datasets first before applying the BIDS validator. This separates out the annotation issues from the format rules of BIDS. There is a fully browser-based HED validator that always uses the latest released version of HED Javascript to validate a BIDS dataset, a BIDS sidecar, a HED string, or a .tsv file with or without sidecar: https://www.hedtags.org/hed-web/.

Another resources is https://hedtools.org/hed or https://hedtools.org/hed_dev which offer a number of HED online tools including validation based on the Python hedtools package. Both the JavaScript and the Python based validators execute the same extensive validation test set. Our goal is to keep them in sync as much as possible.

[happy5214]

@ttm The PR to bids-validator has been merged. Please test with the development version.

[ttm]

@happy5214 tested on merged main, 4b83dc9 (3.0.1-9-g4b83dc9), deno 2.9.4, HED
8.4.0. All six probes rebuilt from scratch and run against the 3.0.1 release for
contrast. events.tsv is identical throughout; only the sidecar differs.

Probe (sidecar)	3.0.1	main 4b83dc9
1. no top-level HED; definitions under sstim_hed_definitions (what we ship)	0 errors	0 errors
2. ↑ plus Totally-not-a-hed-tag in the HED column	TAG_INVALID	TAG_INVALID
3. top-level HED: {"Description": …} only	0 errors	SIDECAR_INVALID
4. top-level HED: {"Definitions": […]} only	0 errors	SIDECAR_INVALID
5. ↑ plus the bogus tag in the HED column	0 errors	SIDECAR_INVALID
6. top-level HED plus a separate sstim_hed_definitions entry	SIDECAR_INVALID	SIDECAR_INVALID

All three silent rows now report, and the legal layout does not regress. Our two
real bundles (the shipped fixture and the revised pair from the HED meeting) also
validate at 0 errors on main. Thanks for the fix.

The only residue is on this side, and the fix makes it more visible: SIDECAR_INVALID
arrives as HED_ERROR with subCode: INTERNAL_ERROR, and its issueMessage is an
object ({"issue": {…}, "name": "IssueError"}) where every other issue carries a
string, so a JSON consumer reading it as text breaks on exactly this case. That is
now the presentation of the commonest illegal-key mistake. Separate issue here, or
by design?