Understanding the XML

Unfortunately, metadata in netCDF files is frequently missing or inadequate. As long as you are using only COARDS compliant netCDF files, you can still use the automatic XML generation technique described above to generate a template configuration file, which you can then edit. If you are using other types of datasets, you have to manually insert the metadata for the dataset.

You will have to modify the XML configuration file if your metadata is missing or insufficient; to do this, you will have to understand the syntax and semantics of the LAS XML configuration file. A sample XML file is below, followed by definitions for LAS XML elements and attributes.

Sample XML file

<?xml version='1.0' ?>
<lasdata>
  <institution name="Pacific Marine Environmental Lab"
   url="http://www.pmel.noaa.gov"/>
<!-- Define operations -->
    <operations url="http://foo.com/las-bin/LASserver.pl" >
      <shade name="Shade a variable" class="LAS::Server::Ferret" method="draw">
        <arg type="variable"/>
         <arg type="region"/>
       </shade>
    </operations>
<!-- Define datasets/variables -->
   <datasets>
    <coads_climatology_cdf name="COADS Climatology" url="file:coads_climatology" doc="doc/coads_climatology.html">
     <variables>
      <airt name="Air Temperature" units="DEG C">
       <link match="/lasdata/grids/coads_climatology_cdf_grid"/>
      </airt>
      <sst name="Sea Surface Temperature" units="Deg C">
       <link match="/lasdata/grids/coads_climatology_cdf_grid"/>
      </SST>
     </variables>
     <composite>
      <wind_vectors name="Wind vectors" js="VecVariable">
       <link match="../../variables/uwnd"/>
       <link match="../../variables/vwnd"/>
      </wind_vectors>
     </composite>
    </coads_climatology_cdf>
   </datasets>
<!-- Define grids -->
   <grids>
    <coads_climatology_cdf_grid>
     <link match="/lasdata/axes/coads_climatology_cdf_COADSX"/>
     <link match="/lasdata/axes/coads_climatology_cdf_COADSY"/>
     <link match="/lasdata/axes/coads_climatology_cdf_TIME"/>
    </coads_climatology_cdf_grid>
   </grids>
<!-- Define axes -->
   <axes>
    <coads_climatology_cdf_COADSX type="x" units="degrees_east">
     <arange start="21" step="2" size="180"/>
    </coads_climatology_cdf_COADSX>
    <coads_climatology_cdf_COADSY type="y" units="degrees_north">
     <arange start="-89" step="2" size="90"/>
    </coads_climatology_cdf_COADSY>
    <coads_climatology_cdf_TIME type="t" units="month">
     <arange start="1-1-16" step="1" size="12"/>
    </coads_climatology_cdf_TIME>
   </axes>
  </lasdata>

XML Element and Attribute Definitions

The elements and attributes that make up a LAS XML specification are defined below. Note the following:

When <*> is used for a element tag, it implies that the tag can be any string compliant with the XML specification, as long as the tag is unique.
Regular expressions are used for describing the children of an element. For example, dataset* implies that 0 or more child dataset elements are required; dataset+ implies that 1 or more child dataset elements are required.

Lasdata element

The lasdata element is the root of the LAS XML hierarchy.

Link element

The link element is used to associate one part of the XML specification with another. It is analogous to the anchor tag in HTML, with the exception that the contents that are linked to are substituted in place. The following XML:

<a>
  <b>
    <link match="/a/d"/>
  </b>
  <d name="foo"/>
</a>

is equivalent to:

<a>
  <b>
    <d name="foo"/>
  </b>
  <d name="foo/>
</a>

Element Tag Required? Children Description

link <link> no Links to XML content in another part of the document.

Attribute Type Required? Description

match string yes The path to the linked content. This can be either a full or relative path. If there are multiple matches, the first match is used.

Datasets element

The datasets section contains information on all of the datasets supported by the server. Here you will find metadata such as variable names, variable units, or the file or URL to be associated with a variable or dataset.

Element Tag Required? Children Description

datasets <datasets> yes dataset* Container for dataset tags

Dataset element

Each dataset is described by a dataset element. The name of the element can be anything but properties or institution; the name must be unique. It is coads_climatology_cdf in the sample file.

Element Tag Required? Children Description

dataset <*> no variables* |
composite* |
properties |
institution Describes a dataset

Attribute Type Required? Description

name string no Display name of dataset. Defaults to element name.

url string no URL of the dataset. In most cases, the URL should use a file scheme; a http scheme will only work with DODS datasets. If not defined, then each variable element contained by this element must have a URL attribute defined.

doc string no URL of documentation associated with dataset. This documentation will appear when a user clicks on dataset in the LAS datasets frame.

