In writing a definition for an entity, an attribute, or any other element within a database design, the desired end is a descriptive text that is clear, factual and concise. Semantics are an ambiguous and often painful tool to employ. Balancing the need for clarity against the desire to avoid redundancy can be a juggling act that is hard to accomplish. One might not easily recognize what is complete versus what is lacking, versus what has gone too far. But even so, within a definition if one finds oneself listing valid values and decoding the value’s meaning, then one has likely already moved beyond what is “concise.” Lists of values easily add bulk and quantity of verbiage into a definition, yet such lists do not usually increase the quality of a definition.
Beyond any other reason, value lists make a definition fragile. This fragility results because the existence of such detail in the definition increases overall system maintenance. Whenever new values arise, the values must be added into the operational side of the solution - whether this is in reference tables or processing logic - and also within whatever operational documentation exists. If these value lists also exist as part of a definition, then the data dictionary must be updated as well. Sadly, the actual process will execute whether or not the data dictionary is updated, which in practical terms means that updating a data dictionary definition is easily forgotten. Sometimes attempts are made to dodge this particular maintenance aspect by stating that the list within the data dictionary is simply a list “of examples” as opposed to the full list. This presumes that by admitting the listing may be incomplete, its use within the data dictionary is still legitimate. But in actuality, if an out-of-date or partial list is acceptable, no list at all should be just as acceptable. Examples may indeed be part of a definition, but for true definitional usage only one or two instances of examples are appropriate, and examples are not code/decode listings.
Fear often drives people to include lists as part of an item’s definition. The apprehension associates with the written text, perhaps because the author feels it is not clear, or just too fuzzy, so a solution arrives in the author’s mind: if the text isn’t clear enough, surely readers can simply scan this list and thereby comprehend on their own what might not have been articulated in words. If the ability to accurately describe something must rely solely on enumerating examples then clearly a better approach is needed. The author should explore crafting text for the definition; for example, possibly touching on synonyms or how the item is classified among peer terms, or groupings the term may belong within, or the groupings contained within the term, or things to which the term is related and how that relationship works.
Lists of valid values are useful information in the overall landscape of metadata within an organization. And while useful, and helpful, and accurate, these value lists are not a proper part of a data dictionary definition. Looking in an English language dictionary one would not expect to find a listing of various cities inside the definition of city, nor should such a list be expected within the data dictionary comprising the metadata behind an IT solution. Perhaps the metadata repository tool that accesses the definition can also access the valid values. Valid values should be listed in a common place where only valid values are documented – and ideally these are generated dynamically from the operational reference tables that serve as their system of record. In this way, the values are maintained only in one place, and the listings viewed by people are always up to date.