Glossary maturity levels

This page proposes maturity levels for shareable glossary use cases, along with expected fields for each level’s schema profile.

Last updated: January 2022

Version: 0.1

Status: Unreviewed. (Errors expected in the schema formats.)

Maturity levels

A glossary should start small, minimizing barriers to implementation. As the glossary matures, more metadata fields can be added to address advanced use cases.

LevelValue added
0 No glossary
1 Non-shareableHelp a reader understand locally defined terms.
2 Machine readableEnables tooling, like domain specific hover-over popups.
3 Traced to sourceKnow where do the glossary terms come from.
4 GovernedManage glossary maintenance
5 Extra metadataSupport power use cases

Level 1: Non-shareable


A non-shareable glossary may be included as a table within a document or website.

Non-shareable glossary table embedded in a document.

Non-shareable glossary.

Value added

A glossary is relatively straightforward to establish for a document or small website. It helps readers understand the terms used.


Copy domain-specific terms from your documentation into a glossary table. Include columns for Terms and Definitions. Ideally, source definitions from a more authoritative glossary.


mercurymetal element which is liquid's standard temperature

Level 2: Machine readable and reusable


Glossary stored in a machine-readable .json file in website.

Glossary stored in a machine readable .json file in website.

Value added

Adding machine readability enables multiple domain specific use cases, such as:

  • Hover-over popups for terms within a document.
  • Downstream glossaries referencing terms within this glossary.


  • Level 2 of the shared glossary profile involves copying the terms and definitions from your Level 1 table into a glossary file. (Fields from higher maturity levels may additionally be included as needed.)

Fields for level 2

  • skos:Collection # Glossary’s top level, covering a collection of terms.
  • skos:Concept # A term to describe
  • skos:prefLabel@en # The preferred term name
  • skos:prefLabel@fr # Optional: Other languages can be supported
  • skos:altLabel # Optional: Store acronyms and synonyms
  • skos:definition # Textual definition

Fields from higher maturity levels may optionally be included.


  ex:chemistry rdf:type skos:Collection : {
    ex:mercury rdf:type skos:Concept : {
      skos:prefLabel "mercury"@en;
      skos:prefLabel "mercure"@fr; # Optionally support multiple languages
      skos:altLabel "hg"@en; # altLabel is optional
      skos:definition "metal element which is liquid at standard temperatures"@en;

Level 3 Reference source glossaries


  • Source terms from upstream glossaries and retain hyperlink to the source.
  • Assign a license which allows repurposing of the glossary by downstream users, such as Creative Commons By Attribution (CC-By).

Machine-readable glossary file referencing terms from source glossary.

Glossary terms referencing source.

Value added

Adding a reference to the source glossary enables:

  • Increased interoperability.
  • Suitable attribution provided to address license conditions.
  • Term definitions can be refreshed from updated source glossaries.
  • A glossary’s credibility will benefit from referencing a more authoritative source.

Extra fields for level 3

  • dcterms:license
  • skos:inScheme
  • dcterm:identifier


  ex:chemistry rdf:type skos:Collection : {
    dcterms:license “”;
    ex:mercury rdf:type skos:Concept : {
      skos:prefLabel "mercury"@en;
      skos:prefLabel "mercure"@es; # Optionally support multiple languages
      skos:altLabel "hg"@en;
      skos:definition "metal element which is liquid at standard temperatures"@en;
      dcterm:identifier “mercury”; #unique identifier
      skos:inScheme “”
      # If term doesn’t have a source, then skos:inScheme isn’t mentioned

Level 4 Governed and versioned


  • Apply governance processes to manage glossary updates.
  • Identify a glossary custodian
  • Apply a unique identifier for each term.
  • Apply versioning to terms (skos:Concepts).
  • Periodically release a baselined version of the glossary (skos:Collection).
  • Publish glossary license information.

Process for sourcing and reviewing glossary terms.

Possible glossary governance process.

Value added

  • Managed quality control processes.
  • Planned release cycles.
  • Reduced accidental inconsistencies.
  • Maintainers can recommend updates to source glossaries.

Extra fields for level 4

  • ex:collectionVersion
  • ex:sourceGlossaryVersion
  • ex:sourceConceptVersion


  ex:chemistry rdf:type skos:Collection : {
    dcterms:license “”;
    ex:collectionVersion rdf:type owl:versionInfo “1.2.1”;
    ex: priorVersion rdf:type owl:priorVersion “1.2.0”;
    ex:mercury rdf:type skos:Concept : {
      skos:prefLabel "mercury"@en;
      skos:altLabel "hg"@en;
      skos:definition "metal element which is liquid at standard temperatures"@en;
      dcterm:identifier “mercury”; #unique identifier within Collection
      skos:inScheme “”
      ex:sourceGlossaryVersion rdf:type owl:versionInfo “2.0”;
      ex:sourceConceptVersion rdf:type owl:versionInfo “3”;

Level 5 Extra metadata

More extensive use cases may involve adding extra metadata fields to the ConceptCollection and Concepts.

As at January 2022, this section requires further definition.

Possible extra fields for level 5

  • skos:note # Comments about the term.
  • skos:scopeNote # Clarifications on usage.
  • dcterms:creator
  • dcterms:created
  • dcterms:modified
  • dcterms:source
  • dcterms:replaces
  • rdfs:seeAlso
  • skos:broader
  • skos:narrower
  • skos:related
  • skos:broadMatch
  • skos:closeMatch
  • skos:exactMatch
  • skos:narrowMatch
  • skos:relatedMatch
  • skos:ConceptScheme

Further reading

Last modified 2022-05-15 (1fd8c89)