The NetCDF Markup Language (NcML)

Overview

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 XML syntax.

NcML development is happening on two fronts:

1. NcML-2.2 as implemented by the NetCDF-Java library.
2. 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.
   • Home page for ncML-Gml
   • ncML-Gml API:
   • Demo web application (N2G) for testing

NcML 2.2

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:

1. 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.
2. In the NetCDF-Java library, use NetcdfFile.writeNcML() or NcMLWriter().writeXML().
3. Use the NetCDF-Java library NCdump main program, eg:

       java -classpath toolsUI.jar ucar.nc2.NCdump <NetCDF-3 filename> -ncml

4. 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.

1. 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()
2. 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.

Advanced NcML

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:

• Tutorial
• Aggregation
• Cookbook Examples
• Annotated Schema for Netcdf-Java 2.2
• Annotated Schema for Netcdf-Java 4
• ncml-2.2.xsd

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 (Unidata/UCAR).

In the first implementation of NcML (version 2.1), there were three parts to NcML with separate schema documents: 1) NcML Core Schema represented the existing netCDF-3 data model; 2) NcML Coordinate System extended NcML Core Schema and extended the netCDF data model to add explicit support for general and georeferencing coordinate systems; 3) 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.

NcML 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 support-netcdf-java@unidata.ucar.edu

This document is maintained by John Caron and was last updated on Nov 2010