Declaring normative content

[baskaufs]

In the past, TDWG had "normative" and "non-normative" documents. That all went away when the Standards Documentation Specification (SDS) came into force. Section 3.2.1 says:

The normative and non-normative parts of standards MUST be clearly labeled as such. If all of the content of a document is normative, this MUST be stated in the introduction to the document. If a single document contains both normative and non-normative content, material in a single section SHOULD be of a single type. The introduction SHOULD state that content is normative unless otherwise noted and headings SHOULD indicate if material in that section is non-normative.

It is also permissible to indicate in the introduction that content of a particular type (e.g. examples or diagrams) is non-normative.

For an example, see Section 1.1 of the Audubon Core Term List document.

In Darwin Core, we don't have a similar human-readable document defining the terms and saying what parts of that document are normative. Rather, we have the quick reference guide, a document that is outside of the standard itself and therefore not subject to the requirements for standards documents, and the so called "normative document", a CSV file that contains the metadata fields that are (mostly) considered normative and excluding stuff like notes and examples that aren't normative.

I don't have a problem with that approach. However, if I were a newbie with Darwin Core, I'm not sure it would be obvious to me how this all works. I would like to see some text at least in the Quick Reference Guide and maybe also on the DwC landing page and repo landing page that flesh this out a bit. Perhaps some statement on the Quick Reference Guide like "Term definitions are normative. Comments and examples are informative. " and on the landing pages changing the description of the normative document to "A CSV file with the full version history of Darwin Core terms. This file contains all of the term metadata that are considered normative."

[sacrevert]

Speaking as a newbie to Darwin Core, I have just been confused by this. For example, for organismQuantityType, the quick reference guide gives some examples, but omits some that one would intuitively expect (e.g. '%biomass' is listed, but not '%cover', widely used in plant and marine ecology). The normative CSV file mentioned above seems to list the same three examples as the quick reference guide, but from what @baskaufs says above this file is normative (although presumably not exhaustive with respect to vocab). Anyway, the result is that I am confused about the process for creating and using new vocab items within terms, such as my '%cover' example above.

[baskaufs]

This is something we need to work on. People have noted the lack of an easy-to-read Darwin Core specification document that clearly lays out what is normative and what is not. I will try to bring this up with the DwC Maintenance Group to see if we can fix it.

One comment for now: I think the general consensus has been reached that examples are not normative. So the presence of some examples and the absence of others shouldn't be construed to have too much significance. Optimally, there would be some kind of "best-practices" guide outside of the standard that would provide guidance to people in using the terms. There is a much higher demand for such documents than the supply of people who are willing to take the time to write them. That isn't an excuse, just a statement of fact. We need to keep working on that.

[sacrevert]

There is a much higher demand for such documents than the supply of people who are willing to take the time to write them. That isn't an excuse, just a statement of fact.

Entirely understood. Thanks for all the efforts of the community to date. I hope my comment will be taken as a useful example of where the understanding of a newcomer might falter based on the current resources, rather than a complaint. Many thanks for response.

[baskaufs]

Thank you for taking the time to write it! This kind of feedback is really useful.

[baskaufs]

I think this is fixed with the completion of https://github.com/tdwg/dwc/milestone/10?closed=1