Schema developerβs guideΒΆ
This guide describes how to develop your own library schema or contribute to existing HED vocabularies.
Quick linksΒΆ
π¬ GitHub issues - Propose changes or ask questions
π§ HED maintainers - Technical guidance
π HED specification - Complete specification
π Schema browser - Explore existing schemas
π§ HED online tools - Validate and convert schemas
Table of contentsΒΆ
Getting startedΒΆ
Before developing a schema:
Explore existing schemas using the HED schema browser
Post an issue describing your proposed changes or new schema on GitHub issues
Discuss with the HED Working Group at hed.maintainers@gmail.com
Choose a schema name (short, informative, alphabetic string)
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-handsis-aCommunicate-gesturallyCommunicate-gesturallyis-aCommunicateCommunicateis-aAction
This enables search generalization: searching for Communicate returns all descendant tags.
3. Orthogonal designΒΆ
Independent concepts should be in different subtrees. For example:
Left-handedis NOT a type ofHumanLeft-handedIS a type ofProperty(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
withStandardversion in the library schema headerUse
{rooted=ParentTag}attribute to integrate library terms under standard schema nodesAdd top-level tags (corresponding to separate subtrees) only when required
Do not use the
inLibraryattribute β 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 (
.mediawikifiles) - Human-readable text format in a single file β easiest format for visualizing the hierarchical structureTSV format (
.tsvfiles) - Spreadsheet-compatible format with separate files for tags, units, etc. Users usually only edit the_Tag.tsvfile β easiest format for including lots of attributes and links to other resourcesXML/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:
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
Discuss with the HED Working Group:
Contact maintainers at hed.maintainers@gmail.com
Present your use case and requirements
Get feedback on scope and approach
Choose a schema name:
Short, informative, alphabetic string (e.g.,
lang,score,slam)Name should clearly indicate the domain
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)
Maintainers create the schema structure:
Create directory
library_schemas/<name>/Set up
prerelease/directory with empty templatesFill 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)
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 |
|---|---|
|
Only |
|
Only |
|
Only |
|
Only |
|
Only |
|
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
ALL changes go to
prerelease/subdirectoryEdit ONLY the
.mediawikifile OR ONLY the.tsvfiles during one PR (GitHub pull request)Let CI/CD pipeline convert to other formats
Never edit released schemas
NEVER assign or change
hedIdvalues. 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ΒΆ
Fork the repository on GitHub:
Go to the hed-schemas GitHub repository
Click the βForkβ button to create your own copy
Clone your fork locally:
git clone https://github.com/YOUR-USERNAME/hed-schemas.git cd hed-schemas
Create a branch with appropriate prefix:
git checkout -b xxx_add_new_term
where
xxxisstandardor the library name depending on which schema you want to change. Thexxxvalueadminis reserved mainly for maintainers and should not be used by individual schema developers.Edit the prerelease MEDIAWIKI file (alternatively the
xxx_Tag.tsvfile):For standard schema:
standard_schema/prerelease/HEDX.Y.Z.mediawikiFor library schema:
library_schemas/<name>/prerelease/HED_<name>_X.Y.Z.mediawiki
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
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
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.
Create pull request to the main repository:
Go to your fork on GitHub
Click βPull Requestβ to create a PR targeting the
mainbranchProvide a clear description of your changes
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:SubClassOfDuplicate term names
Fix errors in your prerelease file and push again
CI/CD will re-run automatically on each push
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)
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 nameThe 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:
Beckonis added at the same level asClap-hands(both have leading***)Beckonbecomes a child ofCommunicate-gesturally(the nearest previous line with fewer asterisks)The description is enclosed in square brackets within
<nowiki> </nowiki>tagsNote that
Beckondoes not have ahedIdyet since itβs in prerelease -hedIdvalues are assigned only at release timeBy convention, we keep the sibling tags of a parent tag in alphabetical order, so we put
BeckonbeforeClap-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
HedTagfor 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:
Beckonis added withLevel=3(same asClap-hands)omn:SubClassOf=Communicate-gesturallyspecifies the parenthedIdis empty (left blank) for prerelease terms - HedIds are assigned only at release timeThe 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:
hedIdappears in the attributes list within{}In TSV format:
hedIdhas its own dedicated column and does NOT appear in the Attributes columnDuring prerelease development, leave
hedIdempty for new tags - it is assigned automatically during official releaseOnce assigned,
hedIdvalues 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.
External linksΒΆ
External annotations link schema terms to external resources like ontologies, publications, or databases using namespace prefixes. All external annotations and links are included using the annotation schema attribute. The information about the links is defined in three places:
Sources - Define bibliographic references that can be cited
Prefixes - Map short prefixes (e.g.,
dc:) to full namespace URIsExternal annotations - Define which external properties can be used (e.g.,
dc:source)
The most common use case for external links is to cite a reference. This is done with annotation=dc:source followed by the citation as illustrated in the following example.
Including citations in schemas
MEDIAWIKI format:
'''Mu-rhythm''' <nowiki>{annotation=dc:source Beniczky ea 2013 Appendix S2} [EEG rhythm at 7-11 Hz composed of arch-shaped waves.]</nowiki>
TSV format:
hedId |
Level |
rdfs:label |
omn:SubClassOf |
Attributes |
dc:description |
|---|---|---|---|---|---|
HED_0042047 |
1 |
Mu-rhythm |
Background-activity |
annotation=dc:source Beniczky ea 2013 Appendix S2 |
EEG rhythm at 7-11 Hz composed of arch-shaped waves. |
The annotation dc:source Beniczky ea 2013 Appendix S2 uses:
dc:prefix (defined inPrefixesfor MEDIAWIKI) pointing to Dublin Coresourceproperty from Dublin Core elements (defined inExternal annotationsfor MEDIAWIKI)Beniczky ea 2013source reference (defined inSourcesMEDIAWIKI)Appendix S2specific location within that source
To use other external ontology terms as annotations, you must define an appropriate prefix (abbreviation of the resource) as well as an external annotation giving the IRI of the item within that resource. This allows inclusion of links to most ontology terms and external resources.
SourcesΒΆ
Sources define bibliographic references that can be cited in schema tags. Each source has a short name, URL/DOI link, and description. The short source name (e.g., Beniczky ea 2017) is used when citing the reference in tag annotations.
Defining bibliographic sources
MEDIAWIKI format (in Sources section):
'''Sources'''
* <nowiki>source=Beniczky ea 2017,link=https://doi.org/10.1016/j.clinph.2017.07.418,description=Standardized computer based organized reporting of EEG: SCORE second version.</nowiki>
* <nowiki>source=Wikipedia,link=https://en.wikipedia.org,description=General definitions of concepts.</nowiki>
TSV format (in _Sources.tsv file):
source |
link |
description |
|---|---|---|
Beniczky ea 2017 |
Standardized computer based organized reporting of EEG: SCORE second version. |
|
Wikipedia |
General definitions of concepts. |
PrefixesΒΆ
Prefixes map short abbreviations to full namespace URIs for external ontologies and vocabularies. All prefixes used in the External annotations section must be defined here. Common prefixes include dc: (Dublin Core), ncit: (NCI Thesaurus), rdfs: (RDF Schema), and skos: (SKOS vocabulary).
Defining namespace prefixes
MEDIAWIKI format (in Prefixes section):
'''Prefixes'''
* <nowiki>prefix=dc:,namespace=http://purl.org/dc/elements/1.1/#,description=The Dublin Core elements</nowiki>
* <nowiki>prefix=ncit:,namespace=http://purl.obolibrary.org/obo/ncit.owl,description=NCI Thesaurus OBO Edition</nowiki>
TSV format (in _Prefixes.tsv file):
prefix |
namespace |
description |
|---|---|---|
dc: |
The Dublin Core elements |
|
ncit: |
NCI Thesaurus OBO Edition |
External annotationsΒΆ
External annotation properties define which ontology terms can be used as annotation keys in your schema. The most commonly used is dc:source for citations. The dc:source entry enables you to use annotation=dc:source in your schema tags to cite references.
Defining external annotation properties
MEDIAWIKI format (in External annotations section):
'''External annotations'''
* <nowiki>prefix=dc:,id=source,iri=http://purl.org/dc/elements/1.1/source,description=A related resource from which the described resource is derived.</nowiki>
* <nowiki>prefix=dc:,id=creator,iri=http://purl.org/dc/elements/1.1/creator,description=An entity primarily responsible for making the resource.</nowiki>
TSV format (in _AnnotationPropertyExternal.tsv file):
prefix |
id |
iri |
description |
|---|---|---|---|
dc: |
source |
A related resource from which the described resource is derived. |
|
dc: |
creator |
An entity primarily responsible for making the resource. |
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:
Final review and approval by the HED Working Group
Moving files from
prerelease/to release directoriesAssigning permanent
hedIdvaluesTagging 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ΒΆ
Donβt edit released schemas
Only edit files in
prerelease/directories
Donβt edit XML/JSON directly
Always edit EITHER MEDIAWIKI OR TSV and let CI convert
Donβt use wrong branch prefix
Branch name must match the schema youβre modifying
Donβt reuse HedIds
HedIds are permanent identifiers, never reuse or assign yourself
Donβt forget to document changes
Update
PRERELEASE_CHANGES.mdfor every change
Donβt violate is-a relationship
Every child must be a type of its parent
Donβt mix properties with categories
Left-handedis not a type ofHuman
Donβt create duplicate terms
Check existing schemas before adding
Donβt skip version increment rules
Understand major/minor/patch implications
β Do this insteadΒΆ
β Edit in
prerelease/subdirectoriesβ Edit only
.mediawikifiles or.tsvfilesβ Use correct branch prefix (
standard_*,score_*, etc.)β Let CI auto-assign HedIds
β Document all changes in
PRERELEASE_CHANGES.mdβ Maintain strict is-a hierarchy
β Keep properties orthogonal to categories
β Search existing schemas thoroughly
β 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 |
|---|---|
|
Validates all changed schema files |
|
Converts changed file(s) to other format |
|
Assigns HedIds to new terms (if during release) |
|
Ensures changes on correct branch and in |
|
Checks spelling |
|
Checks Markdown formatting |
|
Checks for broken links |
Quick referenceΒΆ
MEDIAWIKI syntaxΒΆ
Element |
Syntax |
Example |
|---|---|---|
Root tag |
|
|
Child tag |
|
|
Grandchild |
|
|
Great-grandchild |
|
|
Literal content |
|
|
Description |
|
|
Attributes |
|
|
TSV required columnsΒΆ
Column |
Description |
Example |
|---|---|---|
|
Unique identifier (empty for prerelease) |
|
|
Hierarchy depth (0=root) |
|
|
Tag name |
|
|
Parent tag name |
|
|
Comma-separated attributes |
|
|
Tag description |
|
Common attributesΒΆ
Attribute |
Type |
Description |
Example |
|---|---|---|---|
|
Value |
Permanent unique identifier |
|
|
Value |
Recommended accompanying tag |
|
|
Value |
Related tag reference |
|
|
Value |
External resource link |
|
|
Value |
Parent in partnered schema |
|
|
Boolean |
Must have child value |
|
|
Boolean |
Must be at top level |
|
|
Boolean |
User extensions allowed |
|
|
Boolean |
Reserved for HED use |
|
|
Value |
Deprecated version |
|
Key file locationsΒΆ
Schema Component |
MEDIAWIKI Location |
TSV Location |
|---|---|---|
Tags |
In main |
|
Prefixes |
|
|
External annotations |
|
|
Sources |
|
|
Schema attributes |
|
|
Getting helpΒΆ
Working Group: Email hed.maintainers@gmail.com
Homepage: www.hedtags.org
Resources: www.hedtags.org/hed-resources