Schema developer’s guideΒΆ

This guide describes how to develop your own library schema or contribute to existing HED vocabularies.

Table of contentsΒΆ

  1. Getting started

  2. Schema design principles

  3. Proposing a new library schema

  4. Development workflow

  5. Developing a schema

  6. Release process

  7. Common pitfalls

  8. CI/CD pipeline

  9. Quick reference

  10. Getting help

Getting startedΒΆ

Before developing a schema:

  1. Explore existing schemas using the HED schema browser

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

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

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

  5. 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

Quick 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ΒΆ