Documentation Policies
- Michael
This is an email trail of a few comments.
From Elisa:
I was not on the call that discussed the form of definitions. We had agreed previously to use ISO 704-style definitions, which are not necessarily complete sentences. They take the form of "a <superclass/super-property> that ...", followed by a series of qualifying statements, including but not limited to their "genus/differentia" from Aristotelian styling. While we never completed the write-up on the various forms this should take, I don't see the benefit of changing this now. We agreed on shorter, consumable, and to the point definitions in the style I've mentioned, over longer sentences that add fluff, such as "An <x> is a ..." at the front of the rest of the definition. The ISO 704 approach is preferred in terminologies, business vocabularies and in the library science community, and there is no guidance in the more academic ontology community that I'm aware of. Explanatory notes and additional content may take the form of full sentences, or not, depending on the material. I tend towards complete sentences in explanatory notes, but not necessarily in examples. I would be happy to provide my copy of the ISO document to those who need it, although the banks will need to purchase their own.
--
From MichaelU:
There is value in a detailed precise definition using terms from the ontology. I favor the genus/differentia model whenever possible. The degree of precision often results in longwinded and technical definitions, which are great for technical people, but get in the way for people wanting a quick understanding of the concept. We sometimes have two definitions, one short one using everyday terminology, and a longer more precise one.
Example in health care:
Class: SkilledNursingFacility
Full Definition: A licensed establishment that houses chronically ill, usually elderly patients, and provides long-term nursing care, rehabilitation, and other services. Also called long-term care facility, nursing home. Licensing criteria include that the care of every patient be under the supervision of a physician, that a physician be available on an emergency basis, that medical records for the residents be maintained, etc.
Short Definition: A licensed facility that provides long-term nursing care, rehabilitation, and other services primarily to chronically ill and/or elderly patients.
--
From Elisa:
One purpose of the explanatory note annotation is precisely to augment what you're calling the short definition with the additional material. Long-term care facility would be a synonym, as would nursing home, and then the sentence following that would be captured in an explanatory note. The short definition, with a lower case "a" at the start, since this isn't a sentence, and no "." at the end, conforms to the ISO 704 style, -- iff-- the class SkilledNursingFacility is a subclass of LicensedFacility.
From Pete:
But I don’t think the audience for FIBO is professional taxonomists and librarians.
Can you point at examples of real business vocabularies that use this style? I have come across many at our banking customers and have seen none that do this.
More importantly, we’re taking definitions from a number of external sources (Barron’s, Investopedia, legal documents) which will not use this style and I don’t think it should be up to us to apply editing (and inevitably paraphrasing) to make the original definitions conform to this style.
Finally these are complex definitions in many cases and need more than one sentence. Unless the sentence is so long and convoluted in legalese-style that becomes incomprehensible. Given we have more than one sentence it seems weird to have the first one start with a lower case latter and the (last one?) not end with a period.
--
From Elisa:
Nordea has adopted this style for their business vocabularies and ontologies across the bank, and with respect to the ISO style, the banking side of the business was doing this prior to our involvement. The Markets business vocabulary and ontologies that (1) extend FIBO, and (2) are also the source for compliance with BCBS 239, use this style.
The point that I've been attempting (and failing) to make about the equal importance of development of an ontology that is also a business vocabulary, with respect to the naming of concepts as well as the style of definition has to do, in part, with our ability to support requirements such as BCBS 239. Many recent FIBO presentations have stated FIBO's value in supporting BCBS 239. A common and ISO standards based approach to development of definitions is an integral part of that support. If you have banking customers in the EU that are not using ISO 704, I would be surprised. Any time you can state that your approach conforms to ISO, you are in better shape in the EU. I don't see that this should be considered a deficit in the US.
There are -no- other standards for development of terminology and formal definitions that I'm aware of -- ISO 704 and related to that, ISO 1087, is also the basis for SBVR, and their definitions follow this approach as well.
We have had to adapt most of the definitions we've reused in order to relate them to their superclass/super-property, so I don't see the issue of adaptation as a problem. And for those that are more complex, we've added semi-colons, we've added explanatory notes, etc. I don't see the issue you are seeing.