How to refer to vocabulary lists?

[MaartenSneepKNMI]

Topic for discussion

I work on the Sentinel 5P project, writing the software that generates level 2 products. In those products we have a link to the standard names vocabulary in a global attribute:

:standard_name_vocabulary = "NetCDF Climate and Forecast Metadata Conventions Standard Name Table (v29, 08 July 2015), http://cfconventions.org/standard-names.html" ;

As you can see from the link, this was done some time ago, and the link has gone 404. I fear that dead links are a fact of internet life. We still would like to refer to the standard name vocabulary in a robust way. This either requires voluntary discipline to keep the URL stable, or more enforced discipline in the form of a DOI for each of the vocabularies (but that allows the underlying URL to move).

• What is the recommendation to refer to the current standard name table? This assumes that the list only gets longer, and that names are not removed, which I think is the case.
• I'm happy to remove the version information from the reference.
• We are preparing for a reprocessing. That is, we don't need to revive the URI that we have at the moment, as long as the new reference is stable.

[davidhassell]

Hi Maarten,

Issue cf-convention/cf-conventions#500 gave us the standard name table version in the XML header (see Appendix B: Standard Name Table Format):

      <conventions>CF-StandardNameTable-80</conventions>

and also pointed out it would be perfectly OK to put this in the Conventions global attribute:

// global attributes:
		:Conventions = "CF-1.13 CF-StandardNameTable-80" ;