Variables element

Element Tag Required? Children Description

variables <variables> yes variable* Container for variable tags

Composite element

Composite elements are used to describe "virtual" variables that are composed of one or more dataset variables.

Element Tag Required? Children Description

composite <composite> no comp_tags+ Container for composite tags

Comp_tag element

Element Tag Required? Children Description

comp_tag <*> yes variable+ Describes a virtual variable

Attribute Type Required? Description

name string yes Display name of composite element

Js string yes JavaScript class to be associated with the composite. This class should be a subclass of the V JavaScript class, and should override the getOpType method (which determines the LAS operation to be associated with a variable). The VecVariable class in $lasroot/lasxml/ui/las.js illustrates how this should be implemented.

Variable element

Element Tag Required? Children Description

variable <*> no grid* |
properties |
institution Describes a variable

Attribute Type Required? Description

name string no Display name of variable. Default to element name.

units string yes Units of variable. Should be compatible with Unidata's udunits package.

url string no URL of the dataset. If missing defaults to URL of parent dataset. In netCDF files, URL fragments are used to refer to specific variables; if the fragment is missing, the containing XML element tag is used. Example:

url="file:/foo.cdf#SST" points to the variable SST in file foo.cdf

Grids element

Element Tag Required? Children Description

grids <grids> yes grid Container for grid tags

Grid element

Element Tag Required? Children Description

grid <*> no axis* Describes a grid

Axes element

Element Tag Required? Children Description

axes <axes> yes axis* Container for axis tags

Axis element

Element Tag Required? Children Description

axis <*> no arange | v+ Describes an axis

Attribute Type Required? Description

type 'x'|'y'|'z'|'t' yes Orientation of axis in space. 'x' implies a longitude axis, 'y' latitude, 'z' depth or height, and 't' time.

Units string yes Axis units. Should be compatible with Unidata's udunits package.

Arange element

Element Tag Required? Children Description

arange <arange> no Describes a regular axis range.

Attribute Type Required? Description

start double|time yes
Origin of the axis. If the axis is of type 't', this is a time string; for all other axes, this is a double precision floating point number.

The time string is of the form 'YYYY-MM-DD'. The year '0001' is reserved for climatological time axes.

step double yes The step size of this regular axis. The units used are those of the containing axis. The only time units supported are 'year', 'month', and 'day'

size integer yes Number of points in the axis

V element

Element Tag Required? Children Description

v <v> no text Describes a point in an irregular axis. For example, an axis with two values, 0 and 20, would contain the XML:
<v>0</v>
<v>20</v>

Properties element

Properties are general purpose tags that can be associated with a LAS XML element. LAS currently uses properties to associate visualization "hints" for Ferret with datasets or variables. A set of Ferret properties might look like:

<properties>
  <ferret>
    <size>0.25</size>
    <format>netCDF</format>
  </ferret>
</properties>

The child elements of the <properties> tag can be anything; it is up to the server application to decode their semantics.

Element Tag Required? Children Description

properties <properties> no property* Container for property tags

Institution element

Element Tag Required? Children Description

institution <institution> no Describes the institution that supplied the dataset or variable. This information is displayed on the client's Web browser when a given dataset or variable is selected.

Attribute Type Required? Description

name string yes Display name of the institution.

url string no URL of Web page containing info on the institution.

Operations

Element Tag Required? Children Description

operations <operations> yes operation+ Container for operation tags

Attribute Type Required? Description

url string yes URL of LAS server implementing operations

Operation

An operation is used to map a browser user interface action to a Perl subroutine or method on a LAS server. For instance, there is one operation defined in the sample XML file above; this operation maps the UI action shade to the subroutine draw in the Perl package LAS::Server::Ferret.

Element Tag Required? Children Description

operation <*> yes arg+ Describes the mapping between client-side, JavaScript based user actions to server side, Perl based subroutines.

Attribute Type Required? Description

name string yes Description of operation. Solely for documentation.

class string yes Perl object or package to be associated with the operation.

method string yes Perl subroutine to be associated with the operation.

Arg

Element Tag Required? Children Description

arg <arg> yes Defines the type of an argument to be passed to a LAS operation. Not yet implemented.

Attribute Type Required? Description

type string yes Type of argument. Currently ignored.

Joe Sirott: Jonathan.S.Callahan@noaa.gov
Last modified: April 18, 2000

Element	Tag	Required?	Children	Description
lasdata	<lasdata>	yes	datasets+ \| grids+ \| axes+ \| operations+ \| properties*\| institution?	Root of LAS XML document.

Attribute	Type	Required?	Description
match	string	yes	The path to the linked content. This can be either a full or relative path. If there are multiple matches, the first match is used.