Attribute Convention for Data Discovery 1-3

       DRAFT - Not ready for use

Context

Document

This is the Attribute Convention for Data Discovery (ACDD).

Version and Status

This version is designated as Version 1.3. It is a Working Draft.

The page Attribute Convention for Data Discovery (ACDD) always points to the current released version of the Convention. The version number at the top of the resulting page will show the current version.

See the ACDD category page for information on the history and maintenance of this convention.

Development

For development versions of the ACDD, please see the page Attribute Convention for Data Discovery Working.

Overview

This document describes attributes recommended for describing a NetCDF dataset to discovery systems such as Digital Libraries. THREDDS and other tools can use these attributes for extracting metadata from datasets, and exporting to Dublin Core, DIF, ADN, FGDC, ISO 19115 and other metadata formats. This will help systems and users locate and use data efficiently.

Alignment with NetCDF and CF Conventions

The NetCDF User Guide (NUG) provides basic recommendations for creating NetCDF files; the NetCDF Climate and Forecast Metadata Conventions (CF) provides more specific guidance. The ACDD builds upon and is compatible with these conventions; it may refine the definition of some terms in those conventions, but does not preclude the use of any attributes defined by the NUG or CF.

The NUG does not require any global attributes, though it recommends and defines two, title and history; CF specifies many more. ACDD 1.3 adopts all CF 1.6 global attributes with the exception of 'institution'; we specify 'creator_institution' and 'publisher_institution', to provide more provenance information. We also modify the syntax of the 'Conventions' attribute; we adopt the NUG recommendation to supply all conventions in a single attribute. This change has been approved by the CF Conventions Committee and will be part of CF 1.7, which is not yet published.

Attribute Crosswalks

Many of these attributes correspond to general discovery metadata content, so they are available in many metadata standards. This Attribute_Convention_for_Data_Discovery_(ACDD)_Mappings page includes a crosswalk to THREDDS, OGC CSW, ISO 19115-2 and Rubric Categories.

Additional Metadata: metadata_link attribute

The netCDF metadata model is focused on providing "use metadata" for the data included in the file (or granule). Other metadata dialects (i.e. ISO 19115) can provide information about collections and more details about the dataset. If additional metadata exists, you can make users aware of it by adding a global attribute named "metadata_link" to the netCDF file. The value of this attribute is a URL that gives the location of the more complete metadata.

Maintenance of Metadata

ACDD attributes, like all NetCDF attributes, characterize their containing (parent) granules. As NetCDF data are processed (e.g., through subsetting or other algorithms), these characteristics can be altered. The software or user processor is responsible to update these attributes as part of the processing, but some software processes and user practices leave them unchanged. This affects both consumers and producers of these files, which comprises three roles:

• developers of software tools that process NetCDF files;
• users that create new NetCDF files from existing ones; and
• end users of NetCDF files.

NetCDF file creators (the first two roles) should ensure that the attributes of output files accurately represent those files, and specifically should not "pass through" any source attribute in unaltered form, unless it is known to remain accurate. NetCDF file users (all three roles) should verify critical attribute values, and understand how the source data and metadata were generated, to be confident the source metadata is current.

The ACDD geospatiotemporal attributes present a special case, as this information is already fully defined by the CF coordinate variables (the redundant attributes are recommended to simplify access). Errors in these attributes will create an inconsistency between the metadata and data of the granule or file. The risk of these 'inconsistency errors' is highest for files that are aggregated into longer or larger products, or subset into shorter or smaller products, such as files from numerical forecast models and gridded satellite observations. For this reason, some providers of those data types may choose to omit the ACDD geospatiotemporal attributes from their files. If the ACDD geospatiotemporal attributes are present, checking them against the CF coordinate variables can serve as a partial test of the metadata's validity.

ISO 8601 Recommended Formats

The ACDD specifies ISO 8601:2004 date and time formats for its temporal attributes. ACDD strongly encourages the use of the 'extended' format date-time, in the form

YYYY-MM-DDThh:mm:ss<zone>

