Schema developer guide

HED (Hierarchical Event Descriptors) is a standardized vocabulary and annotation framework that allows researchers to systematically describe what happened during an experiment. A HED schema is a hierarchically-structured vocabulary specification. The standard schema contains basic vocabulary for annotation across all domains, while library schemas provide specialized vocabularies for specific research areas. This guide describes how to develop your own HED library schema or contribute to existing HED vocabularies.

Getting started

  1. Get a basic understanding of HED by reading Introduction to HED. This 5-minute introduction gives you an overview.

  2. Explore schema building workflow by reading As a schema builder from How can you use HED?.

  3. Explore existing schemas using the HED schema browser or see a summary by looking at the HED schemas overview

  4. Post an issue describing your proposed changes or new schema on GitHub issues

  5. Discuss with the HED Working Group at hed.maintainers@gmail.com

  6. Choose a schema name (short, informative, alphabetic string)

  7. Understand the structure by reading this guide

Schema design principles

All HED schemas must conform to these design principles:

1. Organized hierarchy

  • Top-level tags represent major categories

  • Ideally each subtree should have no more than 7 direct children (for human readability)

  • The hierarchy should be easily understood

2. Is-a relationship

Every term must satisfy the is-a relationship with its ancestors. For example:

  • Clap-hands is-a Communicate-gesturally

  • Communicate-gesturally is-a Communicate

  • Communicate is-a Action

This enables search generalization: searching for Communicate returns all descendant tags.

3. Orthogonal design

Independent concepts should be in different subtrees. For example:

  • Left-handed is NOT a type of Human

  • Left-handed IS a type of Property (it doesn’t define humans)

Properties and categories must not be conflated.

4. Unique terms

  • Each tag must be unique within the schema

  • Tags MUST be distinct from standard schema tags

  • Avoid overlap with other library schemas when possible

5. Meaningful names

  • Tags should be clear without context

  • Use standard terminology when available

  • Follow naming conventions (see below)

6. Standard schema partnership

All library schemas should be partnered with the latest standard schema.

  • Specify the withStandard version in the library schema header

  • Use {rooted=ParentTag} attribute to integrate library terms under standard schema nodes

  • Add top-level tags (corresponding to separate subtrees) only when required

  • Do not use the inLibrary attribute – this is attribute is only added by tools when schema is merged with standard

7. Development format

The four HED schema formats: XML, MEDIAWIKI, TSV, and JSON correspond to file types: .xml, .mediawiki, .tsv, and .json, respectively. The formats are completely equivalent, and any one format can be generated from another other format. However, schema developers should ONLY develop in the MEDIAWIKI or TSV formats:

  • MEDIAWIKI format (.mediawiki files) - Human-readable text format in a single file – easiest format for visualizing the hierarchical structure

  • TSV format (.tsv files) - Spreadsheet-compatible format with separate files for tags, units, etc. Users usually only edit the _Tag.tsv file – easiest format for including lots of attributes and links to other resources

  • XML/JSON formats - Generated automatically by CI/CD, never edit directly

When to use MEDIAWIKI format:

  • Creating new schemas with simple hierarchy

  • Visualizing and understanding tag relationships

  • Making structural changes to the hierarchy

  • When most tags have few attributes

When to use TSV format:

  • Adding many attributes to existing tags

  • Including extensive ontology mappings

  • Working with spreadsheet tools for batch updates

  • When collaborating with non-technical domain experts who prefer spreadsheets

Only edit in one format at a time

In a given Pull Request, you should only edit the schema in a single format (either MEDIAWIKI or TSV, not both). Editing in multiple formats simultaneously can lead to merge conflicts and inconsistencies during the automated conversion process.

Naming conventions

  • First character capitalized (if letter)

  • Remaining characters lowercase (except SI units)

  • Multiple words hyphenated (e.g., Clap-hands)

  • Only alphanumeric, hyphens, and underscores allowed for tag names

  • No blanks