However, whilst CF-<VN> is a standardised string in this attribute, CF-StandardNameTable-<VN> is not, so whilst it is pretty clear and obvious what is meant by it, CF does not formally state that CF-StandardNameTable-<VN> always means the standard name table version, and cannot mean anything else (I'm being a bit pedantic! but just wanted to make it clear what the promise is :-)).

[MaartenSneepKNMI]

The goal is to have a reference to a human readable resource in a separate attribute. Of course, if :Conventions = "CF-1.13" ; is present, then the use of the standard name table is implied, regardless of version, and this could (should?) be the current table.

Yes, this is beyond the conventions, and in internal discussions we may conclude that since this is implied by the conventions anyway, that we're better off removing the reference altogether.

[davidhassell]

if :Conventions = "CF-1.13" ; is present, then the use of the standard name table is implied, regardless of version, and this could (should?) be the current table.

I don't think that there's a promise of any particular standard name table version for a given version of CF - after all, there will be multiple version of the standard name table released before CF-1.14 is out. Please correct me if I'm wrong!

For me, :Conventions = "CF-1.13 CF-StandardNameTable-29" ; is the clear way for humans and machines, even if it's unstandardised by the conventions text.

[ChrisBarker-NOAA]

I think a DOI is clearly the way to go.

[speaking as someone that has no idea how do do it ....]

One question -- one DOI for each version? or one DIO for all 1.* versions? WE are commited to not removing any standard names in a point release, so you only need the latest, yes?

NOTE: I have no idea what DOI policy is -- it may well be that it's supposed to point to EXACTLY the same document.

AI says:
"""
Documents with multiple versions generally require a new, unique DOI for each major, citable iteration to ensure proper tracking,, reproducibility, and persistent access. A "concept" or "canonical" DOI can be used to reference all versions, while specific version DOIs should be linked via metadata relations like HasVersion or IsVersionOf. ...
"""

So maybe that's the answer.

[MaartenSneepKNMI]

The DOI for the CF Conventions document as a whole (on Zenodo) has a DOI for each specific version, as well as a generic DOI that always points to the latest release 10.5281/zenodo.14274886. So that part aligns.

The issue that I see is that the (human readable) version of the standard name list is an HTML page with some javascript to search the page (at least I think that is what it does). The cool part is that it is a single file, the hard part is to get something like that on Zenodo and still be functional. I'm not sure Zenodo can (or wants to) serve plain HTML, I think they want (pdf) documents. ECMA-Script is part of the PDF and could potentially deliver the same functionality in a PDF, but I don't have the javascript chops to get that to work (I know there are LaTeX based tools that might be able to help, but that is quite a deep dive).

[ChrisBarker-NOAA]

Asciidoctor can produce PDF, and PDF viewers have search capabilities, so that's not so bad.

Also, IIUC, the DOI can point to our web site for the published version.

CF would have to commit to keeping those up to date, but it could be done.

And/or there could be a link/note in the PDF telling folks where to find the interactive version.

(And even if that changes, I assume search engines will always be available)

[ChrisBarker-NOAA]

I don't think that there's a promise of any particular standard name table version for a given version of CF - after all, there will be multiple version of the standard name table released before CF-1.14 is out. Please correct me if I'm wrong!

For me, :Conventions = "CF-1.13 CF-StandardNameTable-29" ; is the clear way for humans and machines, even if it's unstandardised by the conventions text.

I hadn't noticed that the Standard Name Table was separately versioned.

I see: "The published vocabularies are updated approximately every 1 - 2 months."

So I presume that's when the version is bumped. But that makes a lot of versions -- do we want DOIs / to publish them on Zenodo?

Maybe this is a motivation to have a more incremental approach to versioning -- perhaps go to a date-based version:

2025.02.13

for one updated Feb 13th, 2026.

And then "publish", e.g. make a DOI for, the last one each year:

2025.12.31

Or, if we didn't want to make that much of a change, add apoint release to the current system:

92.1
92.2
92.3

and then, maybe once a year, bump the major version:

93.0 -- and that one gets published.

Third option -- as was expected (by at least some of us) formalize the connection between the CF version and the standard name table -- e.g. a given CF version is tied to a given Standard Name Table version -- with perhaps some way of saying "minimum standard name table version" or something.

Now that I think about it, the current system is a little fuzzy -- is a file CF X.X compliant if it uses standard names that didn't exist when X.X was published? It presumable would not have been compliant and some point, and then, miraculously, it would become compliant if a name it used was added to the standard name table -- that is a bit odd.

"CF-1.13 CF-StandardNameTable-29" ; is the clear way for humans and machines, even if it's unstandardised by the conventions text.

The other option is to standardize a way to specify the Standard Name Table version.

Lots of ideas -- maybe a new discussion is called for.

[MaartenSneepKNMI]

This is a slightly different issue from what I intended. This is more towards the machine readable end of the spectrum, I'm more looking to the human readable side of this reference, and then specifically a doi or hyperlink that my users can follow to reach a page where they can read about a standard_name that we attached to one of our variables. Having this in the Conventions attribute probably assumes more knowledge about netCDF than is frequently available.

[DocOtak]

This really feels like a place where the persistent URI at the NVS could help, if you can reference specific versions of the table. @gwemon if I recall correctly, the ability to view specific past versions of a vocabulary isn't working yet?

[gwemon]

Hi DocOtak - it is fixed! Sorry I forgot to post an update! There is a small section on our homepage at vocab.nerc.ac.uk: "Each NVS collection is versioned and the version identifier is recorded using the owl:versionInfo property. While only the current version is exposed via the user interface, all historical versions remain resolvable via persistent URLs. To access a specific version, replace /current/ in the collection URI with the required numeric version identifier (e.g. /3/). Example: http://vocab.nerc.ac.uk/collection/L05/3/ Opening a link to a specific version of a collection, will return the RDF/XML serialisation directly."

[ChrisBarker-NOAA]

This is more towards the machine readable end of the spectrum, I'm more looking to the human readable side of this reference, and then specifically a doi or hyperlink that my users can follow to reach a page where they can read about a standard_name that we attached to one of our variables

Sorry to get a bit off-track -- to bring it back, yes, we may want to do more for versioning, etc of the standard name table, but regardless, and first, there should be a persistant URI.

I"m not sure what: " the persistent URI at the NVS " is, but if that's what it sounds like then that should do it, yes.

If not, and maybe even if so, we should do a DOI.

We have one for the Convention doc -- is it that much a lift to do the same for the standard name table?

I do see that it's not asciidoc, it's XML, so making a PDF might be a bit of a lift. But a DOI can point to a web site, can't it?

[DocOtak]

DOIs can point to anything really, though they should point to a landing page with links to the actual content.

I'd strongly prefer to "bless" the NVS somehow rather than roll our own solution for this.

[MaartenSneepKNMI]

I've tried to write a quick script to format the standard name table into a pdf using latex. I've tried to turn hyperlinks and DOIs into active links in the document, but not all are successful for various reasons. I won't dive into this any further now unless it is decided that a pdf version is worthwhile to pursue.

The script writes a latex file to stdout, redirect that to file and process with pdflatex to obtain the pdf file.

• cf-standard-name-table.pdf
• print_std_names.py

[alko-k]

Regarding cf standard names on the NVS:
This is the human readable cf standard names list: https://vocab.nerc.ac.uk/collection/P07/current/
The versioned list is machine readable and will be automatically downloaded: https://vocab.nerc.ac.uk/collection/P07/34/
It is also possible to reference the versioning of individual concepts e.g. https://vocab.nerc.ac.uk/collection/P07/current/CFSN0020/2/

[MaartenSneepKNMI]

Thank you. I think the first link will serve our purposes. Because of the machine readable aspect I assume some effort is made to keep the URL stable to avoid breaking all kinds of applications. Please let me know if that assumption is very wrong.

[DocOtak]

IIRC, it not just some effort, I thing these URIs have guaranteed stability/persistence, as far as anything is actually persistent on the internet.

[DocOtak]

I don't know if the stability guarantee applies to this, but the CF names are treated special in NVS:

• (whole collection) https://vocab.nerc.ac.uk/standard_name/
• (example) https://vocab.nerc.ac.uk/standard_name/sea_water_practical_salinity/

I've successfully made a JSON-LD context for the xarray dict representation of a netCDF file that was able to basically "just work" without altering the actual structure of the netCDF. The hope was to use this to enable discoverability, but I got quite sidetracked with other tasks.