Repository structure¶

This page describes the structure and organization of the hed-schemas repository.

Directory organization¶

Root directories¶

The repository is organized into the following main directories:

standard_schema/

Contains the HED standard schema in all formats

hedxml/ - XML format schemas
hedwiki/ - MediaWiki format schemas
hedjson/ - JSON format schemas
hedtsv/ - TSV format schemas
prerelease/ - Working versions under development
README.md - Schema documentation
CHANGELOG.md - Version history
LICENSE - MIT license

library_schemas/

Contains all HED library schemas

score/ - SCORE clinical EEG vocabulary
lang/ - Language experiment vocabulary
slam/ - Sensor location and motion vocabulary
mouse/ - Mouse/rodent experiment vocabulary
testlib/ - Testing vocabulary

Each library has the same subdirectory structure as standard_schema.

scripts/

Utility scripts for schema validation and verification

verify_branch.py - Pre-commit hook for branch validation

docs/

Documentation source files (this documentation)

*.md - Markdown documentation files
*.rst - reStructuredText documentation files
_build/ - Built documentation output

.github/workflows/

CI/CD pipeline definitions

validate_schemas.yaml - Schema validation
verify_source_branch.yaml - Branch verification
update_manifests.yaml - Version manifest and latest-JSON copies
typos.yaml - Spell checking
mdformat.yaml - Markdown formatting
links.yaml - Link validation
deploy-docs.yaml - Documentation deployment

Configuration files¶

library_data.json

Defines HedId ranges for each library schema:

{
  "": {"id_range": [10000, 39999]},     // standard
  "score": {"id_range": [40000, 59999]},
  "lang": {"id_range": [60000, 79999]},
  "slam": {"id_range": [80000, 99999]},
  "mouse": {"id_range": [100000, 119999]}
}

pyproject.toml

Project configuration for documentation build

CONTRIBUTING.md

Guidelines for contributing to HED schemas

Schema version structure¶

Released versions¶

Released schema versions are stored in format-specific directories:

hedxml/HED8.4.0.xml - Released XML schema
hedwiki/HED8.4.0.mediawiki - Released MediaWiki schema
hedjson/HED8.4.0.json - Released JSON schema
hedtsv/HED8.4.0/ - Released TSV schema files

Prerelease versions¶

All schema development happens in the prerelease/ subdirectory:

prerelease/HED8.5.0.mediawiki - Working schema (edit this)
prerelease/HED8.5.0.xml - Auto-generated XML
prerelease/HED8.5.0.json - Auto-generated JSON
prerelease/hedtsv/ - Auto-generated TSV files
prerelease/PRERELEASE_CHANGES.md - Documented changes
prerelease/PROPOSED.md - Proposed future changes

Workflow summary¶

Schema development workflow¶

Create branch with appropriate prefix (standard_*, score_*, etc.)
Edit .mediawiki file in prerelease/ directory
Document changes in PRERELEASE_CHANGES.md
Push to GitHub
CI/CD automatically converts and validates
Create pull request
Merge after review

Release workflow¶

Update version in schema header
Update CHANGELOG.md
Move files from prerelease/ to release directories
Create git tag
Create GitHub release
Upload the released files to the schema’s Zenodo record by hand (Zenodo does not update automatically)