For examples of these conventions in practice, see MEDIAWIKI schema structure and TSV schema structure. All of the formats are available on GitHub.

Proposing a new library schema

To propose a new library schema:

  1. Post an issue on the hed-schemas GitHub repository:

    • Describe the domain your schema will cover

    • Explain the need for this specialized vocabulary

    • Provide examples of terms or concepts you plan to include

  2. Discuss with the HED Working Group:

  3. Choose a schema name:

    • Short, informative, alphabetic string (e.g., lang, score, slam)

    • Name should clearly indicate the domain

  4. Write schema documentation:

    • Prolog: Brief description of the schema’s purpose and scope (appears in schema header)

    • Epilog: Additional information – often acknowledgements (appears in the schema footer)

  5. Maintainers create the schema structure:

    • Create directory library_schemas/<name>/

    • Set up prerelease/ directory with empty templates

    • Fill in schema headers with metadata:

      • Version number (start at 1.0.0)

      • Library name

      • HedId range (assigned in library_data.json)

      • Compatible standard schema version (withStandard)

      • Prologue and epilogue text

    • Create initial documentation files (README.md, LICENSE, CONTRIBUTORS.md)

  6. Begin development:

    • Fork the repository and follow the development workflow below

    • Add your schema terms to the prerelease templates

Development workflow

Branch naming conventions

Branch names determine which schema can be modified:

Branch prefix

Allowed modifications

standard_*

Only standard_schema/: (docs, /prerelease)

score_*

Only library_schemas/score/: (docs, prerelease)

lang_*

Only library_schemas/lang/: (docs, prerelease)

slam_*

Only library_schemas/slam/: (docs, prerelease)

mouse_*

Only library_schemas/mouse/: (docs, prerelease)

admin_*

Any files: (docs, scripts, CI/CD) - maintainers only

CI/CD will reject pushes that violate these conventions. These rules are in place to allow schemas to be housed in a single repository, while keeping development efforts for individual schemas separate. ONLY MAINTAINERS can do releases and move schemas from prerelease to the other directories.

Development process

Critical workflow rules

  1. ALL changes go to prerelease/ subdirectory

  2. Edit ONLY the .mediawiki file OR ONLY the .tsv files during one PR (GitHub pull request)

  3. Let CI/CD pipeline convert to other formats

  4. Never edit released schemas

  5. NEVER assign or change hedId values. These are assigned system-wide programmatically.

The actual official release of a new version of a HED schema is a multistage process.

Development workflow overview

┌──────────────────────────────────────────────────────────┐
│  SETUP (done once)                                       │
│  1. Fork repository                                      │
│  2. Clone to local                                       │
│  3. Create branch with correct prefix                    │
└───────────────────────────┬──────────────────────────────┘
                            ▼
┌──────────────────────────────────────────────────────────┐
│  DEVELOP PROCESS (iterate until approved)                │
│                                                          │
│  ┌────────────────────────────────────────────────────┐  │
│  │  EDIT CYCLE (repeat until valid)                   │  │
│  │  • Edit prerelease file (.mediawiki/.tsv)          │  │
│  │  • Document changes (PRERELEASE_CHANGES)           │  │
│  │  • Validate locally (HED online tools)             │  │
│  └────────────────────────┬───────────────────────────┘  │
│                           ▼                              │
│  ┌────────────────────────────────────────────────────┐  │
│  │  REVIEW CYCLE                                      │  │
│  │  • Push to fork & create pull request              │  │
│  │  • CI/CD validates automatically                   │  │
│  │  • Community review & feedback                     │  │
│  │  • Working Group feedback                          │  │
│  │                                                    │  │
│  │  If changes needed → return to EDIT CYCLE          │  │
│  └────────────────────────┬───────────────────────────┘  │
│                           ▼                              │
│  ┌────────────────────────────────────────────────────┐  │
│  │  UPDATE PRERELEASE                                 │  │
│  │  • Maintainer merges PR                            │  │
│  │  • Changes only affect prerelease/ dir             │  │
│  └────────────────────────────────────────────────────┘  │
└───────────────────────────┬──────────────────────────────┘
                            ▼
