COMMENTED SCHEMA FOR NcML
(Netcdf Markup Language)

<?xml version="1.0" encoding="UTF-8" ?>
<xsd:schema targetNamespace="http://www.ucar.edu/schemas/netcdf" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:nc="http://www.ucar.edu/schemas/netcdf" elementFormDefault="qualified">

Netcdf
The Netcdf object represents a generic netCDF dataset, i.e. a container for data conforming to the netCDF model. For instance, a Netcdf object might represent a netCDF file, a subset of a netCDF file, a set of potential netCDF files, an aggregation of netCDF files or a self-contained dataset (i.e. all the data is already included in the NcML document and there is no netCDF file holding the data). A Netcdf object therefore should not necessarily be thought of as a physical netCDF file, but rather the "public interface" or API to a set of data, which may or may not be implemented with a physical netCDF file. The element netcdf is the root tag of the NcML instance document.

<!-- XML encoding of Netcdf container object -->
<xsd:complexType name="NetcdfType">
  <xsd:choice minOccurs="0" maxOccurs="unbounded"> (1)
    <xsd:element ref="nc:dimension"/>
    <xsd:element ref="nc:variable" />
    <xsd:element ref="nc:attribute"/>
  </xsd:choice>
  <xsd:attribute name="id" type="xsd:token" use="optional" /> (2)
  <xsd:attribute name="uri" type="xsd:anyURI" use="optional" /> (3)
</xsd:complexType>

<xsd:element name="netcdf" type="nc:NetcdfType">
   <!-- uniqueness constraints among children of netcdf element -->
   <xsd:key name="dimensionName"> (4)
    <xsd:selector xpath="nc:dimension" />
    <xsd:field xpath="@name" />
  </xsd:key>
  <xsd:key name="variableName"> (5)
    <xsd:selector xpath="nc:variable" />
    <xsd:field xpath="@name" />
  </xsd:key>
  <xsd:key name="globalAttributeName"> (6)
    <xsd:selector xpath="nc:attribute" />
    <xsd:field xpath="@name" />
  </xsd:key>
</xsd:element>

1. The netcdf element may contain any number (including 0) of elements variable, dimension, attribute, that can appear in any order within the document.
2. The optional id attribute is meant to provide a way to uniquely identify (relative to the application context) the Netcdf object. For example, if many NCML documents are stored on a server, each of them can be assigned a unique key or id (id="abc123", id="cde_45" and so on"). It is important to understand that the id attribute referes to the dataset defined by the XML instance document, NOT the physical file if there is even one.
3. The optional uri attribute provides a reference to the physical file containing the variable data that does not exist in the NcML document itself. Currently the Java-Netcdf library supports the following ways to access a physical netCDF file: 1) if the file is accessible on a local disk, you can use the "file:" scheme (e.g. uri="file://E:/my/path/file.nc"). If it is a DODS dataset that can be accessed through the netCDF API, use the "dods:" scheme (e.g. uri="dods://www.host.com/dods/my/path/file.nc"). You can also make a netCDF file accessible through an HTTP server: (e.g. uri="http://www.host.com/my/path/file.nc").
4. The name attribute of a dimension element must be unique within the scope of the enclosing netcdf element (this constraint is compatible with the netCDF requirements that there cannot be two dimensions in the same file with the same name)

