Architecture
Definition
A controlled vocabulary (or simply vocabulary) is an organized collection of terms (i.e. names, codes, etc.) under the control of a governing authority. They can be simple — name authority files, code lists, synonym rings — or fairly complex — taxonomies and thesauri --, but at the core all of them aim to organize knowledge described in natural language.
Terms from controlled vocabularies are commonly used by reference as enumeration values in information systems which need to restrict what values are permissible. This has several benefits, such as a standardized way to reuse terms and their semantic descriptions, and allowing non-technical domain experts to contribute to vocabularies and not have to be familiar with programming.
Identification
Rationale
Each controlled vocabulary is identified by its IRI, and so are each of the terms contained in them:
Vocabulary |
|
|
|---|---|---|
Representation |
Web documentation (HTML) |
|
SKOS (Turtle) |
|
|
SHACL (Turtle) |
|
|
Term |
|
|
where:
{vocab}
|
vocabulary name (non-opaque in "kebab-case") |
{term}
|
term name (non-opaque) |
Life cycle management
Rationale
No release cycle or version number scheme will be used. Instead, in order to keep things simple, predictable and maintainable, controlled vocabularies will simply evolve [2]. New knowledge can always be added, including the introduction of new terms, but changes which alter the meaning or semantic scope of a term or the vocabulary are prohibited. In such cases a new term must be created with its own definition which may be stated to supersede the old term, and (if applicable) the old term can be deprecated. Terms and their definitions may also never be deleted. This way, any reference to a term or vocabulary will remain valid and accessible indefinitely (FAIR principles F1, A1 and A2).
|
Each modification to the vocabulary does result in a different version of it, but none of these representations are exposed through its identifying IRI and are merely accessible through the VCS. Effectively, this encodes having a single evolving identity whilst preserving historical lineage of the evolution. Furthermore, it deserves mention that terms themselves do not have versions. Different versions of a vocabulary might provide different descriptions of terms contained in it, but there is no such thing as a "version of a term". |
Build process
Rationale
Each controlled vocabulary is maintained through a single source file in YAML. The build process converts this to JSON and adds a JSON-LD context, creating a RDF graph. Furthermore, term IRIs are derived from the notations, explicit type statements are added to make the graph a proper SKOS ontology, and the concepts key is inverted into more standard skos:inScheme statements. Finally some additional information is added, such as the dcterms:source of the file.
This way of working keeps maintenance simple for authors, leaving the tedious and error-prone transforming and adding of information to the deterministic build process.