┌──────────────────────────────────────────────────────────┐
│  RELEASE (Working Group approval required)               │
│  • Working Group approves release                        │
│  • Maintainer moves files from prerelease                │
│  • Maintainer tags version in git                        │
│  • Maintainer publishes DOI via Zenodo                   │
└──────────────────────────────────────────────────────────┘

Step-by-step workflow

  1. Fork the repository on GitHub:

    • Go to the hed-schemas GitHub repository

    • Click the “Fork” button to create your own copy

  2. Clone your fork locally:

    git clone https://github.com/YOUR-USERNAME/hed-schemas.git
cd hed-schemas

  3. Create a branch with appropriate prefix:

    git checkout -b xxx_add_new_term

    where xxx is standard or the library name depending on which schema you want to change. The xxx value admin is reserved mainly for maintainers and should not be used by individual schema developers.

  4. Edit the prerelease MEDIAWIKI file (alternatively the xxx_Tag.tsv file):

    • For standard schema: standard_schema/prerelease/HEDX.Y.Z.mediawiki

    • For library schema: library_schemas/<name>/prerelease/HED_<name>_X.Y.Z.mediawiki

  5. Document your changes in prerelease/PRERELEASE_CHANGES.md:

    ## Version 8.5.0

### Added
- New tag `Action/Communicate/Wave-hand` for waving gestures

### Modified
- Updated description of `Clap-hands` for clarity

  6. Validate and test conversion using HED online tools:

    • Go to hedtools.org/hed/schemas

    • Use the Validate tool to check your modified schema file for errors

    • Use the Convert tool to ensure your schema can be converted to other formats without errors

    • If validation or conversion errors occur, fix them in your schema file and repeat until successful

    • This step helps catch issues before creating a pull request

  7. Commit and push to your fork:

    git pull origin main
git add .
git commit -m "Add Wave-hand action tag"
git push origin standard_add_new_term

    Be sure the main branch of your fork is up-to-date with the current version to avoid conflicts.

  8. Create pull request to the main repository:

    • Go to your fork on GitHub

    • Click “Pull Request” to create a PR targeting the main branch

    • Provide a clear description of your changes

  9. CI/CD pipeline automatically runs on your PR:

    • Converts the format you have changed to other formats (e.g., MEDIAWIKI → XML, JSON, TSV)

    • Validates all schema files

    • Commits generated files back to your PR branch

    • Note: HED IDs are NOT assigned during prerelease development – they are only assigned when the schema is officially released (handled by maintainers during the release process)

    If CI/CD pipeline validation fails:

    • Review the error messages in the GitHub Actions log

    • Common errors (should be found before PR using the online tools):

      • Schema syntax errors (missing brackets, mismatched tags)

      • Invalid attribute values

      • Undefined parent tags in TSV omn:SubClassOf

      • Duplicate term names

    • Fix errors in your prerelease file and push again

    • CI/CD will re-run automatically on each push

  10. Review and merge:

  • Maintainers review your changes

  • Address any feedback or requested changes

  • Once approved, maintainers will merge your PR (contributors cannot merge their own PRs)

  1. Check your release:

  • View your schema in the HED schema browser using the View prerelease schema button on the viewer

  • Check both with and without showing the partnered schema by toggling the *Show/hide merged library button in the viewer

  • If any problems, correct and repeat from Step 4

Developing a schema

Detailed information about the various HED schema formats is available Appendix A: Schema format details of the HED specification.

MEDIAWIKI schema structure

The MEDIAWIKI format is a single file that contains many sections needed to completely reconstruct the schema. However, schema developers will mainly be concerned with the specification of the HED tags, which is the portion of the file between !# start schema and !# end schema. Each tag specification must be on a single line.