5. The name attribute of a variable element must be unique within the scope of the enclosing netcdf element (this constraint is compatible with the netCDF requirements that there cannot be two variables in the same file with the same name

6. The name attribute of a global attribute element must be unique within the scope of the enclosing netcdf element (this constraint is compatible with the netCDF requirements that there cannot be two global attributes in the same file with the same name)

Dimension
A Dimension object represents a netCDF dimension, i.e. a named index of specified length.

<!-- XML encoding of Dimension object -->
<xsd:complexType name="DimensionType">
  <xsd:attribute name="name" type="xsd:token" use="required" /> (1)
  <xsd:attribute name="length" type="xsd:nonNegativeInteger" use="required" /> (2)
  <xsd:attribute name="isUnlimited" type="xsd:boolean" default="false" /> (3)
</xsd:complexType>

<xsd:element name="dimension" type="nc:DimensionType" />

1. The mandatory name attribute is a unique identifier for the dimension element. The netCDF specification prescribes that dimensions names must be unique. Note that since the attribute name is defined to be of type xsd:token, trailing and ending spaces are ignored, and all other spaces or new lines are collapsed to one single space.
2. The mandatory attribute length expresses the cardinality (number of points) associated with the dimension. Its value can be any non negative integer including 0 (since the unlimited dimension in a netCDF file may have length 0, corresponding to 0 records).
3. The attribute isUnlimited needs to be specified and set to "true" only if the dimension is the unlimited dimension in the netCDF file, otherwise it defaults to the value "false"

Variable
A Variable object represents a netCDF variable, i.e. a scalar or multidimensional array of specified type indexed by 0 or more dimensions.

<!-- XML encoding of Variable object -->
<xsd:complexType name="VariableType">
  <xsd:sequence> (1)
    <xsd:element ref="nc:attribute" minOccurs="0" maxOccurs="unbounded" /> (2)
    <xsd:element ref="nc:values" minOccurs="0" maxOccurs="1" /> (3)
  </xsd:sequence>
  <xsd:attribute name="name" type="xsd:token" use="required" /> (4)
  <xsd:attribute name="shape" type="xsd:token" use="optional" /> (5)
  <xsd:attribute name="type" type="nc:DataType" use="required" /> (6)
</xsd:complexType>

<xsd:element name="variable" type="nc:VariableType">
  <xsd:key name="variableAttributeName"> (7)
    <xsd:selector xpath="nc:attribute" />
    <xsd:field xpath="@name" />
  </xsd:key>
</xsd:element>

<!-- XML encoding of Variable values -->
<xsd:complexType name="ValuesType" mixed="true">
  <xsd:attribute name="separator" type="xsd:string" default=" " /> (8)
</xsd:complexType>

<xsd:element name="values" type="nc:ValuesType" />

1. A variable element may contain any number (including 0) of attribute elements, followed by an optional values element (in that order)
2. 0 or more attribute elements may be included, expressing the particular properties of that variable (for example, the units, a standard name, etc.)
3. The values element is used to optionally include the numerical values associated with a netCDF variable, for example:
   <nc:values separator=" ">-109.0 -107.0 -105.0 -103.0</nc:values>
   Note that the inclusion of the variable values is optional and will depend on on the needs of the application which will make use of the XML instance document. For a multi-dimensional variable, the values must be listed compatibly with the shape attribute of the variable (which has the most rapidly varying dimension last). To avoid ambiguity, it was decided that the single value of a scalar variable must also be encoded (if included) as the content of a values element, for example:
   <variable name="T"><values>101</values><attribute name="units" value="degF" /></variable>.
4. The variable name is meant to represent a unique identifier for variables (but note that a netCDF variable may have the same name as a netCDF dimension). Since this attribute is of type xsd:token, any characters except ">", "<", """, "&" are allowed (these characters can be included in the name by using the standard XML escape sequences &gt;, &lt;, &quot;, &amp; respectively). Note also that trailing and leading spaces are ignored, and multiple spaces and new lines within the name are collapsed to single spaces.
5. The attribute shape represents an ordered list (blank separated) of the names of the dimensions the variable depends on. The dimensions names must be ordered with the most rapidly varying dimension last (same as in the CDL description, same as for C multidimensional arrays). Scalar variables must omit this attribute. (Note that shape="" is not a valid value)
6. The mandatory type attribute is a string selected from a controlled vocabularly (see later) specifying the numerical type of the variable.
7. The name attribute of a variable attribute element must be unique within the scope of the enclosing variable element (this constraint is compatible with the netCDF requirements that a variable cannot have two attributes with the same name)
8. The list of values is ordinarily blank-separated but optionally another token can be used as separator.

Attribute
The Attribute object represents a netCDF attribute, i.e. a name-value pair of specified type. This could be a global netCDF attribute (if it is a child of a netcdf element) or a netCDF variable attribute (if it is a child of a variable element).

<!-- XML encoding of Attribute object -->
<xsd:complexType name="AttributeType">
  <xsd:attribute name="name" type="xsd:token" use="required" /> (1)
  <xsd:attribute name="type" type="nc:DataType" use="required" /> (2)
  <xsd:attribute name="value" type="xsd:string" use="optional" /> (3)
  <xsd:attribute name="separator" type="xsd:string" default=" " /> (4)
</xsd:complexType>

<xsd:element name="attribute" type="nc:AttributeType" />

1. The mandatory attribute name is of type xsd:token and therefore may contain any characters except ">", "<", """, "&" (these characters can be included in the name by using the standard XML escape sequences &gt;, &lt;, &quot;, &amp; respectively). Note also that trailing and leading spaces are ignored, and multiple spaces and new lines within the name are collapsed to single spaces.
2. The mandatory type attribute is a string selected from a controlled vocabularly (see later) specifying the numerical type of the attribute.
3. The value attribute contains the actual data of the attribute element. In the most common case of single-valued attributes, a single number or string will be listed (as in value="3.0"), while in the less frequent case of multi-valued attributes, all the numbers will be listed and separated by a blank or optionally some other character (as in value="3.0 4.0 5.0").
4. The attribute separator represents the token used to separate the values for a multi-valued attribute. If not specified, it defaults to a blank.

Data Types
The DataType object represents an enumerated list of the numerical data types allowed for NcML Variable and Attribute objects. Note that the type "char" (which is allowed in netCDF files) is not allowed in NcML, but it is substituted with "string" (including strings of lenght 1).

<!-- possible data types for Variable, Attribute objects -->
<xsd:simpleType name="DataType">
  <xsd:restriction base="xsd:token">
    <xsd:enumeration value="byte" />
    <xsd:enumeration value="short" />
    <xsd:enumeration value="int" />
    <xsd:enumeration value="float" />
    <xsd:enumeration value="double" />
    <xsd:enumeration value="string" />
  </xsd:restriction>
</xsd:simpleType>

</xsd:schema>