Feature #18651
Updated by Peter Amstutz almost 3 years ago
Design sketch to support using the vocabulary in the Python SDK, for review.
New class called @Vocabulary@ which is initialized from the vocabulary JSON. It can be initialized from an API object, in which case it fetches the vocabulary file itself.
The @Vocabulary@ has a dict, "key_aliases".
The key_aliases has an entry for every alias of every key, as well as the formal identifiers. The value is an object of type @VocabularyKey@.
The @VocabularyKey@ class has fields "identifier" (string), "aliases" (list of strings) and "value_aliases".
The "value_aliases" field has an entry for every alias of every value associated with this key, as well as the formal identifiers. The value is on object of type @VocabularyValue@.
The @VocabularyValue@ class has fields "identifier" (string) and "aliases" (list of strings).
Support case-insensitive lookup of aliases. Suggest indexing aliases as all-lowercase. Lookups check the check the case-insensitive version.
This is intended to be used to easily convert "properties" between aliases and formal identifers. There will be a @Vocabulary.convert_to_labels()@ and @Vocabulary.convert_to_identifiers()@ methods. The first normalizes based on human-readable labels, the second normalizes based to the machine identifiers.
The basic usage would be something like this
<pre>
vocab = Vocabulary(vocab_json)
vocabkey = vocab.key_aliases["species"]
print(vocabkey.identifier) # "id123"
print(vocabkey.aliases) # ["species", "animal"]
vocabvalue = vocabkey.value_aliases["human"]
print(vocabvalue.identifier) # "id456"
print(vocabvalue.aliases) # ["homo sapiens", "human"]
vocab.convert_to_identifiers({"animal": "human"})
# -> {"id123": "id456"}
vocab.convert_to_labels({"id123": "id456"})
# -> {"species": "homo sapiens"}
</pre>
Additional thought: could have add an indexer on the object so that you can just write @vocab["species"]["human"].identifier@.
Suggestion from Tom: wrapper methods which automatically translate the properties field to/from identifiers on get, list, create, update, etc.