(although ss, mm, and hh can be omitted, and <zone> can be Z, ±hh:mm, or ±hh). Per the standard, the shortened or basic format, which omits the - and : separators, "should be avoided in plain text."

For duration attributes, again the extended form is strongly encouraged for readability:

P[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].

If for some reason the strongly encouraged formats can not be used, other compatible formats are acceptable.

Global Attributes

Highly Recommended

Attribute	Description
title	A short phrase or sentence describing the dataset. In many discovery systems, the title will be displayed in the results list from a search, and therefore should be human readable and reasonable to display in a list of such names. This attribute is also recommended by the NetCDF Users Guide (NUG) and the CF conventions.
summary	A paragraph describing the dataset, analogous to an abstract for a paper.
keywords	A comma-separated list of key words and/or phrases. Keywords may be common words or phrases, terms from a controlled vocabulary (GCMD is often used), or URIs for terms from a controlled vocabulary (see also "keywords_vocabulary" attribute).
Conventions	A comma-separated list of the conventions that are followed by the dataset. For files that comply with this version of ACDD, include the term ACDD-1.3. (This attribute is also defined in NUG 1.7.)

Recommended

Attribute	Description
id	An identifier for the data set, provided by and unique within its naming authority. The combination of the "naming authority" and the "id" should be globally unique, but the id can be globally unique by itself also. IDs can be URLs, URNs, DOIs, meaningful text strings, a local key, or any other unique string of characters. The id should not include blanks.
naming_authority	The organization that provides the initial id (see above) for the dataset. The naming authority should be uniquely specified by this attribute. We recommend using reverse-DNS naming for the naming authority. For example, naming_authority="edu.ucar.unidata"
cdm_data_type	The organization of the data, as derived from the Common Data Model's Scientific Data layer and understood by THREDDS (this is a THREDDS "dataType"). One of point, profile, section, station, station_profile, trajectory, grid, image, or swath. Please note that this is different from the CF NetCDF attribute 'featureType' that indicates a Discrete Sampling Geometry file - for guidance on those terms, please see the NODC guidance.
history	Describes the processes/transformations used to create this data; can serve as an audit trail. This attribute is also in the NUG: 'This is a character array with a line for each invocation of a program that has modified the dataset. Well-behaved generic netCDF applications should append a line containing: date, time of day, user name, program name and command arguments.' To include a more complete description you can append a reference to an ISO Lineage entity; see NOAA EDM ISO Lineage guidance.
source	The method of production of the original data. If it was model-generated, source should name the model and its version. If it is observational, source should characterize it. This attribute is also in CF Conventions. E.g. temperature from CTD #1234; world model v.0.1.
comment	Miscellaneous information about the data, not captured elsewhere. This attribute is also in CF Conventions.
date_product_modified	The date on which any of the provided content, including data, metadata, and presented format, was last created or changed. Use ISO 8601 date format.
date_values_modified	The date on which the provided data values were last created or changed; excludes metadata and formatting changes. Use ISO 8601 date format.
creator	The name of the person principally responsible for originating this data.
creator_email	The email address of the person principally responsible for originating this data.
publisher	The person responsible for the data file or product, with its current metadata and format.
publisher_email	The email address of the person responsible for the data file or product, with its current metadata and format.
processing_level	A textual description of the processing (or quality control) level of the data.
acknowledgement	A place to acknowledge various type of support for the project that produced this data.
geospatial_bounds	Describes geospatial extent using any of the geometric objects (2D or 3D) supported by the Well-Known Text (WKT) format.
geospatial_lat_min	Describes a simple lower latitude limit; may be part of a 2- or 3-dimensional bounding region. Geospatial_lat_min specifies the southernmost latitude covered by the dataset.
geospatial_lat_max	Describes a simple upper latitude limit; may be part of a 2- or 3-dimensional bounding region. Geospatial_lat_max specifies the northernmost latitude covered by the dataset.
geospatial_lon_min	Describes a simple longitude limit; may be part of a 2- or 3-dimensional bounding region. Geospatial_lon_min specifies the westernmost longitude covered by the dataset. Cases where geospatial_lon_min is greater than geospatial_lon_max indicate the bounding box extends from geospatial_lon_max, through the longitude range discontinuity meridian (either the antimeridian for -180:180 values, or Prime Meridian for 0:360 values), to geospatial_lon_min; for example, geospatial_lon_min=170 and geospatial_lon_max=-175 incorporates 15 degrees of longitude (ranges 170 to 180 and -180 to -175).
geospatial_lon_max	Describes a simple longitude limit; may be part of a 2- or 3-dimensional bounding region. Geospatial_lon_max specifies the easternmost longitude covered by the dataset. Cases where geospatial_lon_min is greater than geospatial_lon_max indicate the bounding box extends from geospatial_lon_max, through the longitude range discontinuity meridian (either the antimeridian for -180:180 values, or Prime Meridian for 0:360 values), to geospatial_lon_min; for example, geospatial_lon_min=170 and geospatial_lon_max=-175 incorporates 15 degrees of longitude (ranges 170 to 180 and -180 to -175.
geospatial_vertical_min	Describes a numerically smaller vertical limit; may be part of a 2- or 3-dimensional bounding region. If geospatial_vertical_positive is up ('altitude' orientation), the geospatial_vertical_min attribute specifies the location closest to the earth's center covered by the dataset. If geospatial_vertical_positive is down ('depth' orientation), the geospatial_vertical_min attribute specifies the location furthest from the earth's center covered by the dataset.
geospatial_vertical_max	Describes a numerically larger vertical limit; may be part of a 2- or 3-dimensional bounding region. If geospatial_vertical_positive is up ('altitude' orientation), the geospatial_vertical_min attribute specifies the location furthest from the earth's center covered by the dataset. If geospatial_vertical_positive is down ('depth' orientation), the geospatial_vertical_min attribute specifies the location closest to the earth's center covered by the dataset.
geospatial_vertical_positive	One of 'up' or 'down'. If up, vertical values are interpreted as 'altitude', with negative values corresponding to below the reference datum (e.g., under water). If down, vertical values are interpreted as 'depth', positive values correspond to below the reference datum.
time_coverage_start	Describes the time of the first data point in the data set. Use the ISO 8601:2004 date format, preferably the extended format as recommended above.
time_coverage_end	Describes the time of the last data point in the data set. Use ISO 8601:2004 date format, preferably the extended format as recommended above.
time_coverage_duration	Describes the duration of the data set. Use ISO 8601:2004 duration format, preferably the extended format as recommended above.
time_coverage_resolution	Describes the targeted time period between each value in the data set. Use ISO 8601:2004 duration format, preferably the extended format as recommended above.
license	Provide the URL to a standard or specific license, enter "Freely Distributed" or "None", or describe any restrictions to data access and distribution in free text.

Suggested

Attribute	Description
contributor_info	The name and role of any individuals, projects, or institutions that contributed to the creation of this data. May be presented as free text, or in a structured format compatible with conversion to ncML (e.g., insensitive to whitespace).
date_product_available	The date on which this data file or product was produced or distributed. Use the ISO 8601:2004 date format, preferably the extended format as recommended above. While this date is like a file timestamp, the date_product_modified and date_values_modified should be used to assess the age of the contents of the file or product.
geospatial_lat_units	Units for the latitude axis described in "geospatial_lat_min" and "geospatial_lat_max" attributes. These are presumed to be "degree_north"; other options from udunits may be specified instead.
geospatial_lat_resolution	Information about the targeted spacing of points in latitude. Recommend describing resolution as a number value followed by the units. E.g. 10 meters
geospatial_lon_units	Units for the longitude axis described in "geospatial_lon_min" and "geospatial_lon_max" attributes. These are presumed to be "degree_east"; other options from udunits may be specified instead.
geospatial_lon_resolution	Information about the targeted spacing of points in longitude. Recommend describing resolution as a number value followed by units.
geospatial_vertical_units	Units for the vertical axis described in "geospatial_vertical_min" and "geospatial_vertical_max" attributes. These are presumed to be "meter" (of depth); other options from udunits may be specified. Note that the common oceanographic practice of using pressure for a vertical coordinate, while not strictly a depth, can be specified using the unit bar.
geospatial_vertical_resolution	Information about the targeted vertical spacing of points.
creator_uri	The unique identifier of the person principally responsible for originating this data.
creator_institution	The institution that originated this data; should uniquely identify the institution.
creator_institution_info	Additional free text information for the institution that originated this data.
creator_project	The scientific project that originated this data; should uniquely identify the project.
creator_project_info	Additional free text information for the institution that originated this data.
publisher_uri	The unique identifier of the person responsible for providing the data file or product.
publisher_institution	The institution that provided the data file or equivalent product; should uniquely identify the institution.
publisher_institution_info	Additional information for the institution that provided the data file or equivalent product; can include any information as free text, or in a structured format compatible with conversion to ncML (e.g., insensitive to whitespace).
publisher_project	The scientific project that provided the data file or equivalent product; should uniquely identify the project.
publisher_project_info	Additional information for the institution that provided the data file or equivalent product; can include any information as free text, or in a structured format compatible with conversion to ncML (e.g., insensitive to whitespace).
keywords_vocabulary	If you are using a controlled vocabulary for the words/phrases in your "keywords" attribute, this is the unique name or identifier of the vocabulary from which keywords are taken. If more than one keyword vocabulary is used, each may be presented with a prefix (e.g., "CF:NetCDF COARDS Climate and Forecast Standard Names") and a following comma, so that keywords may optionally be prefixed with the controlled vocabulary key.
metadata_link	A URI that gives the location of more complete metadata; a URL is recommended.

Highly Recommended Variable Attributes

Attribute	Description
long_name	A long descriptive name for the variable (not necessarily from a controlled vocabulary). If a "standard_name" attribute is not given (and a "standard_name_vocabulary" is given), the "long_name" attribute value will be used by THREDDS as the variable's name in the variable mapping. This attribute is recommended by the "NetCDF Users Guide", the COARDS convention, and the CF convention.
standard_name	A long descriptive name for the variable taken from a controlled vocabulary of variable names.We recommend using the CF convention and the variable names from the CF standard name table. Use of this attribute is highly recommended and its value will be used by THREDDS as the variable's name in the variable mapping. (For THREDDS use, this attribute takes precedence over the "long_name" attribute.) This attribute is recommended by the CF convention.
units	The units of the variables data values. This attributes value should be a valid udunits string. Its value will be used by THREDDS as the variable's units in the variable mapping. The "units" attribute is recommended by the "NetCDF Users Guide", the COARDS convention, and the CF convention.
coverage_content_type	An ISO 19115-1 code to indicate the source of the data (image, thematicClassification, physicalMeasurement, auxiliaryInformation, qualityInformation, referenceInformation, modelResult, or coordinate).

Deprecated

The following terms and definitions are still recognized, but are no longer recommended for use by ACDD.

Metadata_Convention: removed in favor of 'Conventions'

creator: renamed to creator_name

date_created: deleted (use cases are addressed by 'date_product_available')

date_issued: deleted in favor of 'date_product_available'

date_modified: deleted in favor of 'date_product_modified' and 'date_values_modified'

institution: though recommended by CF, ACDD promotes more detailed attributes - 'creator_institution', 'creator_institution_info', 'publisher_institution', 'publisher_institution_info' -- to provide more provenance information. CF users of course should also provide the institution attribute, according to CF's recommendation.

---

Conformance Test

Conformance tests are available for verson 1.1. We hope to make a conformance test for this version available.

Additional Materials

These materials are not normative and may not be in alignment with this version of ACDD.

• Mappings ACDD to other metadata dialects
  • Attribute Convention for Data Discovery (ACDD) Mappings-
• Recommended Order of Precedence
  • Attribute Convention for Data Discovery (ACDD) Precedence
• Future Directions: Object Conventions for Data Discovery
  • Attribute Convention for Data Discovery (ACDD) Object Conventions
• ISO Translation Notes
  • http://wiki.esipfed.org/index.php?title=Attribute_Convention_for_Data_Discovery_(ACDD)_ISO_TranslationNotes