An excerpt from HED8.4.0.mediawiki

'''Action''' <nowiki>{extensionAllowed, hedId=HED_0012016} [Do something.]</nowiki>
* Communicate <nowiki>{hedId=HED_0012017} [Action conveying knowledge of or about something.]</nowiki>
** Communicate-gesturally <nowiki>{relatedTag=Move-face, relatedTag=Move-upper-extremity, hedId=HED_0012018} [Communicate non-verbally using visible bodily actions, either in place of speech or together and in parallel with spoken words. Gestures include movement of the hands, face, or other parts of the body.]</nowiki>
*** Clap-hands <nowiki>{hedId=HED_0012019} [Strike the palms of against one another resoundingly, and usually repeatedly, especially to express approval.]</nowiki>

Key elements:

  • '''Action''' - The triple single quotes indicate a root tag (no ancestors)

  • The asterisks (*) indicate hierarchy level (more asterisks = deeper in the hierarchy)

  • Hierarchy is determined by the number of asterisks:

    • Tags with *** (3 asterisks) are children of the nearest preceding tag with ** (2 asterisks)

    • Tags with ** are children of the nearest preceding tag with * (1 asterisk)

    • Tags with * are children of the nearest preceding root tag ('''TagName''')

  • The <nowiki>...</nowiki> is MEDIAWIKI markup that preserves the content literally – this markup should enclose everything after the tag name

  • The description appears in square brackets: [...description...]

  • Attributes appear in {} if needed: {relatedTag=Move-face}

Modifying an entry usually involves changing the attributes or the description. Moving the line or changing the number of asterisks (*) changes the structure of the hierarchy and should be done with care unless this library schema has never been released.

Important: Tag deletion is not allowed

Once a schema has had its initial release, tags cannot be deleted. Use the deprecatedFrom schema attribute to designate that the tag should not be used in future annotations. In this case the notes in the description should include advice about what should be used instead.

Adding a tag to a MEDIAWIKI file involves added an additional line in the file.

Adding the Beckon term to MEDIAWIKI

'''Action''' <nowiki>{extensionAllowed, hedId=HED_0012016} [Do something.]</nowiki>
* Communicate <nowiki>{hedId=HED_0012017} [Action conveying knowledge of or about something.]</nowiki>
** Communicate-gesturally <nowiki>{relatedTag=Move-face, relatedTag=Move-upper-extremity, hedId=HED_0012018} [Communicate non-verbally using visible bodily actions, either in place of speech or together and in parallel with spoken words. Gestures include movement of the hands, face, or other parts of the body.]</nowiki>
*** Beckon <nowiki>[Signal or summon someone with a gesture, typically by moving the hand or head.]</nowiki>
*** Clap-hands <nowiki>{hedId=HED_0012019} [Strike the palms of against one another resoundingly, and usually repeatedly, especially to express approval.]</nowiki>

In this example:

  • Beckon is added at the same level as Clap-hands (both have leading ***)

  • Beckon becomes a child of Communicate-gesturally (the nearest previous line with fewer asterisks)

  • The description is enclosed in square brackets within <nowiki> </nowiki> tags

  • Note that Beckon does not have a hedId yet since it’s in prerelease - hedId values are assigned only at release time

  • By convention, we keep the sibling tags of a parent tag in alphabetical order, so we put Beckon before Clap-hands, although it makes no difference in the internal representation.

TSV schema structure

Each version of a schema in TSV format is stored in its own directory, and information about the schema is stored in multiple files. The schema developer will mainly be concerned with the file ending in _Tag.tsv. All of the files are tabular (tab-separated-value) files, which can be easily imported into Excel and other tools.

An excerpt from HED8.4.0_Tag.tsv

hedId

Level

rdfs:label

omn:SubClassOf

Attributes

dc:description

HED_0012016

0

Action

HedTag

