apparent contradiction about recommendation of standard_name or long_name

[JonathanGregory]

Topic for discussion

In commenting on conventions issues #501 (now closed as completed), @martinjuckes drew attention to an apparent inconsistency. Section 3.2 says, "it is highly recommended that either [the long_name attribute] or the standard_name attribute defined in the next section be provided for all data variables and variables containing coordinate data." Both attributes are optional, and CF isn't recommending the standard_name more than the long_name in this sentence. That is consistent with Section 1.4 (the Overview), where it says

The long_name and standard_name attributes are used to describe the content of each variable. For backwards compatibility with COARDS neither is required, but use of at least one of them is strongly recommended.

This lack of preference between long_name and standard_name seems to be contradicted by two other sentences. In the preamble of Section 4, we have

Four types of coordinates receive special treatment by these conventions: latitude, longitude, vertical, and time. We continue to support the special role that the units and positive attributes play in the COARDS convention to identify coordinate type. We extend COARDS by providing explicit definitions of dimensionless vertical coordinates. The definitions are associated with a coordinate variable via the standard_name and formula_terms attributes. For backwards compatibility with COARDS use of these attributes is not required, but is strongly recommended.

and Section 1.4 says

To achieve the goal of being able to spatially locate all data values, this convention includes the definitions of common dimensionless vertical coordinates in Appendix D, Parametric Vertical Coordinates. These definitions provide a mapping between the dimensionless coordinate values and dimensional values that can be uniquely located with respect to a point on the earth's surface. The definitions are associated with a coordinate variable via the standard_name and formula_terms attributes. For backwards compatibility with COARDS use of these attributes is not required, but is strongly recommended.

The final sentence in each of those pieces of text apparently says that the standard_name is strongly recommended, implying it's preferred to the long_name. My reading of those sentences, in context, is that "strongly recommended" actually refers to the use of the convention of Section 4.3.3, "Parametric Vertical Coordinate", which involves standard_name and formula_terms, for those kinds of vertical coordinate where it's relevant. It is not saying that standard_name is "strongly recommended" (disregarding long_name) in all cases, so it's not inconsistent with Section 3.

What do you think, @martinjuckes and anyone else? Is my reading correct?

In any case, I think we ought to clarify this. If my understanding is correct, this is a defect in the wording (a lack of clarity), which we can repair. If there is truly an inconsistency, sorting it out might be a change to the convention. Therefore I've opened this discussion to decide whether it should be an enhancement or a defect issue of conventions. (I've also opened issue #515, where we can deal with it, when we've decided what to do.)

[davidhassell]

Thanks, Jonathan.

I would agree with your interpretation that that particular recommendation refers only to parametric vertical coordinates, i.e. that would make it a defect.

[martinjuckes]

Hi Jonathan, given the exact repetition of the phrase "For backwards compatibility with COARDS use of these attributes is not required, but is strongly recommended." in section 4.3.3, I agree with your interpretation.

I tried checking to see what the COARDS convention actually says about standard names and drew a blank. The page we reference (https://ferret.pmel.noaa.gov/Ferret/documentation/coards-netcdf-conventions) does not mention standard names or formula terms and only provides a broken link (ftp://ftp.unidata.ucar.edu/pub/netcdf/Conventions/COARDS) for further information. But that is a separate issue -- I've notified the ferret web master.

I agree with you suggestion of dealing with our issue by clarifying the text, e.g. ".... strongly recommended for dimensionless vertical coordinates".

[JonathanGregory]

Thanks for following this up, @martinjuckes. I hadn't thought about the COARDS remark. Actually, I think it may be misleading. The CF convention of formula_terms and standard_name is an addition to COARDS. Software that understands COARDS but not CF is unable to use formula_terms or standard_name, but it can still identify vertical coordinates by COARDS methods, since we uphold the units and positive conventions for that reason. If CF required formula_terms and standard_name for dimensionless vertical coordinates, CF-netCDF files would still comply with COARDS. COARDS netCDF files that lacked those attributes (where relevant) would not be CF-compliant if they were mandatory in CF, but I don't think COARDS alone is a reason for making them optional. Perhaps it was 20 years ago! I can't remember. In any case, I suggest we remove, "For backwards compatibility with COARDS" here. Would you be happy with that?

[JonathanGregory]

In view of our agreement that this is a defect, I have returned to the issue, where I have proposed changes to remedy the problem. Please put any comments there. Thanks.

[JonathanGregory]

The issue has now been concluded with an agreed change.