You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
These are a list of actionable items from the Review for @Tasilee, @ArthurChapman, @tucotuco, @chicoreus and @ymgan to discuss and address before resubmission of BDQ. Issues requiring open discussion and feedback will be created as separate GitHub issues linked to from this issue.
NOTE: All but a few of the edits at this stage (2026-03-03) have been applied to Word document versions (to make use of Track Changes) of the markdown files from GitHub and have not been ported back to GitHub. The links below are to the ORIGINAL GitHub documents.
(Done)@ArthurChapman Change 4 cases of "bdq:ParamaterizedTest" (PJM: Fixed as bdq:ParameterizedTest) ~~and 8 cases of "bdq:ParameterizedTest" to "bdq:Parameter Test"~~ (PJM: Not the term, combines label syntax with bdq:namespace, and isn't an appropriate label for the term). AC: But Paul - "ParameterizedTest" does not occur as a term in the bdq: (now bdqval:) namespace - only as comments throughout the ontology.
BDQ Empty
(Done) (PJM) bdq:Empty and bdq:NotEmpty definitions contain identical logic phrased differently. Fix logic. PJM: Fixed by phrasing the definitions more clearly and identically, except with true and false switched, original phrasing was difficult to parse.
(PJM, follow up on Stephen Formel comment below) bdq:Empty is explicitly defined as U+0000 to U+0020, which covers ASCII 0-32, but not other higher unicode non-printing characters. Glossary had mention of ASCII 127, but this is not in the definitions. Also high unicode characters that are non-printing are not addressed. Include these as SHOULD in the implementer's guide? Include in the definition?`
Link to Other Standards (John, Paul)
(Done) Stephen Formel (p. 24 Line 857) The W3C annotation standard is mentioned in the documentation, but not the W3C Data Quality Vocabulary (DQV). I was surprised to not see this standard mentioned in the supplemental material giving the history of development. If nothing else, I thought they might have considered how BDQ can be expressed as DQV. PJM: Some text added on DwC-DP to bdqtest: guide, also needed in implementers guide. Need to add text on the data quality vocabulary, particularly in reference to the bdqdim dimension vocabulary. resolved in BDQ Review - Discuss relationship of BDQ to the W3C Data Quality Vocabulary. #333 and BDQ Review - added text on DwC-DP needs checking. #334PJM: Added discussion of data quality vocabulary, Prov-O, DCAT and metadata about tests results to the bdqffdq guide. Added a dqv: term to the annotation example.
Name Spaces (John, Paul)
(Won't Fix, Probably) Rukaya Johaadien (Page 15 Line 524) and Stephen Formel (p. 17 Line 524) It’s probably hard to implement at this stage but you could have bdqu: as a preferred prefix as well as bdqffdq which is a bit hard to type, remember and pronounce out loud! (PJM): Could use bdqo with o for ontology, bdqu: seems odd as u suggests user. We likely don't want two prefixes for the same namespace. Pronouncing as as bdq ffdq has worked for us.PJM: Several other suggestions out there, difficulty is that one is non-trivial to change, as it is embedded in external implementation systems and would break them unless they also update.
Miscellaneous comments (Arthur)
(Done) Melissa Wiu (p. 7 Line 209) The documents do not yet make it consistently clear which sections are normative, and which are non-normative. Without clear designation, users may be uncertain about what must be followed versus what is illustrative. The writing is solid, but greater clarity—particularly in signaling normative content—will be essential to maximize adoption by the broadest audience. Comment: AC: This has been addressed in documents as editing proceeds - addressed in User's Guide, Introduction and BDQ Tests and Assertions so farPJM: Unclear about why the reviewer raised this issue, all sections are explicitly marked as normative or non-normative in the section headings, (though there as some new ones in the tutorial we need to add non-normative to), and there are consistent status of the content of this document statements in each document, and explicit disclaimers of examples.PJM: fixed headings in the tutorial. All headings in all the documents now have a (normative) or (non-normative) marker at the end of the heading.
(Done) Sophie Parmelon (p. 18 Line 650) Is it applicable to standards other than DwC (outside of the Bd field even?) Response:AC - this has been addressed in the User's Guide and a brief note placed in the IntroductionPJM: language "initially focused on Darwin Core" used in several places. Explicit domain neutral statement added to the bdqffdq guide.
(Not an issue) Stephen Formel (p. 23 Line 710) Ontology file (to open with Protégé): https://github.com/tdwg/bdq/blob/master/tg2/_review/vocabulary/bdqffdq.owl[**Response AC** - It is not clear what is meant here - Paul?]PJM: This appears to just be a pasted link to the owl file, not an an issue.
(????) Several reviewers (e.g. Stephen Formel p. 21 Line 766) mentioned liking the output in Rukaya's app.
Approach:
I carefully reviewed the actionable items and comments in the document to identify any issues that are mentioned more than once, either verbatim or in slightly different wording. Below, I list each duplicated issue, quoting the relevant line numbers and summarizing the duplication.
Duplicated Issues Identified
Terminology Consistency: “Use Case” Definition and Usage
• Line 240: Melissa Liu requests replacing “usecase” with “use case” and standardizing “UseCases” to “Use Cases.”
• Line 207: Melissa Wiu notes that the term “Use Case” should be defined more explicitly to avoid ambiguity.
• Line 641: Sophie Parmelon comments that actual use case files are not easily found.
• Line 657: Sophie Parmelon suggests providing more use cases or more exhaustive ones.
• Line 881: Stephen Formel and Melissa Wiu both mention the need for a “guide to the guides” and mapping user roles to guides, which relates to clarifying use case entry points.
Significance: The need for consistent terminology and clear definition of “Use Case” appears in multiple places, both as a terminology issue and as a documentation/navigation issue. PJM: We have adopted the convention of `Term Label`, or `namespace:TermLocalName` consistently, checking all instances of `UseCase` to change to `Use Case`, similarly for other labels that contain spaces
(Done) Broken or Hard-to-Find Links
• Line 613: Sophie Parmelon lists several broken links from the main GitHub repo page.
• Line 622: Sophie Parmelon lists more broken links from the TG2 (tests and assertions) repo page.
• Line 430: Rukaya Johaadien notes broken URLs in AuthoritiesDefaults for VALIDATION_COORDINATESTERRESTRIALMARINE_CONSISTENT.
Significance: Broken or inaccessible links are reported in several sections, indicating a recurring issue with documentation navigation and resource accessibility. PJM: Script written to check internal links, run regularly during revisions, currently at zero broken internal links.PJM: External links checked and updated.
Typos and Spelling Errors• Line 627: Sophie Parmelon points out typos in BDQ supplemental information.
• Lines 394–402: Rukaya Johaadien lists multiple spelling errors (e.g., “Amendement,” “Fittness,” “captialized,” “Vaildation,” etc.).
• Line 415: Rukaya Johaadien notes malformed strings and inconsistent key/value patterns, which often stem from typographical errors.
Significance: Typos and spelling inconsistencies are highlighted by multiple reviewers across different sections, showing this is a widespread issue. PJM: We've searched for and corrected instances of typos and spelling errors identified by the reviewers in all documents, run aspell on templates, asked github copilot to find spelling errors and typos, proofread more, and iteratively checked as we have rewritten text in response to the reviewers.
(Done) Documentation Structure and Redundancy
• Line 332: Rukaya Johaadien comments on redundancy in documentation.
• Line 580: Sophie Pamerlon and others mention that documentation is complex, redundant, and could be more concise.
• Line 568: Sophie Pamerlon suggests clearer, more concise, and user-oriented documentation.
• Line 209: Melissa Wiu notes the lack of clear designation between normative and non-normative sections, which relates to structural clarity.
Significance: Concerns about documentation structure, redundancy, and clarity are echoed by several reviewers, indicating a need for a more streamlined and user-friendly approach. PJM: Addressed: normative and non-normative text from bdqffdq landing page, bdqtest landing page, bdqffdq guide, bdqtest guide, and standard landing page combined into bdqffdq guide and bdqtest guide, both renamed to reflect "Context and Use". Redunancy between these two pages and the implementer's and user's guide remains and is intentional.
Test Types and Naming Conventions
• (Done) Line 248: Melissa Liu requests defining technical terms like “Validation,” “Issue,” “Measure,” and “Amendment” where they first appear. Comment: AC: Will be addressed by link terms in Tests to Glossary
• Line 202: Melissa Wiu suggests providing plain-language explanations of test types in the Quick Reference Guide.
• (DONE) Line 850: Stephen Formel questions why terms are sometimes all caps and sometimes camelCase. Comment:AC: A paragraph will be included in #1.8 of the Introduction Document?Basically the conventions used in Darwin Core (UpperCamelCase for classes and lowerCamelCase for properties) comes from a long history of capitalization conventions including (at least) 1) logical and philosophical distinctions between universals and particulars, 2) object-oriented programming conventions, 3) UML conceptual modeling practice, and 4) Semantic Web ontology engineering norms. The UPPERCASE convention we have are not names, they are just for labels. I wouldn't think there needs to be any justification for those either. Darwin Core and other standards use a convention where every word is separate and capitalized (so it isn't title case). i think Stephen wants us to change them, not justify them. We'd just have to justify to him why not. Justifications could be 1) they don't have to follow any convention as labels, 2) there is value in immediate recognition as a test label that would be lost otherwise, 3) the refactoring effort doesn't justify losing the one advantage they provide.
• (Won't Fix) Line 878: Stephen Formel asks about the need for a general spatial-mask term, which relates to test type clarity.
Significance: The need for consistent naming conventions and clear definitions of test types is raised in multiple places, showing this is a recurring concern.
Quick Reference Guide Usability
• Line 201: Melissa Wiu suggests adding a filter for Use Cases to improve navigation.
• Line 348: Rukaya Johaadien recommends making the Quick Reference Guide more user-friendly and adding filters.
• (Won't Fix) Line 520: Rukaya Johaadien suggests including a sentence on the order of running tests.
• Line 884: Stephen Formel recommends grouping terms for easier browsing.
Significance: Multiple reviewers suggest improvements to the Quick Reference Guide, especially regarding navigation, filtering, and user-friendliness. PJM: some suggestions were for more explanatory text, others for less. Improved navigation, filtering, faceting work pending html deployment environment on bdq.tdwg.org
Applicability to Standards Beyond DwC
• (Done) Line 836: Stephen Formel notes the documentation implies the standard is for Darwin Core but does not state this clearly. AC: Wording added to Introduction and to the User's GuidePJM: Text "initially focused on Darwin Core" in landing page for the standard, "suite of Tests initially mapped to key Darwin Core terms" to the bdqtest guide, "initially primarily Darwin Core Terms" in the users guide.
• (Addressed) Line 650: Sophie Parmelon asks if the standard is applicable outside the biodiversity field.
Significance: Questions about the scope and applicability of the standard are raised in more than one place. Comment: AC: Answered by additional words in User's Guide and Introduction
Summary Table
Duplicated Issue Example Line Numbers (from Review Document)
Use Case terminology/definition 207, 240, 641, 657, 881
Broken/hard-to-find links 613, 622, 430
Typos/spelling errors 627, 394–402, 415
Documentation structure/redundancy 332, 580, 568, 209
Test types/naming conventions 248, 202, 850, 878
Quick Reference Guide usability 201, 348, 520, 884
Applicability to other standards 836, 650
These are a list of actionable items from the Review for @Tasilee, @ArthurChapman, @tucotuco, @chicoreus and @ymgan to discuss and address before resubmission of BDQ. Issues requiring open discussion and feedback will be created as separate GitHub issues linked to from this issue.
Basics: Base documents under https://github.com/tdwg/bdq/tree/master/tg2/_build_review. Duplicated issues from Review at bottom of this posting.
NOTE: All but a few of the edits at this stage (2026-03-03) have been applied to Word document versions (to make use of Track Changes) of the markdown files from GitHub and have not been ported back to GitHub. The links below are to the ORIGINAL GitHub documents.
Easily Editable Issues (Lee etc)
Writing Style (John to ponder)
Introduction (The Biodiversity Data Quality Standard) - Guide to Guides https://github.com/tdwg/bdq/blob/master/tg2/_review/index.md (Lee)
A Guide to Guides (Introduction as above intro document. (Lee)
BDQ Tests and Assertions (Lee) https://github.com/tdwg/bdq/blob/master/tg2/_review/docs/bdqtest/index.md
Quick Reference Guide https://tdwg.github.io/bdq/terms/bdqtest/#780480ff-8c4a-4276-aaca-cbd1248de9fa (John)
Test Suite (Paul and Lee)
BDQ User's Guide (https://github.com/tdwg/bdq/blob/master/tg2/_review/docs/guide/users/index.md) (Arthur)
Fitness for Use Framework Ontology Guide https://github.com/tdwg/bdq/blob/master/tg2/_review/docs/guide/bdqffdq/index.md#usecase (Paul and Arthur)
BDQ Implementer's Guide (https://github.com/tdwg/bdq/blob/master/tg2/_review/docs/guide/implementers/index.md) (Paul)
OTHER ISSUES
BDQ Controlled Vocabulary List of Terms (Paul)
(PJM: Fixed as bdq:ParameterizedTest) ~~and 8 cases of "bdq:ParameterizedTest" to "bdq:Parameter Test"~~ (PJM: Not the term, combines label syntax with bdq:namespace, and isn't an appropriate label for the term). AC: But Paul - "ParameterizedTest" does not occur as a term in the bdq: (now bdqval:) namespace - only as comments throughout the ontology.BDQ Empty
PJM: Fixed by phrasing the definitions more clearly and identically, except with true and false switched, original phrasing was difficult to parse.Link to Other Standards (John, Paul)
PJM: Some text added on DwC-DP to bdqtest: guide, also needed in implementers guide. Need to add text on the data quality vocabulary, particularly in reference to the bdqdim dimension vocabulary.resolved in BDQ Review - Discuss relationship of BDQ to the W3C Data Quality Vocabulary. #333 and BDQ Review - added text on DwC-DP needs checking. #334PJM: Added discussion of data quality vocabulary, Prov-O, DCAT and metadata about tests results to the bdqffdq guide. Added a dqv: term to the annotation example.Name Spaces (John, Paul)
(PJM): Could use bdqo with o for ontology, bdqu: seems odd as u suggests user. We likely don't want two prefixes for the same namespace. Pronouncing as as bdq ffdq has worked for us.PJM: Several other suggestions out there, difficulty is that one is non-trivial to change, as it is embedded in external implementation systems and would break them unless they also update.Miscellaneous comments (Arthur)
Comment: AC: This has been addressed in documents as editing proceeds - addressed in User's Guide, Introduction and BDQ Tests and Assertions so farPJM: Unclear about why the reviewer raised this issue, all sections are explicitly marked as normative or non-normative in the section headings, (though there as some new ones in the tutorial we need to add non-normative to), and there are consistent status of the content of this document statements in each document, and explicit disclaimers of examples.PJM: fixed headings in the tutorial. All headings in all the documents now have a (normative) or (non-normative) marker at the end of the heading.Response:AC - this has been addressed in the User's Guide and a brief note placed in the IntroductionPJM: language "initially focused on Darwin Core" used in several places. Explicit domain neutral statement added to the bdqffdq guide.[**Response AC** - It is not clear what is meant here - Paul?]PJM: This appears to just be a pasted link to the owl file, not an an issue.PJM: Unclear what the action item is here.Permission granted by Stan/Dave Bloom - Matt Blisset currently addressing in conjunction with @chicoreus and @tucotuco )Test instance of rs.tdwg.org for BDQ infrastructure#99Duplicated Issues from Reviews
Approach:
I carefully reviewed the actionable items and comments in the document to identify any issues that are mentioned more than once, either verbatim or in slightly different wording. Below, I list each duplicated issue, quoting the relevant line numbers and summarizing the duplication.
Duplicated Issues Identified
Terminology Consistency: “Use Case” Definition and Usage
• Line 240: Melissa Liu requests replacing “usecase” with “use case” and standardizing “UseCases” to “Use Cases.”
• Line 207: Melissa Wiu notes that the term “Use Case” should be defined more explicitly to avoid ambiguity.
• Line 641: Sophie Parmelon comments that actual use case files are not easily found.
• Line 657: Sophie Parmelon suggests providing more use cases or more exhaustive ones.
• Line 881: Stephen Formel and Melissa Wiu both mention the need for a “guide to the guides” and mapping user roles to guides, which relates to clarifying use case entry points.
Significance: The need for consistent terminology and clear definition of “Use Case” appears in multiple places, both as a terminology issue and as a documentation/navigation issue.
PJM: We have adopted the convention of `Term Label`, or `namespace:TermLocalName` consistently, checking all instances of `UseCase` to change to `Use Case`, similarly for other labels that contain spaces(Done) Broken or Hard-to-Find Links
• Line 613: Sophie Parmelon lists several broken links from the main GitHub repo page.
• Line 622: Sophie Parmelon lists more broken links from the TG2 (tests and assertions) repo page.
• Line 430: Rukaya Johaadien notes broken URLs in AuthoritiesDefaults for VALIDATION_COORDINATESTERRESTRIALMARINE_CONSISTENT.
Significance: Broken or inaccessible links are reported in several sections, indicating a recurring issue with documentation navigation and resource accessibility.
PJM: Script written to check internal links, run regularly during revisions, currently at zero broken internal links.PJM: External links checked and updated.Typos and Spelling Errors• Line 627: Sophie Parmelon points out typos in BDQ supplemental information.
• Lines 394–402: Rukaya Johaadien lists multiple spelling errors (e.g., “Amendement,” “Fittness,” “captialized,” “Vaildation,” etc.).
• Line 415: Rukaya Johaadien notes malformed strings and inconsistent key/value patterns, which often stem from typographical errors.
Significance: Typos and spelling inconsistencies are highlighted by multiple reviewers across different sections, showing this is a widespread issue.
PJM: We've searched for and corrected instances of typos and spelling errors identified by the reviewers in all documents, run aspell on templates, asked github copilot to find spelling errors and typos, proofread more, and iteratively checked as we have rewritten text in response to the reviewers.(Done) Documentation Structure and Redundancy
• Line 332: Rukaya Johaadien comments on redundancy in documentation.
• Line 580: Sophie Pamerlon and others mention that documentation is complex, redundant, and could be more concise.
• Line 568: Sophie Pamerlon suggests clearer, more concise, and user-oriented documentation.
• Line 209: Melissa Wiu notes the lack of clear designation between normative and non-normative sections, which relates to structural clarity.
Significance: Concerns about documentation structure, redundancy, and clarity are echoed by several reviewers, indicating a need for a more streamlined and user-friendly approach.
PJM: Addressed: normative and non-normative text from bdqffdq landing page, bdqtest landing page, bdqffdq guide, bdqtest guide, and standard landing page combined into bdqffdq guide and bdqtest guide, both renamed to reflect "Context and Use". Redunancy between these two pages and the implementer's and user's guide remains and is intentional.Test Types and Naming Conventions
• (Done) Line 248: Melissa Liu requests defining technical terms like “Validation,” “Issue,” “Measure,” and “Amendment” where they first appear.
Comment: AC: Will be addressed by link terms in Tests to Glossary• Line 202: Melissa Wiu suggests providing plain-language explanations of test types in the Quick Reference Guide.
• (DONE) Line 850: Stephen Formel questions why terms are sometimes all caps and sometimes camelCase.
Comment:AC: A paragraph will be included in #1.8 of the Introduction Document?Basically the conventions used in Darwin Core (UpperCamelCase for classes and lowerCamelCase for properties) comes from a long history of capitalization conventions including (at least) 1) logical and philosophical distinctions between universals and particulars, 2) object-oriented programming conventions, 3) UML conceptual modeling practice, and 4) Semantic Web ontology engineering norms. The UPPERCASE convention we have are not names, they are just for labels. I wouldn't think there needs to be any justification for those either. Darwin Core and other standards use a convention where every word is separate and capitalized (so it isn't title case). i think Stephen wants us to change them, not justify them. We'd just have to justify to him why not. Justifications could be 1) they don't have to follow any convention as labels, 2) there is value in immediate recognition as a test label that would be lost otherwise, 3) the refactoring effort doesn't justify losing the one advantage they provide.• (Won't Fix) Line 878: Stephen Formel asks about the need for a general spatial-mask term, which relates to test type clarity.
Significance: The need for consistent naming conventions and clear definitions of test types is raised in multiple places, showing this is a recurring concern.
Quick Reference Guide Usability
• Line 201: Melissa Wiu suggests adding a filter for Use Cases to improve navigation.
• Line 348: Rukaya Johaadien recommends making the Quick Reference Guide more user-friendly and adding filters.
• (Won't Fix) Line 520: Rukaya Johaadien suggests including a sentence on the order of running tests.
• Line 884: Stephen Formel recommends grouping terms for easier browsing.
Significance: Multiple reviewers suggest improvements to the Quick Reference Guide, especially regarding navigation, filtering, and user-friendliness.
PJM: some suggestions were for more explanatory text, others for less. Improved navigation, filtering, faceting work pending html deployment environment on bdq.tdwg.orgApplicability to Standards Beyond DwC
• (Done) Line 836: Stephen Formel notes the documentation implies the standard is for Darwin Core but does not state this clearly.
AC: Wording added to Introduction and to the User's GuidePJM: Text "initially focused on Darwin Core" in landing page for the standard, "suite of Tests initially mapped to key Darwin Core terms" to the bdqtest guide, "initially primarily Darwin Core Terms" in the users guide.• (Addressed) Line 650: Sophie Parmelon asks if the standard is applicable outside the biodiversity field.
Significance: Questions about the scope and applicability of the standard are raised in more than one place.
Comment: AC: Answered by additional words in User's Guide and IntroductionSummary Table
Duplicated Issue Example Line Numbers (from Review Document)
Use Case terminology/definition 207, 240, 641, 657, 881
Broken/hard-to-find links 613, 622, 430
Typos/spelling errors 627, 394–402, 415
Documentation structure/redundancy 332, 580, 568, 209
Test types/naming conventions 248, 202, 850, 878
Quick Reference Guide usability 201, 348, 520, 884
Applicability to other standards 836, 650