extensionAllowed

Do something.

HED_0012017

1

Communicate

Action

Action conveying knowledge of or about something.

HED_0012018

2

Communicate-gesturally

Communicate

relatedTag=Move-face, relatedTag=Move-upper-extremity

Communicate non-verbally using visible bodily actions, either in place of speech or together and in parallel with spoken words. Gestures include movement of the hands, face, or other parts of the body.

HED_0012019

3

Clap-hands

Communicate-gesturally

Strike the palms of against one another resoundingly, and usually repeatedly, especially to express approval.

Key elements:

  • hedId: Unique identifier for each term (empty for prerelease terms)

  • Level: Hierarchy depth (0 = root, 1 = child of root, etc.)

  • rdfs:label: The tag name

  • omn:SubClassOf: The parent tag name, or HedTag for root-level tags (tags with no parent)

  • Attributes: Comma-separated list of schema attributes

  • dc:description: The tag description

Adding a tag to the TSV format involves adding a line to the _Tag.tsv spreadsheet.

Adding the tag

hedId

Level

rdfs:label

omn:SubClassOf

Attributes

dc:description

HED_0012016

0

Action

HedTag

extensionAllowed

Do something.

HED_0012017

1

Communicate

Action

Action conveying knowledge of or about something.

HED_0012018

2

Communicate-gesturally

Communicate

relatedTag=Move-face, relatedTag=Move-upper-extremity

Communicate non-verbally using visible bodily actions, either in place of speech or together and in parallel with spoken words. Gestures include movement of the hands, face, or other parts of the body.

HED_0012019

3

Clap-hands

Communicate-gesturally

Strike the palms of against one another resoundingly, and usually repeatedly, especially to express approval.

3

Beckon

Communicate-gesturally

Signal or summon someone with a gesture, typically by moving the hand or head.

