TG2-Notes to the BDQ Review Manager #306
Description
Notes for the Review Manager of BDQ
This will be the first TDWG standard since the SDS to use an ontology as well as vocabularies. Some consequences, and some other decisions made in producing the documentation of the proposed standard.
1. Master copy of the ontology in owl, term-version file not implemented yet.
We are maintaining the ontology in owl (in an turtle serialization) as the master copy, leaving it to implementation in the TDWG infrastructure to produce a term-version csv file from which to build the ontology document.
2. Documents for the ontology.
The SDS specifies that ontologies need: A term-version file with the basic vocabulary in the ontology, a vocabulary extension with additional axioms, and a landing page, each with a different URI. To support eventual directory paths to documents tdwg.org/bdqffdq/{sort of thing}/ as the different URIs, we have built /docs/bdqffdq/index.md for the landing page, /docs/list/bdqffdq/index.md, for the term list, and in the absence of guidance from the SDS, used /docs/extension/bdqffdq/index.md for the extension list. We have placed the bulk of the normative statements about bdqffdq in the landing page document. To reduce confusion, in each of these documents, we have added a section that lists all of these documents and their relationships to each other as well as the required list of distributions. Some of these elements are required by the SDS, others we’ve tried to be logical where the SDS is not explicit.
3. Competency Questions
The SDS specifies that a TDWG ontology must be accompanied by competency questions. We have both pointed to the original set of competency questions framed by Bob Morris for the original ontology representation of the Framework, and a set that we have written in the Supplement document. There does not appear to be a requirement for them to be normative, and we considered that the Supplement document appears an appropriate place for them.
4. Keys to Terms
To each vocabulary term-list document we have added a section that gives an explicit key to each of the terms used to describe the terms in the vocabulary. We feel that the absence of a requirement for such a key is a weakness of the SDS.
We adopted the landing page with normative guidance and separate term-list page for the bdq: (list of tests) vocabulary. This appears to work well with the combination of a Quick Reference Guide to the tests, the term-list page with the bulk of the normative statements and the term-list page with all the details for each test, and separate User and Implementer Guides.
5. Identifiers for tests and components of tests
In constructing the tests, we found that the labels of tests could be unstable over the decade of development, and settled on opaque globally unique UUIDs as the guaranteed stable identifiers for tests and other concepts in BDQ. The Java implementation of the tests use these identifiers to link to the RDF representation of BDQ and to identify Java methods implementing particular tests, thus using identifiers for machine consumption by software.
In BDQ, we have posited that each test (each instance of a subclass of bdqffdq:DataQualityNeed) will have a resolvable IRI, e.g. https://rs.tdwg.org/bdqcore/terms/0493bcfb-652e-4d17-815b-b0cce0742fbe for VALIDATION_COUNTRYCODE_STANDARD however, we have posited (probably incorrectly) that non-resolvable identifiers would suffice for instances of Methods, Specification, and other bdqffdq classes instantiated in BDQ (e.g. urn:uuid:01b96157-e4a1-4884-95d7-3bcfc5f3c047 for the instance of the Specification associated with VALIDATION_COUNTRYCODE_STANDARD. If resolvable IRIs are desired by the TAG instead, these will be very straightforward to change to if and when BDQ becomes a standard.
6. Restrictions
bdqffdq is an ontology and we have chosen to apply limited restrictions to that ontology. Restrictions, domains and ranges tend to have unexpected side effects for those used to sql schemas or uml or other representations of related classes of information. Consequently, for bdqffdq to be used in a meaningful way, we have had to make a large number of normative assertions about how object properties are to be used. The most important set relates to queries on assertions made by test implementations to be able to be followed back to the description of the test that was run to make the assertion. Consequently, the list of normative statements associated with bdqffdq is much larger than if we had adopted an IDEFX information model or UML to model the framework instead of owl. The choice of owl is deliberate, looking towards linked open data, and representation in an extended specimen network, following TDWG's long standing approach to representing data in RDF.
7. Contributors/Authors.
This is a deliberate departure from the SDS. Section 3.2.3.1 Header Section (for descriptive documents) in the SDS specifies that the header of each descriptive document should include and entry “Contributors”. Given the very long term development of BDQ Core, and the very different levels of contributions by different contributors over more than a decade, we decided to provide a list of all the contributors with explicit description of their contributions in the introduction, and provide a list of authors for the standard on each of the descriptive documents. This reflects the long term commitment of these authors in the development of the tests and their active authorship of the text of the standard.
8. Normative or Non-normative marking.
We made a decision to explicitly label each section (or an entire document) as normative or non-normative, since the SDS as being somewhat contradictory about the requirements with respect to such labeling. We provided feedback to the SDS concerning this at: tdwg/vocab#55.
Following the guidance in the SDS about labeling artifacts such as images and captions, we explicitly asserted that examples in the text are non-normative, including the following text in relevant documents: Any sentence or phrase beginning with "For example" or "e.g.", whether in a normative section or a non-normative section, is non-normative.