Standard names: Add "Conventions" string to the standard name xml table header

[larsbarring]

The xml version of the table (available for download from this page) currently includes the following header information:

       <version_number>80</version_number>
       <last_modified>2023-02-07T15:39:41Z</last_modified>
       <institution>Centre for Environmental Data Analysis</institution>
       <contact>[email protected]</contact>

Suggestion:
Include a "Conventions string" in this header, i.e. a string that defines how the standard name table is to be specified in the NetCDF global Conventionsattribute.

For example:

If the header includes the line

      <Conventions_string>CF-StdNameTable-80</Conventions_string>

it would be easy for some software to include this information in the Conventions attribute to give the following ncdump -houtput:

// global attributes:
		:Conventions = "CF-1.10 CF-StdNameTable-80" ;

Without this enhancement only the table version is know, which means that users/software either cannot add this information to the Conventions atribute, or have to "invent" a non-standardised string, which is contrary to the intended use.

[larsbarring]

@japamment Would this issue be suited for the cf-conventions repo?

[larsbarring]

Following @japamment's suggestion I am migrating this to the cf-conventions repo.

[erget]

Hi folks, @DocOtak reached out from Antarctica, where the Internet's not so fast - I'm relaying on his behalf :) Btw looks like he's doing really well in the extreme south, it got me pretty jealous!

• Are xml tags case sensitive? nothing else seems to have capital letters
• Why include the data type? i.e. why not just use <conventions>whatever is agreed to here</conventions>
• Why abbreviate Std? Use the whole thing CF-StandardNameTable-80

I might post some more stuff for him while he's away, but that's subject to the availability of time and email reception.

Happy holidays all :) 🎄

[larsbarring]

Just to quickly respond to the points:

• Are xml tags case sensitive? nothing else seems to have capital letters
• Why include the data type? i.e. why not just use whatever is agreed to here

--- I don't know about case sensitivity. I am happy to change to whatever is agreed to here because it is simpler.

• Why abbreviate Std? Use the whole thing CF-StandardNameTable-80

-- This was just to keep with the general style of abbreviating individual items in the Conventions attribute. But If the general view go for the longer variant I am happy with that.

Seasons greetings :-)

[larsbarring]

While the exact text/string value to be used for the standard name conventions string is not settled I am nevertheless opening a PR to get this going. It will be easy to change the text once the string is agreed.

[larsbarring]

And while preparing PR #503 I noticed that the current text in Appendix B is not quite up-to-date with the actual content of the standard name xml files . In particular the version_number is missing. Hence I also added this in the same PR. I invited @japamment and/or @feggleton as reviewers of the PR. Many thanks.

[davidhassell]

Thanks for putting this together, Lars. It looks good to me.

I would probably prefer CF-StandardNameTable-83, or even CF-StandardNames-83, but I have no strong opinion on this and would also be happy with the proposed CF-StdNameTable-83.

[JonathanGregory]

Dear @larsbarring

Thanks very much for this issue and PR.

Please excuse my asking a question first about the principle. I agree with your proposal that it's useful to define a standard Conventions string to indicate the standard name table version, but I wonder whether we need to state it explicitly as an extra tag in the xml file, if it is bound to take the form CF-StdNameTable-version. We could instead state this rule for producing the Conventions string in the CF conventions document.

If we do include this new xml tag, I would prefer not abbreviating "standard", like @DocOtak and @davidhassell, because I think the full word is clearer. (For the same reason, we use very few abbreviations in the standard names themselves.) Also like @DocOtak, I would prefer lower case. I don't know whether xml is case-sensitive, but all the standard names are entirely lower case, and the CF convention says its controlled keywords are case-insensitive. I think that mixed case is more likely to lead to mistakes.

For the name of the tag, I would suggest conventions instead of conventions_string. Since it's obviously a string, and the netCDF Conventions attribute is a string, and everything in xml is a string, I feel that string is unnecessary.

Thanks for your patience in considering these points.

Best wishes

Jonathan

[larsbarring]

@JonathanGregory in response to your first point, I think there is merit to have a ready-made string that any software, or human, can easily access/understand, rather than require each and everyone implement/being aware of the exact rules laid down in "a document somewhere" ;-). This is a small thing within CF community but potentially a big thing in a larger context.

I am happy to go with the slightly longer CF-StandardNameTable-version_ preferred by @DocOtak, @davidhassell and @JonathanGregory. And I think that "Table" should be included to make it clear that it is the standard name table and nothing else. Also I am happy to drop the "_string" part of the tag name.

The PR has been updated accordingly.

[JonathanGregory]

Thanks for your flexibility, @larsbarring. I accept the first point! Would you find CF-standardnametable-version acceptable, or perhaps CF_standard_name_table_version - which actually looks more like a standard name, so it's self-referential in character. 😄

[JonathanGregory]

Being ignorant about this, I have just searched on Google, and learned that xml tags are case-sensitive, and so is the text of the elements.

[larsbarring]

@JonathanGregory The netCDF global attribute Conventions is where the Climate and Forecasting Conventions interact with the outside world, in the sense that the content and formatting is not [only] dictated by us. The main aim is to point users to various conventions regarding how to interpret the specific content and formats of various elements of the data and metadata. Of course you already know this, but the point I want to make is that for this particular attribute we should look at what is customary outside the CF world, because the the whole point with this attribute is that it should not follow what any one convention may have as its specific rules or customary habits.

Based on this, my point of departure when making the proposal was (and still is) as follows:

• The value of the attribute should be easy for human to read and understand, still succinct. Thus a balance is needed between explicit and detailed (and avoiding unnecessary acronyms etc) while at the same time not being too long.
• It should in general follow patterns and styles used by others.

Here are a couple of examples that I quickly gathered from https://www.unidata.ucar.edu/software/netcdf/conventions.html (I am sure there are plenty other):

Conventions = "CF-1.6, OceanSITES-1.5, ACDD-1.2"
Conventions = "NCAR-RAF/nimbus"
Conventions = "ACDD-1.3"

where the first example refers to three separate conventions.

I think that the suggested CF-StandardNameTable-version, which was supported by several, including yourself, meet these criteria. It is easy to read/understand and follows the general pattern. The two you suggested CF-standardnametable-version is just less readable, e.g. as all this is dealing with metadata an outside reader might for a moment be diverted into wondering what "metable" means. And CF_standard_name_table_version (while following the standard name style) does not follow the general style. And using a specific style that might not be known until having taken on board the convention that the reference points to is not optimal.

Hence I maintain that on balance CF-StandardNameTable-version is a good suggestion.

[davidhassell]

I'm happy with CF-StandardNameTable-, and including it explicitly in the XML file.
David

[JonathanGregory]

Dear @larsbarring

Thanks for your explanations and your patience. It's good to have the reasons. In that case, I'm happy to support your proposal of conventions="CF-StandardNameTable-version" in the xml.

Best wishes

Jonathan

[larsbarring]

Thanks Jonathan for you flexibility, and all for your input and support. With this I think we can start the three weeks countdown.

Also, I would like to note that the PR implements the change in appb.adoc but a corresponding change have to be implemented in the xsdfile referred to in the standard name xml file (not in this repo).

[larsbarring]

See cf-convention.github.io/#433 regarding the last sentence in my previous comment.

[larsbarring]

The three week countdown period (started on January 10) has has now passed with good margin. Can we merge the associated PR, @davidhassell would you mind?

[JonathanGregory]

It would be an honour for me to do it, hoping that @davidhassell doesn't mind. Thanks, @larsbarring.