Description
The problem
When lists of terms are presented in TDWG standards as human readable documents using key:value lists, the meaning of the keys may be unclear. Definitions are needed to provide readers with the information needed to interpret the content of a vocabulary document. When viewing a vocabulary as an RDF document, the terms used to define the vocabulary are explicit, but this is not the case in human readable documents.
An Example from the Darwin Core Quick Reference Guide
https://dwc.tdwg.org/terms/#dwc:higherGeographyID
- Identifier - http://rs.tdwg.org/dwc/terms/higherGeographyID
- Definition - An identifier for the geographic region within which the dcterms:Location occurred.
- Comments - Recommended best practice is to use a persistent identifier from a controlled vocabulary such as the Getty Thesaurus of Geographic Names.
- Examples - http://vocab.getty.edu/tgn/1002002 (Antártida e Islas del Atlántico Sur, Territorio Nacional de la Tierra del Fuego, Argentina).
From the Darwin Core term list document: https://dwc.tdwg.org/list/#dwc_higherGeographyID
- Term IRI - http://rs.tdwg.org/dwc/terms/higherGeographyID
- Modified - 2023-06-28
- Term version IRI - http://rs.tdwg.org/dwc/terms/version/higherGeographyID-2023-06-28
- Label - Higher Geography ID
- Definition - An identifier for the geographic region within which the dcterms:Location occurred.
- Notes - Recommended best practice is to use a persistent identifier from a controlled vocabulary such as the Getty Thesaurus of Geographic Names. http://vocab.getty.edu/tgn/1002002 (Antártida e Islas del Atlántico Sur, Territorio Nacional de la Tierra del Fuego, Argentina).
The meaning of the labels "Term IRI, Modified, Term version IRI, Definition, Notes, Examples, Identifier, Comments" is not evident from the documents. See in particular "Comments" in the quick reference guide, which is rendered as "Notes" in the term list document.
Requesting a Turtle serialization makes things clearer: http://rs.tdwg.org/dwc/terms/higherGeographyID.ttl
<http://rs.tdwg.org/dwc/terms/higherGeographyID>
rdfs:isDefinedBy <http://rs.tdwg.org/dwc/terms/>;
dcterms:isPartOf <http://rs.tdwg.org/dwc/terms/>;
dcterms:created "2009-04-24"^^xsd:date;
dcterms:modified "2023-06-28"^^xsd:date;
rdfs:label "Higher Geography ID"@en;
skos:prefLabel "Higher Geography ID"@en;
rdfs:comment "An identifier for the geographic region within which the dcterms:Location occurred."@en;
skos:definition "An identifier for the geographic region within which the dcterms:Location occurred."@en;
skos:example "`[http://vocab.getty.edu/tgn/1002002`](http://vocab.getty.edu/tgn/1002002) (Antártida e Islas del Atlántico Sur, Territorio Nacional de la Tierra del Fuego, Argentina)."@en;
What is referred to in the Quick Reference guide as "Comments" and the term list as "Notes" is a rdfs:comment. The lack of clarity in the human readable documents causes confusion, and is a clear example of the need for keys.
Proposed solution
The SDS should provide an expectation that a human readable term list document should provide a key to the terms used to describe the vocabulary in that term list.
The Biodiversity Data Quality (BDQ) Context
In the development of the draft BDQ standard, we developed a human readable quick reference guide to the tests, providing a subset of the terms that define each test, and human readable term list document for each vocabulary in BDQ. The task group found these documents confusing, and in an email, @Tasilee argued that the central issue was the absence of a key providing definitions for the terms used to describe each vocabulary:
Our basic strategy for documents like the BDQ Quick Reference Guide or the vocabularies where we are dumping csv information into the HEADER, MUST contain an explanation/definition for the terms in the LIST that follows. If that is not the cas
65C4
e, how can a user understand what the content of the list means? While there could be links or references to such explanations, we do not think that is wise. Those documents should be self-contained when it comes to explaining fundamental terms used in those documents.
For example, take the bdqenh vocabulary list of terms: It MUST contain at least simple definitions of
• Term IRI
• Modified
• Term version IRI
• Label
• Definition
• Comments
• Controlled value
• Type
These lists of definitions provide readers with all the information needed to interpret the content of that document/vocabulary.
An example:
In the draft proposed Biodiversity Data Quality (BDQ) standard, for each vocabulary in the standard, we provide a key to the terms used to describe the vocabulary, with the key having entries for Label. Term, Normative, Definition and Example. The Label is the label used in the term list, the Term is the underlying term that is found in the RDF representation of the vocabulary. Normative is a statement of whether this element is normative or non-normative in this vocabulary. Definition is the definition of the term, drawn from its authoritative source, any additional TDWG context from the SDS and any meaning local to this document.
One entry from that table:
- Label: Term IRI
- Term: dcterms:isVersionOf
- Normative: normative
- Definition: A related resource of which the described resource is a version, edition, or adaptation. TDWG SDS: The HTTP IRI that uniquely identifies the current term.
- Example: https://rs.tdwg.org/bdqdim/terms/Completeness
Thus, when an individual term within the vocabulary is encountered, e.g.-
- Term - bdqdim:Completeness
- Term IRI - https://rs.tdwg.org/bdqdim/terms/Completeness
- Modified - 2024-09-30
- Term version IRI - https://rs.tdwg.org/bdqdim/terms/version/Completeness-2024-09-30
- Label – Completeness
- Definition - The extent to which data in a bdqffdq:InformationElement are present and sufficiently comprehensive for use.
- Comments - Definition from the Fitness for Use Framework: Data Quality Dimensions Document https://github.com/tdwg/bdq/wiki/TG2-Data-Quality-Dimension.
- Status – recommended
- Controlled value – Completeness
- Type - bdqffdq:DataQualityDimension
the meaning of each of the keys in the key:value pairs describing and defining the term is made explicit. For example, both the global definition of Term IRI and the TDWG context for Term IRI from the SDS are provided without the user having to look at the RDF representation of the terms, discover that Term IRI is dcterms:isVersionOf, and look up the definition of this term (and look it up in the SDS). The importance of such as key is evident in the rich bdqtest: vocabulary, which contains many terms:
https://github.com/tdwg/bdq/blob/master/tg2/_review/docs/list/bdqtest/index.md#110-key-to-vocabulary-terms-normative
the meaning of which needs to be clear for the human readable presentation of a term to be clear.
https://github.com/tdwg/bdq/blob/master/tg2/_review/docs/list/bdqtest/index.md#bdqtest_853b79a2-b314-44a2-ae46-34a1e7ed85e4
Proposal
Add a section to the SDS: 3.3.5 Keys in term version lists.
Each term list SHOULD include a key to the items that make up the term version entries. This key SHOULD include the IRI for the term version entry, the label used for the term version entry, and a definition of the term version entry, at a minimum copying the list of term version entries and definitions from section 3.3.4. This key MAY include a statement about whether the term version entry is normative in the vocabulary. This key MAY include an example of an entry found in the vocabulary. This key MAY include the global definition of the term in the term version entry, the TDWG specific meaning, and any meaning local to the present vocabulary.
An Example
| Label | Term | Normative | Definition | Example |
|Term IRI | dcterms:isVersionOf | normative | A related resource of which the described resource is a version, edition, or adaptation. TDWG SDS: The HTTP IRI that uniquely identifies the current term. | https://rs.tdwg.org/ bdqdim/terms/Completeness |