Difference between revisions of "Attribute Convention for Data Discovery 1-2 Working"

From Earth Science Information Partners (ESIP)
(removed Documentation Cluster category)
 
(45 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
[[Category: Attribute Conventions Dataset Discovery]]
 
[[Category: Attribute Conventions Dataset Discovery]]
 +
 +
__TOC__
 +
 
== Version and Status ==
 
== Version and Status ==
  
This version is designated as Version 1.2.1 beta.
+
This is an older working document for updates to the ACDD convention, leading to version 1.2 of that convention.  This page is no longer under development, but is maintained for historical reasons. It contains extensive (but not complete) documentation of discussions during the development of version 1.3.
 +
 
 +
Note this document is not a full replacement of the original 1.1; that full replacement will be built upon approval of this content.
  
This page is under development with updated definitions.
+
The version of this ''working'' document is designated as version 1.2.3.
  
 
= Introduction =
 
= Introduction =
Line 12: Line 17:
 
The first 3 sections represent the terms in the corresponding sections of the ACDD.
 
The first 3 sections represent the terms in the corresponding sections of the ACDD.
  
Modifications relative to the original text may be seen with the history mechanism of this wiki. The original definitions are marked with the Summary keyword Original Definitions.
+
Modifications relative to the original text may be seen with the history mechanism of this wiki. The original definitions are marked in that history with the Summary keyword Original Definitions.
  
 
== Process ==
 
== Process ==
  
The edits will be made in this page by anyone in the community who wishes to contribute, and discussed in greater depth in the Discussion page, if necessary. (The discussion page can also be used as an archive of changes on this page, if desired.)
+
The edits have been made in this page by anyone in the community who wishes to contribute, and discussed in greater depth in the Discussion page, if necessary.
  
Once there is some consensus about one or a group of definitions, they can be migrated to the [[Attribute Convention for Data Discovery (ACDD)|primary document]] and the version number of that document incremented.
+
Once there is consensus about these definitions, they will be migrated to a new version of the [[Attribute Convention for Data Discovery|primary document]].
  
 
== Status ==
 
== Status ==
  
This summarizes the status of the terms as of 2013.10.18.   
+
This summarizes the status of the terms as of 2014.02.03All major issues have been resolved in the document, pending review by the ACDD team.
 +
 
 +
Details may be reviewed below the [http://wiki.esipfed.org/index.php/Talk:Attribute_Convention_for_Data_Discovery_Working#List_of_Open_Issues open issues] in the Discussion page.
  
It also references the [http://wiki.esipfed.org/index.php/Talk:Attribute_Convention_for_Data_Discovery_(ACDD)_Working#List_of_Open_Issues open issues] in the Discussion page.
+
= Suggested Changes to introductory words =
  
These are the major remaining issues in the document.
+
The following (between § marks) is proposed to replace the top text on the [[Attribute Convention for Data Discovery 1-1]] page, until just before the Highly Recommended section.
  
=== Attributes Without Comment ===
+
§
'''Highly Recommended''': title, summary
+
== Version and Status ==
  
'''Recommended''': id, naming_authority, comment, processing_level, acknowledgment, geospatial_* (bounds, lat_min, lat_max, lon_min, lon_max, vertical_min, vertical_max, vertical_positive), time_coverage_start, time_coverage_end, time_coverage_duration, license (wording reordered)
+
This is version 1.2 of the ACDD convention.
Suggested: geospatial_lat_units, geospatial_lon_units, geospatial_vertical_units, coverage_content_type
 
  
=== Attributes Discussed and Resolved ===
+
The target page [[Attribute Convention for Data Discovery]] will always point to the current version of this convention. As the convention is updated, the version number at the top of the page and in the URL will be updated, and the target page will redirect to the most recent version.
'''Recommended''':
 
* cdm_data_type: all issues resolved, needs one last read.
 
* creator, creator_email, publisher, publisher_email: no issue with updates
 
* time_coverage_resolution: updated to specify targeted spacing (and preferred format); needs review
 
* standard_name_vocabulary: someone pointed out this is unnecessary; in CF the standard_name vocabulary is always CF. It's deleted.
 
* contributor_info: principal objections (ISO 19139) are resolved; discussion may be needed, but I think satisfactory structural encodings may be found and should be acceptable.
 
  
'''Suggested''':
+
See the [[http://wiki.esipfed.org/index.php/Category:Attribute_Conventions_Dataset_Discovery category page]] for an overview of this convention and history about its development. 
* geospatial_*_resolution (lat, lon, vertical): updated to specify targeted spacing; needs review
 
  
=== Attributes Under Discussion ===
+
=== Development ===
'''Highly Recommended''':
 
* keywords: use type code or pseudo-groups syntax? ok to use URI in addition to selections from a vocabulary? ok to use prefix?
 
  
'''Recommended''':
+
Any development version of the ACDD definitions is maintained can be found at [[Attribute_Convention_for_Data_Discovery_Working]], which redirects to the current working document, if any.
* keywords_vocabulary: can multiple keyword vocabularies be separated by a comma and specified in keywords attribute with a prefix? (if not both, then do neither -- just use URI option in keywords)
 
* history: had to drop ISO 19139 expression of lineage, replaced with external reference option
 
* date_modified: recently discussed by Nan; description is updated per John's latest email in that thread
 
* creator_url, publisher url: moved to Suggested, changed to _uri, and specified to apply to person only
 
  
'''Suggested''':
+
= Overview =
* creator_project, creator_institution, publisher_project, publisher_institution: do they help discovery enough to include?
+
The NetCDF Group at Unidata has recommended  [http://www.unidata.ucar.edu/software/thredds/v4.3/netcdf-java/formats/DataDiscoveryAttConvention.html attributes for data discovery] . The Attribute Convention for Data Discovery (ACDD) addresses that need, providing definitions for NetCDF global attributes that will help data to be located efficiently. 
* creator_project_info, creator_institution_info, publisher_project_info, publisher_institution_info: (deleted ISO 19139: do _they_ help discovery enough?
 
* date_created: recently discussed by Nan; description is updated from John's latest email in that thread
 
  
'''Other''':
+
== Alignment with NetCDF and CF Conventions ==
* Metadata_Conventions: changed text significantly per separate email thread; reference John's email titled Metadata_Conventions and Metadata_Link
+
The NetCDF User Guide [http://www.unidata.ucar.edu/software/netcdf/docs/netcdf.html (NUG)] provides basic recommendations for creating NetCDF files; the NetCDF Climate and Forecast Metadata Conventions [http://cf-pcmdi.llnl.gov/documents/cf-conventions/latest-cf-conventions-document-1/ (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.
* Metadata_Link: defined
 
  
= Working Definitions =
+
The NUG does not require any global attributes, though it recommends and defines two, title and history; CF specifies many more. ACDD 1.2 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 [http://www.unidata.ucar.edu/software/netcdf-java/formats/DataDiscoveryAttConvention.html Unidata crosswalk to THREDDS] page includes also includes a crosswalk to ISO 19115-2. Note that the attribute names link to the Unidata definitions. Many of these elements are included in the [https://geo-ide.noaa.gov/wiki/index.php?title=ISO_19115_Core_Elements ISO 19115 Core] specification. They are indicated in this Table by an M, O, or C in parentheses. An “M” indicates that the element is mandatory. An “O” indicates that the element is optional. A “C” indicates that the element is mandatory under certain conditions.
 +
 
 +
== Additional Metadata: metadata_link attribute ==
 +
 
 +
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.
 +
 
 +
== Conformance Test ==
 +
 
 +
A [https://geo-ide.noaa.gov/wiki/index.php?title=NetCDF_Attribute_Convention_for_Dataset_Discovery_Conformance_Test Conformance Test] is available for this convention.
 +
 
 +
== 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.
 +
 
 +
''{(Not for inclusion in final draft) As a working tool, the page [[NetCDF Utilities Metadata Handling]] has been created to identify the state of play for how tools handle metadata attributes when processing files.}''
 +
 
 +
= Global Attributes = 
 +
''(reformat Highly Recommended, Recommended, etc. as 2nd-level headings)''
 +
 
 +
§
  
 
== Highly Recommended ==
 
== Highly Recommended ==
Line 70: Line 89:
 
; title : A short phrase or sentence describing the dataset; this is a NetCDF Users Guide ([http://www.unidata.ucar.edu/software/netcdf/docs/netcdf.html#Attribute-Conventions NUG]) attribute.  
 
; title : A short phrase or sentence describing the dataset; this is a NetCDF Users Guide ([http://www.unidata.ucar.edu/software/netcdf/docs/netcdf.html#Attribute-Conventions NUG]) attribute.  
 
; summary : A paragraph describing the dataset, analogous to an abstract for a paper.
 
; 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, or URIs for terms from a controlled vocabulary (see keyword_vocabulary below).
+
; 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 list of the conventions followed by the dataset; blank space separated is recommended but commas should be used if any convention name contains blanks. This attribute is defined in [http://www.unidata.ucar.edu/software/netcdf/docs/netcdf.html#Attribute-Conventions NUG].
+
; Conventions : A list of the conventions followed by the dataset; blank space separated is recommended but commas should be used if any convention name contains blanks. For files that comply with this version of ACDD, include the term ACDD-1.2. This attribute is [http://www.unidata.ucar.edu/software/netcdf/docs/netcdf.html#Attribute-Conventions defined in NUG].
; 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 defined in ([http://cf-pcmdi.llnl.gov/documents/cf-conventions/1.6/cf-conventions.html#description-of-file-contents CF]).
 
  
 
== Recommended ==
 
== Recommended ==
Line 78: Line 96:
 
; 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.
 
; 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.
 
; naming_authority : The organization that provides the initial id (see above) for the dataset. The naming authority should be uniquely specified by this attribute.
; keywords_vocabulary : If you are using a controlled vocabulary for the words/phrases in your "keywords" attribute, 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.
 
 
; 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 [http://www.unidata.ucar.edu/projects/THREDDS/tech/catalog/InvCatalogSpec.html#dataType 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  [http://www.nodc.noaa.gov/data/formats/netcdf/ this NODC guidance].
 
; 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 [http://www.unidata.ucar.edu/projects/THREDDS/tech/catalog/InvCatalogSpec.html#dataType 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  [http://www.nodc.noaa.gov/data/formats/netcdf/ this NODC guidance].
; history : Describes the processes/transformations used to create this data; can serve as an audit trail. Per the [http://www.unidata.ucar.edu/software/netcdf/docs/netcdf.html#Attribute-Conventions 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 an ISO Lineage reference; see [https://geo-ide.noaa.gov/wiki/index.php?title=ISO_Lineage NOAA EDM ISO Lineage guidance].
+
; history : Describes the processes/transformations used to create this data; can serve as an audit trail. This attribute is defined in the [http://www.unidata.ucar.edu/software/netcdf/docs/netcdf.html#Attribute-Conventions 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 an ISO Lineage reference; see [https://geo-ide.noaa.gov/wiki/index.php?title=ISO_Lineage NOAA EDM ISO Lineage guidance].  
; comment : Miscellaneous information about the data, not captured elsewhere.
+
; 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 [http://cf-pcmdi.llnl.gov/documents/cf-conventions/1.6/cf-conventions.html#description-of-file-contents defined in CF].
; date_modified : The date on which the provided content, including data, metadata, and presented format, was last changed.
+
; comment : Miscellaneous information about the data, not captured elsewhere.  This attribute is [http://cf-pcmdi.llnl.gov/documents/cf-conventions/1.6/cf-conventions.html#description-of-file-contents defined in CF].
 +
; date_content_modified : The date on which any of the provided content, including data, metadata, and presented format, was last created or changed (ISO 8601 format)
 +
; date_values_modified: The date on which the provided data values were last created or changed; excludes metadata and formatting changes (ISO 8601 format)
 
; creator  : The name of the person principally responsible for originating this data.  
 
; creator  : The name of the person principally responsible for originating this data.  
; creator_email : The email address of the person principally responsible for the data in the file.
+
; creator_email : The email address of the person principally responsible for originating this data.
; publisher : The person responsible for the data file, its metadata and format.  
+
; 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, its metadata and format.
+
; publisher_email : The email address of the person responsible for the data file or product.
 
; processing_level : A textual description of the processing (or quality control) level of the data.
 
; 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.
 
; acknowledgement : A place to acknowledge various type of support for the project that produced this data.
Line 104: Line 123:
  
 
== Suggested ==
 
== Suggested ==
 +
 +
The following terms and definitions are offered in case they address your situation.
  
 
; 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).
 
; 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_generated : The date on which this data product was produced/distributed
+
; date_product_generated : The date on which this data file or product was produced/distributed (ISO 8601 format). While this date is like a file timestamp, the date_content_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. These are presumed to be "degree_north"; other options from udunits may be specified instead.
 
; geospatial_lat_units : Units for the latitude axis. 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. (Format is not prescribed.)
 
; geospatial_lat_resolution : Information about the targeted spacing of points in latitude. (Format is not prescribed.)
Line 113: Line 134:
 
; geospatial_vertical_units : Units for the vertical axis. 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_units : Units for the vertical axis. 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.  
 
; geospatial_vertical_resolution : Information about the targeted vertical spacing of points.  
; coverage_content_type :  Information about the content of the file, valid values are image, thematicClassification, physicalMeasurement, auxiliaryInformation, qualityInformation, referenceInformation, modelResult, coordinate.
+
; creator_uri : The unique identifier of the person principally responsible for originating this data.  
; creator_uri : The unique identifier of the person principally responsible for the data.  
+
; creator_institution : The institution that originated this data; should uniquely identify the institution.  
; creator_institution : The institution that produced the data; should uniquely identify the institution.  
+
; creator_institution_info : Additional free text information for the institution that originated this data.
; creator_institution_info : Additional free text information for the institution that produced the data.
+
; creator_project : The scientific project that originated this data; should uniquely identify the project.  
; creator_project : The scientific project that produced the data; should uniquely identify the project.  
+
; creator_project_info : Additional free text information for the institution that originated this data.
; creator_project_info : Additional free text information for the institution that produced the data.
+
; publisher_uri : The unique identifier of the person responsible for providing the data file or product.  
; publisher_uri : The unique identifier of the person responsible for the data file, its metadata and format.  
+
; publisher_institution : The institution that provided the data file or equivalent product; should uniquely identify the institution.  
; publisher_institution : The institution that published the data file; 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_institution_info : Additional information for the institution that published the data; can include any information as ISO 19139  or free text.
+
; publisher_project : The scientific project that provided the data file or equivalent product; should uniquely identify the project.  
; publisher_project : The scientific project that published the data; 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).
; publisher_project_info : Additional information for the institution that published the data; can include any information as ISO 19139  or free text.
+
; 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.
 
; metadata_link : A URI that gives the location of more complete metadata; a URL is recommended.
; Metadata_Convention : (deprecated, supported for backward compatibility with current usage) Reference to the particular metadata convention(s) used for the described data file; recommended practice is to add the metadata convention(s) to the comma-delimited conventions list in the 'Conventions' attribute, per NetCDF Best Practices.
 
  
Note: The NUG defines title and history to be global attributes. CF adds institution, source, references, and comment, to be either global or assigned to individual variables. When an attribute appears both globally and as a variable attribute, the variable's version has precedence. ACDD does not require or define institution or references.
+
== Deprecated ==
 +
 
 +
The following terms and definitions are still in the specification, but are no longer recommended for use.
 +
 
 +
: Metadata_Convention : (deprecated, supported for backward compatibility with current usage) Reference to the particular metadata convention(s) used for the described data file; recommended practice is to add the metadata convention(s) to the comma-delimited conventions list in the 'Conventions' attribute, per NetCDF Best Practices.
 +
: date_created :deleted in favor of date_product_generated (which used to be date_issued); we did not have a use case for knowing the date a stream or product was _first_ generated, once it has been updated
 +
: date_issued : changed name to date_product_generated
 +
: date_modified : changed name to date_content_modified
 +
 
 
----
 
----
  
= Mappings ACDD to other metadata dialects =
+
= Additional Materials =
http://wiki.esipfed.org/index.php/Attribute_Convention_for_Data_Discovery_%28ACDD%29_Mappings
+
== Mappings ACDD to other metadata dialects ==
 +
[[Attribute Convention for Data Discovery (ACDD) Mappings]]
  
= Recommended Order of Precedence =
+
== Recommended Order of Precedence ==
http://wiki.esipfed.org/index.php/Attribute_Convention_for_Data_Discovery_%28ACDD%29_Precedence
+
[[Attribute Convention for Data Discovery (ACDD) Precedence]]
  
=Future Directions: Object Conventions for Data Discovery=
+
== Future Directions: Object Conventions for Data Discovery ==
http://wiki.esipfed.org/index.php/Attribute_Convention_for_Data_Discovery_%28ACDD%29_Object_Conventions
+
[[Attribute Convention for Data Discovery (ACDD) Object Conventions]]
  
=ISO Translation Notes=
+
== ISO Translation Notes ==
 
http://wiki.esipfed.org/index.php?title=Attribute_Convention_for_Data_Discovery_(ACDD)_ISO_TranslationNotes
 
http://wiki.esipfed.org/index.php?title=Attribute_Convention_for_Data_Discovery_(ACDD)_ISO_TranslationNotes
[[Category:Attribute Conventions Dataset Discovery]]
 
[[Category: Documentation Cluster]]
 

Latest revision as of 14:02, January 5, 2015


Version and Status

This is an older working document for updates to the ACDD convention, leading to version 1.2 of that convention. This page is no longer under development, but is maintained for historical reasons. It contains extensive (but not complete) documentation of discussions during the development of version 1.3.

Note this document is not a full replacement of the original 1.1; that full replacement will be built upon approval of this content.

The version of this working document is designated as version 1.2.3.

Introduction

This page consolidates ongoing work seeking to improve the definitions in the Attribute Convention for Data Discovery (ACDD).

The first 3 sections represent the terms in the corresponding sections of the ACDD.

Modifications relative to the original text may be seen with the history mechanism of this wiki. The original definitions are marked in that history with the Summary keyword Original Definitions.

Process

The edits have been made in this page by anyone in the community who wishes to contribute, and discussed in greater depth in the Discussion page, if necessary.

Once there is consensus about these definitions, they will be migrated to a new version of the primary document.

Status

This summarizes the status of the terms as of 2014.02.03. All major issues have been resolved in the document, pending review by the ACDD team.

Details may be reviewed below the open issues in the Discussion page.

Suggested Changes to introductory words

The following (between § marks) is proposed to replace the top text on the Attribute Convention for Data Discovery 1-1 page, until just before the Highly Recommended section.

§

Version and Status

This is version 1.2 of the ACDD convention.

The target page Attribute Convention for Data Discovery will always point to the current version of this convention. As the convention is updated, the version number at the top of the page and in the URL will be updated, and the target page will redirect to the most recent version.

See the [category page] for an overview of this convention and history about its development.

Development

Any development version of the ACDD definitions is maintained can be found at Attribute_Convention_for_Data_Discovery_Working, which redirects to the current working document, if any.

Overview

The NetCDF Group at Unidata has recommended attributes for data discovery . The Attribute Convention for Data Discovery (ACDD) addresses that need, providing definitions for NetCDF global attributes that will help data to be located 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.2 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 Unidata crosswalk to THREDDS page includes also includes a crosswalk to ISO 19115-2. Note that the attribute names link to the Unidata definitions. Many of these elements are included in the ISO 19115 Core specification. They are indicated in this Table by an M, O, or C in parentheses. An “M” indicates that the element is mandatory. An “O” indicates that the element is optional. A “C” indicates that the element is mandatory under certain conditions.

Additional Metadata: metadata_link attribute

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.

Conformance Test

A Conformance Test is available for this convention.

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.

{(Not for inclusion in final draft) As a working tool, the page NetCDF Utilities Metadata Handling has been created to identify the state of play for how tools handle metadata attributes when processing files.}

Global Attributes

(reformat Highly Recommended, Recommended, etc. as 2nd-level headings)

§

Highly Recommended

title
A short phrase or sentence describing the dataset; this is a NetCDF Users Guide (NUG) attribute.
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 list of the conventions followed by the dataset; blank space separated is recommended but commas should be used if any convention name contains blanks. For files that comply with this version of ACDD, include the term ACDD-1.2. This attribute is defined in NUG.

Recommended

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.
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 this NODC guidance.
history
Describes the processes/transformations used to create this data; can serve as an audit trail. This attribute is defined 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 an ISO Lineage reference; 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 defined in CF.
comment
Miscellaneous information about the data, not captured elsewhere. This attribute is defined in CF.
date_content_modified
The date on which any of the provided content, including data, metadata, and presented format, was last created or changed (ISO 8601 format)
date_values_modified
The date on which the provided data values were last created or changed; excludes metadata and formatting changes (ISO 8601 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.
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 bounding box or cube. 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 bounding box or cube. Geospatial_lat_max specifies the northernmost latitude covered by the dataset.
geospatial_lon_min
Describes a simple longitude limit; may be part of a bounding box or cube. 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.
geospatial_lon_max
Describes a simple longitude limit; may be part of a bounding box or cube. 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.
geospatial_vertical_min
Describes a numerically smaller vertical limit; may be part of a bounding box or cube. 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 bounding box or cube. 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. ISO8601 format recommended.
time_coverage_end
Describes the time of the last data point in the data set. ISO8601 format recommended.
time_coverage_duration
Describes the duration of the data set. ISO8601 duration format recommended.
time_coverage_resolution
Describes the targeted time period between each value in the data set. ISO8601 duration format recommended.
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

The following terms and definitions are offered in case they address your situation.

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_generated
The date on which this data file or product was produced/distributed (ISO 8601 format). While this date is like a file timestamp, the date_content_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. 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. (Format is not prescribed.)
geospatial_lon_units
Units for the longitude axis. 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. (Format is not prescribed.)
geospatial_vertical_units
Units for the vertical axis. 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.

Deprecated

The following terms and definitions are still in the specification, but are no longer recommended for use.

Metadata_Convention : (deprecated, supported for backward compatibility with current usage) Reference to the particular metadata convention(s) used for the described data file; recommended practice is to add the metadata convention(s) to the comma-delimited conventions list in the 'Conventions' attribute, per NetCDF Best Practices.
date_created :deleted in favor of date_product_generated (which used to be date_issued); we did not have a use case for knowing the date a stream or product was _first_ generated, once it has been updated
date_issued : changed name to date_product_generated
date_modified : changed name to date_content_modified

Additional Materials

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