The NetCDF Markup Language (NcML)
NcML is an XML representation of netCDF metadata, (approximately) the
header information one gets from a netCDF file with the "ncdump -h"
command. NcML is similar to the netCDF CDL
(network Common data form Description Language), except, of course, it uses
NcML development is happening on two fronts:
- NcML-2.2 as implemented by the NetCDF-Java library.
- ncML-Gml is
an extension of ncML core schema, based on GML grammar. It uses both NcML and GML to
create a bridge to GIS Systems. This work is led by Stefano Nativi at the
Università degli Studi di Firenze.
NcML as output
The simplest use of NcML is to describe the metadata and structural content of a netCDF file, like the output of ncdump -h. There are
several ways to generate NcML ouput from an existing netCDF file:
- In the ToolsUI application, use the NcML tab to open a
NetCDF dataset, and the NcML will be displayed. You can edit and then save the NcML with the "Save NcML" button.
- In the NetCDF-Java library, use NetcdfFile.writeNcML() or NcMLWriter().writeXML().
- Use the NetCDF-Java library ncdump application, eg:
java -classpath netcdfAll.jar ucar.nc2.NCdumpW <NetCDF-3 filename> -ncml
- In the netCDF C library, version 3.6.1 or later , use ncdump -x<NetCDF filename>
Using NcML to create a NetCDF-3 file
Using the NetCDF-Java library, you can also use NcML to create a new netCDF-3 file, similar to the ncgen program.
- Using a text or XML editor, create the NcML file with an "xml" or "ncml" file extension. Open the NcML file with NetcdfDataset.open(),
then call ucar.nc2.FileWriter.writeFile()
- In the ToolsUI application, open an existing NcML file in
the NcML tab, or create a new one. You can edit and save the NcML with the "Save NcML" button. You can create the equivilent
binary NetCDF file with the "Write NetCDF" button.
Using NcML to modify an existing CDM file
Using the NetCDF-Java library, you can use NcML to modify an existing CDM file, and then write a new netCDF-3 format file with those modifications in it.
- Using a text or XML editor, create the NcML file with an "xml" or "ncml" file extension. Reference the existing file using the location
attribute, and add, change or delete metadata in the NcML as in this example.
- Write the new file as a netCDF-3 format file:
- Use the NetCDF-Java library nccopy application to
write the new file, eg:
java -Xmx1g -classpath netcdfAll-4.3.jar ucar.nc2.dataset.NetcdfDataset -in myFile.ncml -out myFile.nc
- (or) In the ToolsUI application, open the NcML file in
the NcML tab. You can create the equivilent binary NetCDF file with the "Write NetCDF" button.
A more advanced use is to modify existing NetCDF files, as well as to create "virtual" NetCDF datasets, for example through aggregation. In that case,
you'll have to read more:
Acknowledgments and History
Earlier work in defining XML representations for netCDF data included Bear Giles DTD and XML tools in March 2000, a proposed DTD by Stefano Nativi and Lorenzo
Bigagli at the University of Florence in May 2000, and a version developed by John Caron in February 2001.
The original NcML working group consisted of John
Caron (Unidata/UCAR), Luca Cinquini (SCD/NCAR), Ethan Davis (Unidata/UCAR), Bob Drach (PCMDI/LLNL), Stefano Nativi (University of Florence), and Russ Rew
In the first implementation of NcML (version 2.1), there were three parts to NcML with separate schema documents:
- NcML Core
Schema represented the existing netCDF-3 data model
- NcML Coordinate System extended NcML Core Schema and extended the netCDF
data model to add explicit support for general and georeferencing coordinate systems
- NcML Dataset extended NcML Core Schema to use NcML to
define a netCDF file, similar to the ncgen command line tool, as well as to redefine, aggregate, and subset existing netCDF files.
Coordinate System is now superceded by NcML-GML. NcML Core Schema and NcML Dataset
have been combined into a single NcML Schema, and some of the NcML Dataset syntax and
functionality has been modified.
Please send comments and/or questions to firstname.lastname@example.org
This document is maintained by Unidata. Send comments to THREDDS support. Last updated: Nov