6.4.1 Dataset Descriptor Structure

In order to translate data from one data model into another, OPeNDAP must have some knowledge about the types of the variables, and their semantics, that comprise a given data set. It must also know something about the relations of those variables--even those relations which are only implicit in the dataset's own API. This knowledge about the dataset's structure is contained in a text description of the dataset called the Dataset Description Structure.  

The DDS does not describe how the information in the dataset is physically stored, nor does it describe how the data set API is used to access that data. Those pieces of information are contained in the API itself and in the OPeNDAP server, respectively. The server uses the DDS to describe the structure of a particular dataset to a translator--the DDS contains knowledge about the dataset variables and the interrelations of those variables. In addition, the DDS can be used to satisfy some of the DODS-supported API data set description calls. For example, netCDF has a function which returns the names of all the variables in a netCDF data file. The DDS can be used to get that information.

The DDS is a textual description of the variables and their classes that make up some data set. The DDS syntax is based on the variable declaration and definition syntax of C and C++. A variable that is a member of one of the base type classes is declared by writing the class name followed by the variable name. The type constructor classes are declared using C's brace notation. A grammar for the syntax is given in table 6.4.1. Each of the keywords for the type constructor and base type classes have already been described in Section 6.3. The Dataset  keyword has the same syntactic function as Structure but is used for the specific job of enclosing the entire data set even when it does not technically need an enclosing element.

Different data access APIs will store the information in the DDS in different places. Some APIs are self-documenting in the sense that the data files themselves will contain all the information about the structure of their data types. Other APIs need secondary files containing what is called ancillary data, describing the data structure. For some APIs, such as netCDF, gathering the ancillary information from the data archive may be a time-consuming process. The OPeNDAP server for these APIs may cache ancillary data files to save time. An example DDS entry is shown in figure 6.4.1. (See Section 6.1 for an explanation of the information implied by the data model, and for several other DDS examples).

Dataset { 
  Int32 catalog_number;
  Sequence {
    String experimenter;
    Int32 time;
    Structure {
      Float64 latitude;
      Float64 longitude;
    } location;
    Sequence {
      Float64 depth;
      Float64 salinity;
      Float64 oxygen;
      Float64 temperature;
    } cast;
  } station;
} data;

When creating a DDS to be kept in an ancillary file, you can use the # character as a comment indicator. All characters after the # on a line are ignored.