In this example:

  • Beckon is added with Level=3 (same as Clap-hands)

  • omn:SubClassOf=Communicate-gesturally specifies the parent

  • hedId is empty (left blank) for prerelease terms - HedIds are assigned only at release time

  • The row is at the end of the file (for convenience) – the hierarchy is determined by `omn:SubClassOf

  • Attributes column is empty (or contains comma-separated attributes if needed)

The TSV format is easier than MEDIAWIKI format for adding large numbers of attributes and checking descriptions, but it is more difficult to check the hierarchy (you must trace parent-child relationships through the omn:SubClassOf column instead of visually seeing indentation levels).

Adding attributes

HED schema attributes modify tag behavior and provide additional metadata (see Schema design principles for design guidance). Attributes can be:

  • Boolean: Set by name only to indicate presence or absence (e.g., requireChild, topLevelTagGroup)

  • Value attributes: Require a string or numeric value (e.g., suggestedTag=Task-property, hedId=HED_0012808). When multiple values of the same attribute are needed, repeat the attribute name with each value as comma-separated name-value pairs (e.g., suggestedTag=Tag1,suggestedTag=Tag2).

The Definition tag has both boolean and value attributes

MEDIAWIKI format:

** Definition <nowiki>{requireChild, reserved, topLevelTagGroup, hedId=HED_0012808} [A HED-specific utility tag whose child value is the name of the concept and the tag group associated with the tag is an English language explanation of a concept.]</nowiki>

TSV format:

hedId

Level

rdfs:label

omn:SubClassOf

Attributes

dc:description

HED_0012808

2

Definition

Organizational-property

requireChild, reserved, topLevelTagGroup

A HED-specific utility tag whose child value is the name of the concept and the tag group associated with the tag is an English language explanation of a concept.

The Definition tag has the boolean attributes requireChild, reserved, topLevelTagGroup and the value attribute hedId

Important notes about hedId:

  • In MEDIAWIKI format: hedId appears in the attributes list within {}

  • In TSV format: hedId has its own dedicated column and does NOT appear in the Attributes column

  • During prerelease development, leave hedId empty for new tags - it is assigned automatically during official release

  • Once assigned, hedId values become permanent identifiers and must never be changed or reused

Some attributes have special requirements. For example the suggestedTag and the relatedTag are schema value attributes whose values must be tags that are also in the schema.

Using multiple suggestedTag attributes

MEDIAWIKI format:

'''Posterior-dominant-rhythm''' <nowiki>{suggestedTag=Feature-frequency,suggestedTag=Occipital-lobe} [Rhythmic activity occurring during wakefulness.]</nowiki>

TSV format:

hedId

Level

rdfs:label

omn:SubClassOf

Attributes

dc:description

HED_0042046

1

Posterior-dominant-rhythm

Background-activity

suggestedTag=Feature-frequency,suggestedTag=Occipital-lobe

Rhythmic activity occurring during wakefulness.

Note, the Posterior-dominant-rhythm is a tag from the SCORE library schema as is Feature-frequency. The Occipital-lobe is a tag from the HED standard schema that this version of the SCORE library is partnered with.

All schema attributes must be defined in the Schema attributes section (for MEDIAWIKI) or split among the _AnnotationProperty.tsv, _DataProperty.tsv, and _ObjectProperty.tsv files (for TSV). For library schema developers, these files should usually only have headers, since these are defined in the standard schema that this schema is partnered with. The attributes are in separate .tsv files for easier mapping with ontologies using the OWL format. See the HED ontology chapter of the HED specification for more information on HED’s equivalence to a formal ontology.

Partnering with standard schema

Library schemas are usually partnered with a standard schema. When you specify a library schema (e.g., score_2.2.0), the information from that schema is automatically merged with its standard schema partner to form a single schema. A given version of a library schema is partnered with a specific version of the schema, as specified in the schema header.

Specifying the partner

The header for partnered library schema lang_1.1.0

MEDIAWIKI format:

!# Version="1.1.0" withStandard="8.4.0" library="lang"

Note: The header information for TSV is contained in the _Structure.tsv file and is generally setup by the HED maintainers when the directory for that library schema is created in hed-schemas.

Rooting a term

To root a library subtree under a standard schema node, use the rooted attribute:

Rooting Linguistic-item of lang_1.1.0 under Item

'''Linguistic-item''' <nowiki>[Language-related entity.] {rooted=Item}</nowiki>

This places the entire Linguistic-item subtree under the standard schema’s Item tag in the merged schema. The rooted attribute is useful when your library schema tags logically belong under an existing standard schema category. Without rooted, library schema root tags appear at the top level of the merged schema.

When to use rooted:

  • Your library terms are specializations of standard schema concepts

  • You want library terms integrated into the standard hierarchy

  • Users should see library terms as extensions of standard categories

When NOT to use rooted:

  • Your library defines completely new top-level categories

  • Your domain is orthogonal to standard schema organization

Release process

The official release of a new schema version is performed by HED maintainers. This process involves:

  1. Final review and approval by the HED Working Group

  2. Moving files from prerelease/ to release directories

  3. Assigning permanent hedId values

  4. Tagging the release in GitHub and publishing to Zenodo

Developers do not need to perform these steps. Once your changes are merged into the prerelease directory and approved for release, the maintainers will handle the rest.

Common pitfalls

❌ Don’t do this

  1. Don’t edit released schemas

    • Only edit files in prerelease/ directories

  2. Don’t edit XML/JSON directly

    • Always edit EITHER MEDIAWIKI OR TSV and let CI convert

  3. Don’t use wrong branch prefix

    • Branch name must match the schema you’re modifying

  4. Don’t reuse HedIds

    • HedIds are permanent identifiers, never reuse or assign yourself

  5. Don’t forget to document changes

    • Update PRERELEASE_CHANGES.md for every change

  6. Don’t violate is-a relationship

    • Every child must be a type of its parent

  7. Don’t mix properties with categories

    • Left-handed is not a type of Human

  8. Don’t create duplicate terms

    • Check existing schemas before adding

  9. Don’t skip version increment rules

    • Understand major/minor/patch implications

✅ Do this instead

  1. ✅ Edit in prerelease/ subdirectories

  2. ✅ Edit only .mediawiki files or .tsv files

  3. ✅ Use correct branch prefix (standard_*, score_*, etc.)

  4. ✅ Let CI auto-assign HedIds

  5. ✅ Document all changes in PRERELEASE_CHANGES.md

  6. ✅ Maintain strict is-a hierarchy

  7. ✅ Keep properties orthogonal to categories

  8. ✅ Search existing schemas thoroughly

  9. ✅ Follow semantic versioning strictly

Each generation of change log

You can easily generate your CHANGELOG.md entry using the Schema compare action of the HED online schema tools. You can compare your current version with the previously released version or if this is the first release, with the initial setup. The tool produces a nice CHANGELOG in Markdown for you to use.

CI/CD pipeline

GitHub Actions automatically:

Workflow

Purpose

validate_schemas.yaml

Validates all changed schema files

update_and_convert_schemas.yaml

Converts changed file(s) to other format

add_hed_ids.yaml

Assigns HedIds to new terms (if during release)

verify_source_branch.yaml

Ensures changes on correct branch and in prerelease/

codespell.yaml

Checks spelling

mdformat.yaml

Checks Markdown formatting

links.yaml

Checks for broken links

Contributing to documentation

This section explains how to build and contribute to the HED schemas documentation.

Prerequisites

  • Python 3.10 or higher

  • Git

Setting up documentation environment

  1. Clone the repository (if not already done):

    git clone https://github.com/hed-standard/hed-schemas.git
cd hed-schemas

Building documentation locally

Initial setup (one-time)

  1. Create a virtual environment (if not already done):

    Windows:

    python -m venv .venv
.venv\Scripts\Activate.ps1

    Unix/Mac:

    python -m venv .venv
source .venv/bin/activate

  2. Install documentation dependencies:

    pip install .[docs]

Building with Sphinx

From the repository root, use sphinx-build to build the documentation:

Windows:

sphinx-build -b html docs/ docs/_build/html

Unix/Mac:

sphinx-build -b html docs/ docs/_build/html

The built documentation will be in docs/_build/html/.

Viewing documentation locally

After building, you can serve the documentation with Python’s built-in HTTP server:

Windows:

cd docs\_build\html
python -m http.server 8000

Unix/Mac:

cd docs/_build/html
python -m http.server 8000

Then open your browser to http://localhost:8000.

Press Ctrl+C to stop the server.

Alternative: You can also open docs/_build/html/index.html directly in your web browser.

Making changes to documentation

Documentation structure

The documentation source files are in docs/:

File

Purpose

index.rst

Main documentation index

schemas_overview .md

Overview of HED schemas

developer_guide.md

Guide for schema development

api.rst

Repository structure reference

conf.py

Sphinx configuration

Workflow for documentation changes

  1. Create a branch:

    git checkout -b admin_update_docs

  2. Edit documentation files in docs/

    • Use Markdown (.md) for content pages

    • Use reStructuredText (.rst) for structural files

  3. Build and preview:

    # Build
sphinx-build -b html docs/ docs/_build/html

# Serve
cd docs/_build/html
python -m http.server 8000

  4. Review your changes in the browser at http://localhost:8000

  5. Rebuild as needed - The build is fast, so rebuild frequently to check your changes

  6. Commit and push:

    git add docs/
git commit -m "Update documentation"
git push origin admin_update_docs

  7. Create a pull request on GitHub

Documentation style guide

Markdown guidelines

  • Use # for top-level headings, ## for sections, ### for subsections

  • Use code blocks with language specification: python```, bash```, etc.

  • Use bold for emphasis on key terms

  • Use inline code for commands, file names, and code snippets

  • Use bullet lists for unordered items

  • Use numbered lists for sequential steps

Code examples

Always specify the language for code blocks:

````python
from hed import schema
schema = schema.load_schema('8.4.0')
````

For bash/shell commands:

````bash
pip install .[dev]
````

Common documentation tasks

Adding a new page

  1. Create a new .md file in docs/

  2. Add it to the toctree in index.rst:

    .. toctree::
   :maxdepth: 2
   :caption: Contents:

   HED schemas overview <schemas_overview>
   Schema developer guide <developer_guide>
   your_new_page
   ...

  3. Build and verify it appears in the navigation

Updating schema information

When a new schema version is released:

  1. Update version numbers in schemas_overview.md

  2. Add new links for the new version

  3. Check that all DOI links are correct

Adding images

  1. Place images in docs/_static/images/

  2. Reference in Markdown:

    ![Alt text](_static/images/your-image.png)

Troubleshooting documentation builds

Build errors

Problem: Module not found errors

ModuleNotFoundError: No module named 'myst_parser'

Solution: Reinstall dependencies

pip install .[docs]

Warnings

Sphinx may show warnings about:

  • Missing references

  • Duplicate labels

  • Malformed links

Fix these warnings before committing - they indicate potential broken links or incorrect formatting.

Port already in use

Problem: Address already in use when running http.server

Solution: Use a different port

python -m http.server 8001

Or find and stop the process using port 8000.

CI/CD for documentation

Documentation is automatically built and deployed:

  • On every push to main: Documentation is built and deployed to GitHub Pages

  • On pull requests: Documentation is built (but not deployed) to verify no errors

The deployed documentation is available at the GitHub Pages URL for the repository.

Quick syntax reference

MEDIAWIKI syntax

Element

Syntax

Example

Root tag

'''TagName'''

'''Action'''

Child tag

* (1 level)

* Communicate

Grandchild

** (2 levels)

** Communicate-gesturally

Great-grandchild

*** (3 levels)

*** Clap-hands

Literal content

<nowiki>...</nowiki>

<nowiki>{hedId=HED_0012001}</nowiki>

Description

[text]

[Do something.]

Attributes

{attr1, attr2=value}

{requireChild, hedId=HED_0012808}

TSV required columns

Column

Description

Example

hedId

Unique identifier (empty for prerelease)

HED_0012016

Level

Hierarchy depth (0=root)

0, 1, 2, 3

rdfs:label

Tag name

Action, Communicate

omn:SubClassOf

Parent tag name

HedTag, Action

Attributes

Comma-separated attributes

extensionAllowed

dc:description

Tag description

Do something.

Common attributes

Attribute

Type

Description

Example

hedId

Value

Permanent unique identifier

hedId=HED_0012016

suggestedTag

Value

Recommended accompanying tag

suggestedTag=Task-property

relatedTag

Value

Related tag reference

relatedTag=Move-face

annotation

Value

External resource link

annotation=dc:source Beniczky ea 2017

rooted

Value

Parent in partnered schema

rooted=Item

requireChild

Boolean

Must have child value

requireChild

topLevelTagGroup

Boolean

Must be at top level

topLevelTagGroup

extensionAllowed

Boolean

User extensions allowed

extensionAllowed

reserved

Boolean

Reserved for HED use

reserved

deprecatedFrom

Value

Deprecated version

deprecatedFrom=8.3.0

Key file locations

Schema Component

MEDIAWIKI Location

TSV Location

Tags

In main .mediawiki file

_Tag.tsv

Prefixes

'''Prefixes''' section

_Prefixes.tsv

External annotations

'''External annotations''' section

_AnnotationPropertyExternal.tsv

Sources

'''Sources''' section

_Sources.tsv

Schema attributes

'''Schema attributes''' section

_AnnotationProperty.tsv, _DataProperty.tsv, _ObjectProperty.tsv

Getting help

Documentation resources

Support