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.
| Level | Value added |
|---|---|
| 0 No glossary | |
| 1 Non-shareable | Help a reader understand locally defined terms. |
| 2 Machine readable | Enables tooling, like domain specific hover-over popups. |
| 3 Traced to source | Know where do the glossary terms come from. |
| 4 Governed | Manage glossary maintenance |
| 5 Extra metadata | Support power use cases |
Level 1: Non-shareable
What
A non-shareable glossary may be included as a table within a document or website.
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.
How
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.
Example
| Term | Definition |
| mercury | metal element which is liquid's standard temperature |
Level 2: Machine readable and reusable
What
- Store terms in a standard, machine-readable format. Typically the glossary is stored as a static file, accessible via a URL, such as: https://mywebsite.org/glossary.json.
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.
How
- 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.
Example
{
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
What
- 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).
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
Example
{
ex:chemistry rdf:type skos:Collection : {
dcterms:license “https://creativecommons.org/licenses/by/4.0/”;
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 “https://authoritative1.org/glossary.json”
# If term doesn’t have a source, then skos:inScheme isn’t mentioned
}
}
Level 4 Governed and versioned
What
- 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.
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
Example
{
ex:chemistry rdf:type skos:Collection : {
dcterms:license “https://creativecommons.org/licenses/by/4.0/”;
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 “https://authoritative1.org/glossary.json”
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)