Client-Side Catalog Specification

TDS User's Guide Client-Side Catalog Specification

Overview

A THREDDS catalog is a way to describe an inventory of available datasets. These catalogs provide a simple hierarchical structure for organizing a collection of datasets, an access method for each dataset, a human understandable name for each dataset, and a structure on which further descriptive information can be placed.

This document specifies the semantics of a THREDDS catalog, as well as its representation as an XML document. It is written to help clients read and understand THREDDS catalogs received from a server.

Related resources:

Base Catalog Elements

`catalog` Element

<xsd:element name="catalog"> 
  <xsd:complexType>
    <xsd:sequence>
      <xsd:element ref="service" minOccurs="0" maxOccurs="unbounded"/>   
      <xsd:element ref="property" minOccurs="0" maxOccurs="unbounded" /> 
      <xsd:element ref="dataset" minOccurs="1" maxOccurs="unbounded" />  
    </xsd:sequence>

    <xsd:attribute name="base" type="xsd:anyURI"/>  
    <xsd:attribute name="name" type="xsd:string" /> 
    <xsd:attribute name="expires" type="dateType"/>  
    <xsd:attribute name="version" type="xsd:token" default="1.2" />  
  </xsd:complexType>
</xsd:element>

The catalog element is the top-level element. It may contain zero or more service elements, followed by zero or more property elements, followed by one or more dataset type elements. The base is used to resolve any relative URLs in the catalog such as catalogRefs, services, etc. It is usually the URL of the catalog document itself. Optionally, the catalog may have a display name. The option expires attribute indicates when this catalog should be re-read. If not present, assume you must re-read each time. The value of the version attribute indicates the version of the InvCatalog specification to which the catalog conforms.

Example

Here is an example of very simple, useful catalog:

<catalog xmlns="http://www.unidata.ucar.edu/namespaces/thredds/InvCatalog/v1.0">  
  <service name="aggServer" serviceType="DODS"  base="http://acd.ucar.edu/thredds/dodsC/" />
  <dataset name="SAGE III Ozone Loss" urlPath="sage.nc">
    <serviceName>aggServer</serviceName>
  </dataset>
</catalog>

Note the necessary presence of the xml namespace attribute xmlns="http://www.unidata.ucar.edu/namespaces/thredds/InvCatalog/v1.0" on the catalog element.

`service` Element

<xsd:element name="service">  
 <xsd:complexType>
  <xsd:sequence>
    <xsd:element ref="property" minOccurs="0" maxOccurs="unbounded" />  
    <xsd:element ref="service" minOccurs="0" maxOccurs="unbounded" />  
  </xsd:sequence>

  <xsd:attribute name="name" type="xsd:string" use="required" />  
  <xsd:attribute name="base" type="xsd:string" use="required" />  
  <xsd:attribute name="serviceType" type="serviceTypes" use="required" />  
  <xsd:attribute name="desc" type="xsd:string"/>   
  <xsd:attribute name="suffix" type="xsd:string" />  
 </xsd:complexType>
</xsd:element>

A service element represents a data access service and allows basic data access information to be factored out of dataset and access elements.

The name attribute is required and its value must be unique for all service elements within the catalog. These unique names are used in the definition of a dataset access method to refer to a specific service element. The mandatory base attribute and the optional suffix attribute are both used in the construction of the dataset URL (see constructing URLS). The base may be an absolute URL or it may be relative to the catalog’s base URL. The service element has a serviceType attribute whose value is typically one of the serviceType values. The optional desc attribute allows you to give a human-readable description of the service.

A service element may contain 0 or more property elements to allow for the encoding of additional, service-specific information.

Only service element with serviceType="Compound" may have nested service elements. Compound services are used when there is more than one way to access a dataset (e.g., OpenDAP and FTP), and the access URLs are the same except for the service base. Nested service elements may also be used directly by dataset or access elements, and so must have unique names.

Examples

Simple examples of where the base is an absolute URL and a relative to catalog URL:

<service name="mcidasServer" serviceType="ADDE" 
         base="http://thredds.ucar.edu/thredds/adde/" />  <!-- absolute URL -->

<service name="this" serviceType="OPENDAP" base="/thredds/dodsC/" />  <!-- relative URL -->

Note: See the constructing URLS section of this document for more information on how the resolved URL is created.

`dataset` Type

<xsd:element name="dataset" type="DatasetType" />  
<xsd:complexType name="DatasetType">
  <xsd:sequence>
    <xsd:group ref="threddsMetadataGroup" minOccurs="0" maxOccurs="unbounded" />  
    <xsd:element ref="access" minOccurs="0" maxOccurs="unbounded"/>   
    <xsd:element ref="dataset" minOccurs="0" maxOccurs="unbounded"/>  
  </xsd:sequence>

  <xsd:attribute name="name" type="xsd:string" use="required"/>  
  <xsd:attribute name="alias" type="xsd:token"/>                 
  <xsd:attribute name="authority" type="xsd:string"/>            
  <xsd:attribute name="collectionType" type="collectionTypes"/>  <!-- deprecated -->
  <xsd:attribute name="dataType" type="dataTypes"/>              
  <xsd:attribute name="harvest" type="xsd:boolean"/>             
  <xsd:attribute name="ID" type="xsd:token"/>                    
  <xsd:attribute name="restrictAccess" type="xsd:string"/>  

  <xsd:attribute name="serviceName" type="xsd:string" />         
  <xsd:attribute name="urlPath" type="xsd:token" />              
</xsd:complexType>

A dataset element represents a named, logical set of data at a level of granularity appropriate for presentation to a user. A dataset is a directdataset if it contains at least one dataset access method, otherwise it is a container for nested datasets, called a collectionDataset.

A dataset must have a name attribute, and may have other attributes. The name of the dataset should be a human readable name that will be displayed to users.

If an ID attribute is given, its value must be unique within the catalog. We highly recommend that all datasets be given a unique ID. This allows for a number of capabilities including XPath ID reference. A dataset may have a naming authority specified within itself or in a parent dataset. (You may also use an authority element rather than an attribute.) If a dataset has an ID and an authority attribute, then the combination of the two should be globally unique for all time. If the same dataset is specified in multiple catalogs, then the combination of its authority and ID should be identical if possible.

A dataset element contains any number of elements from the threddsMetadataGroup in any order. These are followed by 0 or more access elements, followed by 0 or more nested dataset elements (actually you can use any element in the dataset substitution group: dataset or catalogRef). The data represented by a nested dataset element should be a subset, a specialization or in some other sense “contained” within the data represented by its parent dataset element.

If the harvest attribute is true, then this dataset is available to be placed into digital libraries or other discovery services. Note that the harvest attribute should be carefully placed to get the right level of granularity for digital library entries, and is typically placed on collection datasets.

If you want the same dataset to appear in multiple places in the same catalog, use an alias attribute. Define it in one place (with all appropriate metadata), then wherever else it should appear, make a dataset with an alias to it, whose value is the ID of the defined dataset. (Note, it may not refer to a dataset in another catalog referred to by a catalogRef element.) In this case, any other properties of the dataset are ignored, and the dataset to which the alias refers is used in its place.

The dataset element’s serviceName (which can also be specified as a serviceName element) specifies which service to use for this dataset. As of 5.0, it is optional as long as you specify the dataType or featureType of the dataset. The urlPath attribute, in combination with the applicable service, is used to specify data access methods. When you have more than one way to access a dataset, either explicitly define them using more than one nested access elements, or use a compoundService.

Examples

<dataset name="DC8 flight 1999-11-19" urlPath="SOLVE_DC8_19991119.nc">
  <serviceName>agg</serviceName>
</dataset>

<dataset ID="SOLVE_DC8_19991119" name="DC8 flight 1999-11-19, 1 min merge">
  <metadata xlink:href="http://dataportal.ucar.edu/metadata/tracep_dc8_1min_05"/>
  <access serviceName="disk" urlPath="SOLVE_DC8_19991119.nc"/>
</dataset>

An example using an alias attribute. In this case the dataset referred to logically replaces the alias dataset.

<dataset name="Station Data">
  <dataset name="Metar data" urlPath="cgi-bin/MetarServer.pl?format=qc" />
  <dataset name="Level 3 Radar data" urlPath="cgi-bin/RadarServer.pl?format=qc" />
  <dataset name="Alias to SOLVE dataset" alias="SOLVE_DC8_19991119"/>
</dataset>

`access` Element

<xsd:element name="access">  
  <xsd:complexType>
    <xsd:sequence>
      <xsd:element ref="dataSize" minOccurs="0"/>   
    </xsd:sequence>
    <xsd:attribute name="urlPath" type="xsd:token" use="required"/>   
    <xsd:attribute name="serviceName" type="xsd:string"/>             
    <xsd:attribute name="dataFormat" type="dataFormatTypes"/>         
  </xsd:complexType>
</xsd:element >

An access element specifies how a dataset can be accessed through a data service element. It always refers to the dataset that it is immediately contained within.

The urlPath is appended to the service’s base to get the dataset URL (see constructing URLS). The serviceName refers to the unique name of a service element. The dataFormat is important when the serviceType is a bulk-transport protocol, like FTP or HTTP, as it specifies the format of the transferred file. It is not needed for client/server protocols like OpenDAP or ADDE.

An access element may contain an optional dataSize element to specify how large the dataset would be if it were to be copied to the client.

Example

<access serviceName="ftpServer" urlPath="SOLVE_DC8_19991119.nc" dataFormat="NetCDF" />

`catalogRef` Element

<xsd:element name="catalogRef" substitutionGroup="dataset">
  <xsd:complexType>
    <xsd:complexContent>
      <xsd:extension base="DatasetType">
        <xsd:attributeGroup ref="XLink"/>
      </xsd:extension>
    </xsd:complexContent>
  </xsd:complexType>
</xsd:element>

A catalogRef element refers to another THREDDS catalog that logically is a nested dataset inside this parent catalog. This is used to separately maintain catalogs and to break up large catalogs. THREDDS clients should not read the referenced catalog until the user explicitly requests it, so that very large dataset collections can be represented with catalogRef elements without large delays in presenting them to the user. The referenced catalog is not textually substituted into the containing catalog, but remains a self-contained object. The referenced catalog must be a valid THREDDS catalog, but it does not have to match versions with the containing catalog.

The XLink attributeGroup allows you to add Xlink attributes, a generalization of HTTP hrefs. The value of xlink:href is the URL of the referenced catalog. It may be absolute or relative to the parent catalog URL. The value of xlink:title is displayed as the name of the dataset that the user can click on to follow the XLink.

A catalogRef element is in the dataset substitutionGroup, so it can be used wherever a dataset element can be used. It is an extension of a DatasetType, so any of dataset’s nested elements and attributes can be used in it. This allows you to add enhanced metadata to a catalogRef. However, you should not add nested datasets, as these will be ignored. Furthermore, metadata elements are NOT copied to the referenced catalog, so they are used only to display information to the user before the user downloads the referenced catalog.

Example

<catalogRef xlink:title="NCEP Model Data" xlink:href="http://yerserv/uniModels.xml"/>

`XLink` Attribute Group

<xsd:attributeGroup name="XLink">     
  <xsd:attribute ref="xlink:href" />  
  <xsd:attribute ref="xlink:title" /> 
  <xsd:attribute ref="xlink:show"/>   
  <xsd:attribute ref="xlink:type" />  
</xsd:attributeGroup>

These are attributes from the XLink specification that are used to point to another web resource. The xlink:href attribute is used for the URL of the resource itself. The xlink:title attribute is a human-readable description of the linked resource. THREDDS clients can display the title to the user as appropriate. These are the only two attributes currently used in the THREDDS software. You can also add the xlink:type or xlink:show attributes.

Example

<documentation xlink:href="http://cloud1.arc.nasa.gov/solve/" xlink:title="SOLVE home page"/>

THREDDS Metadata Elements

THREDDS metadata elements are catalog elements that are used in Digital Libraries entries, discovery centers, and for annotation and documentation of datasets.

`threddsMetadataGroup` Element Group

<xsd:group name="threddsMetadataGroup">   
  <xsd:choice minOccurs="0" maxOccurs="unbounded">
    <xsd:element name="documentation" type="documentationType"/>   
    <xsd:element ref="metadata"  />                                
    <xsd:element ref="property"  />   

    <!-- The next group of elements are used primarily for use in Digital Libraries.  -->
    <xsd:element ref="contributor"/>    
    <xsd:element name="creator" type="sourceType"/>             
    <xsd:element name="date" type="dateTypeFormatted"/>         
    <xsd:element name="keyword" type="controlledVocabulary" />  
    <xsd:element name="project" type="controlledVocabulary" />  
    <xsd:element name="publisher" type="sourceType"/>           

    <!-- The next group of elements are used in search services.  -->
    <xsd:element ref="geospatialCoverage"/>    
    <xsd:element name="timeCoverage" type="timeCoverageType"/>   
    <xsd:element ref="variables"/>    

    <xsd:element name="dataType" type="dataTypes"/>            
    <xsd:element name="dataFormat" type="dataFormatTypes"/>    
    <xsd:element name="serviceName" type="xsd:string" />       
    <xsd:element name="authority" type="xsd:string" />         
    <xsd:element ref="dataSize"/>                              
  </xsd:choice>
</xsd:group>

The elements in the threddsMetadataGroup may be used as nested elements of both dataset and metadata elements. There may be any number of them in any order, but more than one geospatialCoverage, timeCoverage, dataType, dataFormat, serviceName, or authority elements will be ignored. A documentation element contains (or points to) human-readable content. Documentation content may be displayed to users by THREDDS clients as appropriate for the situation. A metadata element is a container for machine-readable information structured in XML. A property element is an arbitrary name/value pair.

The next group of elements are used primarily for use in Digital Libraries.

A contributor element is typically a person’s name with an optional role attribute, documenting some person’s contribution to the dataset. A creator element indicates who created the dataset. A date element is used to document various dates associated with the dataset, using one of the date type enumerations. A keyword element is used for library searches, while a project element specifies what scientific project the dataset belongs to. Both the project and keyword elements have type controlledVocabulary, which allows an optional vocabulary attribute to specify if you are using words from a restricted list, for example DIF. A publisher element indicates who is responsible for serving the dataset. Both a contibutor and publisher element use the sourceType definition.

The next group of elements are used in search services.

The geospatialCoverage element specifies a lat/lon bounding box for the data. The timeCoverage element specifies the range of dates that the dataset covers. The variables element specifies the names of variables contained in the datasets, and ways to map the names to standard vocabularies. The dataType element is used to indicate the high-level semantic type of the dataset (e.g., grid, point, trajectory) and can be used by clients to decide how to display the data. The values come from the dataType enumeration which are intended to map to the scientific data types from the Common Data Model (CDM). The dataFormat element indicates the format of the data and is mainly used so clients can determine how to read data that is accessed using a bulk access method. The data format values come from the dataFormat enumeration. The serviceName element is a reference to a service element; its content must match the name of a service element in the catalog. The service referenced by a dataset is used in the construction of access method URLs for that dataset. (This element and the serviceName attribute of an access element are both used in the same way.) The authority element is used to further refine dataset IDs with the goal of allowing for globally unique IDs. The dataSize element can be used to specify how large the dataset would be if it were to be copied to a client.

Including any of these elements in a metadata element with its inherit attribute set to true means that they apply to the containing dataset and any nested datasets.

`documentation` Element

If your intention is to enable THREDDS to write entries into a Digital Library, you should to be aware of how elements are mapped to Digital Libraries. For example, you will probably want to add a documentation element with type summary as its content will be the description of the dataset in the Digital Library entry. Another documentation element you may need has type rights which specifies what restrictions there are on the dataset usage.

Examples

<documentation type="summary"> The SAGE III Ozone Loss and Validation Experiment (SOLVE)
 was a measurement campaign designed to examine the processes controlling ozone levels
 at mid- to high latitudes. Measurements were made in the Arctic high-latitude
 region in winter using the NASA DC-8 and ER-2 aircraft,
 as well as balloon platforms and ground-based instruments. </documentation>

<documentation type="rights"> Users of these data files are expected  to follow the NASA
  ESPO Archive guidelines for use of the SOLVE data, including consulting with the PIs
  of the individual measurements  for interpretation and credit.
</documentation>

<keyword>Ocean Biomass</keyword>

<project vocabulary="DIF">NASA Earth Science Project Office, Ames Research Center</project>

The documentation element may contain arbitrary plain text content, or XHTML. We call this kind of content “human readable” information. It has an optional documentation type attribute, such as summary, funding, history, etc.

The documentation element may also contain an XLink to an HTML or plain text web page. This allows you to point to external web references, and allows you to factor out common documentation which can be referenced from multiple places. Note, it should not link to an XML page (unless its XHTML); instead use the metadata element in these instances.

Examples

<documentation xlink:href="http://espoarchive.nasa.gov/archive/index.html"
    xlink:title="Earth Science Project Office Archives"/>

<documentation>Used in doubled CO2 scenario</documentation>

`documentation` Type

<xsd:complexType name="documentationType" mixed="true">
  <xsd:sequence>
    <xsd:any namespace="http://www.w3.org/1999/xhtml" minOccurs="0" maxOccurs="unbounded"
         processContents="strict"/>
  </xsd:sequence>

  <xsd:attribute name="type" type="documentationEnumTypes"/>
  <xsd:attributeGroup ref="XLink" />
</xsd:complexType>

`metadata` Element

<xsd:element name="metadata">
  <xsd:complexType>
    <xsd:choice>
      <xsd:group ref="threddsMetadataGroup" minOccurs="0" maxOccurs="unbounded" />
      <xsd:any namespace="##other" minOccurs="0" maxOccurs="unbounded" processContents="strict"/>
    </xsd:choice>

    <xsd:attribute name="inherited" type="xsd:boolean" default="false" />
    <xsd:attribute name="metadataType" type="metadataTypeEnum"  />
    <xsd:attributeGroup ref="XLink" />
  </xsd:complexType>
</xsd:element>

A metadata element contains or refers to structured information (in XML) about datasets, which is used by client programs to display, describe, or search for the dataset.
We call this kind of content “machine readable” information.

A metadata element contains any number of elements from the threddsMetadataGroup in any order, OR it contains any other well-formed XML elements, as long as they are in a namespace other than the THREDDS namespace. It may also contain an XLink to another XML document, whose top-level element should be a valid metadata element (see example below). Note, it should not link to an HTML page, use the documentation element instead.

The inherited attribute indicates whether the metadata is inherited by nested datasets. If true, the metadata element becomes logically part of each nested dataset. (The metadata always applies to the containing dataset whether inherited is true or not.)

The metadataType attribute may have any value, but the “well known” values are listed in the metadataType enumeration. To use metadata elements from the threddsMetadataGroup, do not include the metadata type attribute (or set it to “THREDDS”). To use your own elements, give it a metadata type, and add a namespace declaration (see example below).

Examples

<!-- contains THREDDS metadata -->
<metadata inherited="true">
  <contributor role="data manager">John Smith</contributor>
  <keyword>Atmospheric Science</keyword>
  <keyword>Aircraft Measurements</keyword>
  <keyword>Upper Tropospheric Chemistry</keyword>
</metadata>


<!-- link to external file containing THREDDS metadata -->
<metadata xlink:href="http://dataportal.ucar.edu/metadata/solveMetadata.xml"
   xlink:title="Solve metadata" />

If you use an XLink, it should point to a document whose top element is a metadata element, which declares the THREDDS namespace:

<?xml version="1.0" encoding="UTF-8"?>
<metadata  xmlns="http://www.unidata.ucar.edu/namespaces/thredds/InvCatalog/v1.0">
  <contributor role="Investigator">Mashor Mashnor</contributor>

  <abstract>
   This project aims to determine the physiological adaptations of algae to the
   extreme conditions of Antarctica.
  </abstract>

  <publisher>
     <name vocabulary="DIF">AU/AADC</name>
     <long_name vocabulary="DIF">Australian Antarctic Data Centre, Australia</long_name>
     <contact url="http://www.aad.gov.au/default.asp?casid=3786" email="metadata@aad.gov.au"/>
  </publisher>

</metadata>

When using elements from another namespace, all the sub-elements should be in the same namespace, which should be declared in the metadata element:

<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
  <dc:title>Goto considered harmful</dc:title >
  <dc:description>The unbridled use of the go to statement has an immediate consequence
      that it becomes terribly
        hard to find a meaningful set of coordinates in which to describe the process progress.
  </dc:description>
  <dc:author>Edsger W. Dijkstra</dc:author>
</metadata>

If you use an XLink to point to elements from another namespace, add a metadataType attribute:

<metadata xlink:href="http://www.unidata.ucar.edu/metadata/ncep/dif.xml"
    xlink:title="NCEP DIF metadata" metadataType="DublinCore"/>

whose xlink:href should point to a document whose top element is a metadata element, which declares a different namespace. Note, you also still need to declare the THREDDS namespace:

<?xml version="1.0" encoding="UTF-8"?>
<metadata  xmlns="http://www.unidata.ucar.edu/namespaces/thredds/InvCatalog/v1.0"
           xmlns:dc="http://purl.org/dc/elements/1.1/">
  <dc:title>Goto considered harmful</dc:title >
  <dc:description>The unbridled use of the go to statement has an immediate consequence
      that it becomes terribly
        hard to find a meaningful set of coordinates in which to describe the process progress.
  </dc:description>
  <dc:author>Edsger W. Dijkstra</dc:author>
</metadata>

This equivalent declaration makes the other namespace the default namespace:

<?xml version="1.0" encoding="UTF-8"?>
<cat:metadata  xmlns:cat="http://www.unidata.ucar.edu/namespaces/thredds/InvCatalog/v1.0"
               xmlns="http://purl.org/dc/elements/1.1/">
  <title>Goto considered harmful</title >
  <description>The unbridled use of the go to statement has an immediate consequence
      that it becomes terribly
        hard to find a meaningful set of coordinates in which to describe the process progress.
  </description>
  <author>Edsger W. Dijkstra</author>
</cat:metadata>

`property` Element

<xsd:element name="property">
  <xsd:complexType>
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="value" type="xsd:string"/>
  </xsd:complexType>
</xsd:element>

property elements are arbitrary name/value pairs to associate with a catalog, dataset or service element. Properties on datasets are added as global attributes to the THREDDS data model objects. Generally there may be multiple properties having the same name.

Example

<property name="Conventions" value="WRF" />

`source` Type

<xsd:complexType name="sourceType">
  <xsd:sequence>
    <xsd:element name="name" type="controlledVocabulary"/>  
    <xsd:element name="contact">                       
      <xsd:complexType>
        <xsd:attribute name="email" type="xsd:string" use="required"/>   
        <xsd:attribute name="url" type="xsd:anyURI"/>                    
      </xsd:complexType>
    </xsd:element>
  </xsd:sequence>
</xsd:complexType>

This is used by the creator and publisher elements to specify roles of responsibility for the dataset.

The sourceType must have a name element. The name element has an optional vocabulary attribute if it originates from a controlled vocabulary.
A contact element is also required.
The contact element has attributes to specify a web url and an email address.

Example

Here is an example of the sourceType used in a publisher element:

<publisher>
  <name vocabulary="DIF">UCAR/NCAR/CDP > Community Data Portal, National Center for Atmospheric
    Research, University Corporation for Atmospheric Research</name>
  <contact url="http://dataportal.ucar.edu" email="cdp@ucar.edu"/>
</publisher>

`contributor` Element

<xsd:element name="contributor">    
  <xsd:complexType>
    <xsd:simpleContent>
      <xsd:extension base="xsd:string">
        <xsd:attribute name="role" type="xsd:string" use="required"/>    
      </xsd:extension>
    </xsd:simpleContent>
  </xsd:complexType>
</xsd:element>

A contributor element represents a person’s name.
It has an optional role attribute that specifies the role the person plays with regard to this dataset. The roles can be any string (i.e., they are not from a controlled vocabulary).

Example

<contributor role="PI">Jane Doe</contributor>

`geospatialCoverage` Element

<xsd:element name="geospatialCoverage">  
  <xsd:complexType>
   <xsd:sequence>
     <xsd:element name="northsouth" type="spatialRange" minOccurs="0" />    
     <xsd:element name="eastwest" type="spatialRange" minOccurs="0" />      
     <xsd:element name="updown" type="spatialRange" minOccurs="0" />        
     <xsd:element name="name" type="controlledVocabulary" 
                  minOccurs="0" maxOccurs="unbounded"/>   
   </xsd:sequence>

   <xsd:attribute name="zpositive" type="upOrDown" default="up"/>     
  </xsd:complexType>
</xsd:element>

<xsd:complexType name="spatialRange">     
  <xsd:sequence>
    <xsd:element name="start" type="xsd:double"  />
    <xsd:element name="size" type="xsd:double" />
    <xsd:element name="resolution" type="xsd:double" minOccurs="0" />   
    <xsd:element name="units" type="xsd:string" minOccurs="0" />
  </xsd:sequence>
</xsd:complexType>

<xsd:simpleType name="upOrDown">
  <xsd:restriction base="xsd:token">
    <xsd:enumeration value="up"/>
    <xsd:enumeration value="down"/>
  </xsd:restriction>
</xsd:simpleType>

A geospatialCoverage element specifies the lat/lon bounding box, and an altitude range covered by the data.
The northsouth and eastwest elements should both be set to specify a lat/lon bounding box. The default units are degrees_north and degrees_east, respectively.
The updown element specifies the altitude range, with default units in meters.
You can optionally add any number of names to describe the covered region. An important special case is global coverage, in which case you should use the name global (see example below):
A zpositive value of up means that z increases up, like units of height, while a value of down means that z increases downward, like units of pressure or depth.
The spatialRange elements indicate that the range goes from start to start + size.
Use the resolution attribute to indicate the data resolution.

Example

<geospatialCoverage zpositive="down">
  <northsouth>
    <start>10</start>
    <size>80</size>
    <resolution>2</resolution>
    <units>degrees_north</units>
  </northsouth>
  <eastwest>
    <start>-130</start>
    <size>260</size>
    <resolution>2</resolution>
    <units>degrees_east</units>
  </eastwest>
  <updown>
    <start>0</start>
    <size>22</size>
    <resolution>0.5</resolution>
    <units>km</units>
  </updown>
</geospatialCoverage>

<geospatialCoverage>
  <name vocabulary="Thredds">global</name>
</geospatialCoverage>

`timeCoverage` Element

<xsd:complexType name="timeCoverageType">   
  <xsd:sequence>
    <xsd:choice minOccurs="2" maxOccurs="3" >
      <xsd:element name="start" type="dateTypeFormatted"/>   
      <xsd:element name="end" type="dateTypeFormatted"/>     
      <xsd:element name="duration" type="duration"/>         
    </xsd:choice>
    <xsd:element name="resolution" type="duration" minOccurs="0"/>     
  </xsd:sequence>
</xsd:complexType>

The timeCoverage element specifies a date range and is defined by the timeCoverageType. The timeCoverageType’s start element represents the start of the date range. The end element represents the end of the date range. The duration element represents the date range duration. The optional resolution element should be used to indicate the data resolution for time series data.

When using the timeCoverage element, the date range can be specified in one of the following ways:

By giving both a start and an end date element; or
By specifying a start element and a duration element; or
By specifying an end element and a duration element.

Examples

<timeCoverage>
  <start>1999-11-16T12:00:00</start>
  <end>present</end>
</timeCoverage>

<timeCoverage>
  <start>1999-11-16T12:00:00</start>
  <duration>P3M</duration>  <!-- 3 months  -->
</timeCoverage>

<timeCoverage>   <!-- 10 days before the present up to the present -->
  <end>present</end>
  <duration>10 days</duration>
  <resolution>15 minutes</resolution>
</timeCoverage>

`date` Type

<xsd:simpleType name="dateType">
  <xsd:union memberTypes="xsd:date xsd:dateTime udunitDate">
    <xsd:simpleType>
      <xsd:restriction base="xsd:token">
        <xsd:enumeration value="present"/>
      </xsd:restriction>
    </xsd:simpleType>
  </xsd:union>
</xsd:simpleType>

<xsd:simpleType name="udunitDate">
  <xsd:restriction base="xsd:string">
    <xsd:annotation>
      <xsd:documentation>Must conform to complete udunits date string, eg
          "20 days since 1991-01-01"</xsd:documentation>
    </xsd:annotation>
  </xsd:restriction>
</xsd:simpleType>

A dateType follows the W3C Date profile of ISO 8601 for date/time formats. Note that it is a simple type, so that it can be used as the type of an attribute. It can be one of the following:

an xsd:date, with form CCYY-MM-DD
an xsd:dateTime with form CCYY-MM-DDThh:mm:ss, CCYY-MM-DDThh:mm:ssZ or CCYY-MM-DDThh:mm:ss-hh:ss
a valid UDUNITS date string
the string present

Examples

<start>1999-11-16</start>
<start>1999-11-16T12:00:00</start> <!-- implied UTC -->
<start>1999-11-16T12:00:00Z</start> <!-- explicit UTC  -->
<start>1999-11-16T12:00:00-05:00</start> <!-- EST time zone specified -->
<start>20 days since 1991-01-01</start>
<start>present</start>

`dateTypeFormatted` Type

<xsd:complexType name="dateTypeFormatted">
  <xsd:simpleContent>
    <xsd:extension base="dateType">
      <xsd:attribute name="format" type="xsd:string" /> // from java.text.SimpleDateFormat
      <xsd:attribute name="type" type="dateEnumTypes" />
    </xsd:extension>
  </xsd:simpleContent>
</xsd:complexType>

A dateTypeFormatted extends dateType by allowing an optional, user-defined format attribute and an optional type attribute. The format string follows the specification in java.text.SimpleDateFormat. The values of the type attribute are taken from the Dublin Core date types.

Example

<start format="yyyy DDD" type="created">1999 189</start> <!-- year, day of year -->

Example_Format_String	Example_Text
`yyyy.MM.dd G 'at' HH:mm:ss z`	`2001.07.04 AD at 12:08:56 PDT`
`EEE, MMM d, "yy"`	`Wed, Jul 4, '01`
`K:mm a, z`	`0:08 PM, PDT`
`yyyyy.MMMMM.dd GGG hh:mm aaa`	`02001.July.04 AD 12:08 PM`
`EEE, d MMM yyyy HH:mm:ss Z`	`Wed, 4 Jul 2001 12:08:56 -0700`
`yyMMddHHmmssZ`	`010704120856-0700`

`duration` Type

<xsd:simpleType name="duration">
  <xsd:union memberTypes="xsd:duration udunitDuration" />
</xsd:simpleType>

<xsd:simpleType name="udunitDuration">
  <xsd:restriction base="xsd:string">
    <xsd:annotation>
      <xsd:documentation>Must conform to udunits time duration, eg "20.1 hours"
      </xsd:documentation>
    </xsd:annotation>
  </xsd:restriction>
</xsd:simpleType>

A duration type can be one of the following:

an xsd:duration type specified in the following form PnYnMnDTnHnMnS where:
- P indicates the period (required)
- nY indicates the number of years
- nM indicates the number of months
- nD indicates the number of days
- T indicates the start of a time section (required if you are going to specify hours, minutes, or seconds)
- nH indicates the number of hours
- nM indicates the number of minutes
- nS indicates the number of seconds
a valid UDUNITS time duration string.

Example

<duration>P5Y2M10DT15H</duration>
<duration>5 days</duration>

`dataSize` Element

<xsd:element name="dataSize">
  <xsd:complexType>
    <xsd:simpleContent>
    <xsd:extension base="xsd:string">
      <xsd:attribute name="units" type="xsd:string" use="required"/>
    </xsd:extension>
    </xsd:simpleContent>
  </xsd:complexType>
</xsd:element>

A dataSize element is just a number with a units attribute, which should one of the following:

bytes
Kbytes
Mbytes
Gbytes
Tbytes

Example

<dataSize units="Kbytes">123</dataSize>

`controlledVocabulary` Type

<xsd:complexType name="controlledVocabulary">
 <xsd:simpleContent>
  <xsd:extension base="xsd:string">
   <xsd:attribute name="vocabulary" type="xsd:string" />
  </xsd:extension>
 </xsd:simpleContent>
</xsd:complexType>

A controlledVocabulary simply adds an optional vocabulary attribute to the string-valued element, indicating that the value comes from a restricted list.

Example

<name vocabulary="DIF">UCAR/NCAR/CDP</name>

`variables` Element

<xsd:element name="variables">
  <xsd:complexType>
    <xsd:choice>
      <xsd:element ref="variable" minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element ref="variableMap" minOccurs="0"/>
    </xsd:choice>
    <xsd:attribute name="vocabulary" type="variableNameVocabulary" use="optional"/>
    <xsd:attributeGroup ref="XLink"/>
  </xsd:complexType>
</xsd:element>

<xsd:element name="variable">
  <xsd:complexType mixed="true">
    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="vocabulary_name" type="xsd:string" use="optional"/>
    <xsd:attribute name="units" type="xsd:string"/>
  </xsd:complexType>
</xsd:element>

<xsd:element name="variableMap">
  <xsd:complexType>
    <xsd:attributeGroup ref="XLink"/>
  </xsd:complexType>
</xsd:element>

A variables element contains a list of variables OR a variableMap element that refers to another document that contains a list of variables. This element specifies the variables (aka fields or parameters) that are available in the dataset, and associates them with a standard vocabulary of names, through the vocabulary attribute. The optional XLink is a reference to an online resource describing the standard vocabulary.

Each variable element must have a name attribute which contains the name of variable in the dataset. The optional vocabulary_name attribute contains the variables name from a standard vocabulary (specified by the variables element). The units attribute contains the units of the variable in the dataset. The content of the variable element can contain text describing the variable. A variableMap element contains an XLink to variable elements, so that you can factor these out and refer to them from multiple places.

The main purpose of the variables element is to describe a dataset for a search service or digital library.
For example GCMD requires a list of dataset “Parameter Valids” from their controlled vocabulary. A client might want to show those “standard variable names” to a user, since the names may be more meaningful than the actual variable names.

Examples

<variables vocabulary="CF-1.0">
  <variable name="wv" vocabulary_name="Wind Speed" units="m/s">Wind Speed @ surface</variable>
  <variable name="wdir" vocabulary_name="Wind Direction" units= "degrees">
    Wind Direction @ surface
  </variable>
  <variable name="o3c" vocabulary_name="Ozone Concentration" units="g/g">
    Ozone Concentration @ surface
  </variable>
</variables>

<variables vocabulary="GRIB-NCEP" xlink:href="http://www.unidata.ucar.edu//GRIB-NCEPtable2.xml">
  <variableMap xlink:href="../standardQ/Eta.xml" />
</variables>

A variableMap should point to an XML document with a top-level variables element with the THREDDS namespace declared:

<?xml version="1.0" encoding="UTF-8"?>
<variables xmlns="http://www.unidata.ucar.edu/namespaces/thredds/InvCatalog/v1.0" >
  <variable name="wv" vocabulary_name="Wind Speed" units="m/s"/>
  <variable name="wdir" vocabulary_name="Wind Direction" units= "degrees"/>
  <variable name="o3c" vocabulary_name="Ozone Concentration" units="g/g"/>
  ...
</variables>

Other Enumerations

The remaining definitions are all enumerations of “well-known” values. Note that for all of these, any token is a legal value. However, standard software is likely to understand only the values that are explicitly listed. We encourage you to use these well-known values if possible, and to submit new values to the THREDDS mailing list for inclusion in future versions of this schema.

`dataFormat` Enumeration

<!-- DataFormat Types -->
<xsd:simpleType name="dataFormatTypes">
  <xsd:union memberTypes="xsd:token mimeType">
    <xsd:simpleType>
      <xsd:restriction base="xsd:token">
        <xsd:enumeration value="BUFR"/>
        <xsd:enumeration value="ESML"/>
        <xsd:enumeration value="GEMPAK"/>
        <xsd:enumeration value="GINI"/>
        <xsd:enumeration value="GRIB-1"/>
        <xsd:enumeration value="GRIB-2"/>
        <xsd:enumeration value="HDF4"/>
        <xsd:enumeration value="HDF5"/>
        <xsd:enumeration value="McIDAS-AREA"/>
        <xsd:enumeration value="NcML"/>
        <xsd:enumeration value="NetCDF"/>
        <xsd:enumeration value="NetCDF-4"/>
        <xsd:enumeration value="NEXRAD2"/>
        <xsd:enumeration value="NIDS"/>

        <xsd:enumeration value="image/gif"/>
        <xsd:enumeration value="image/jpeg"/>
        <xsd:enumeration value="image/tiff"/>
        <xsd:enumeration value="text/csv"/>
        <xsd:enumeration value="text/html"/>
       <xsd:enumeration value="text/plain"/>
         <xsd:enumeration value="text/tab-separated-values"/>
        <xsd:enumeration value="text/xml"/>
        <xsd:enumeration value="video/mpeg"/>
        <xsd:enumeration value="video/quicktime"/>
        <xsd:enumeration value="video/realtime"/>
      </xsd:restriction>
    </xsd:simpleType>
  </xsd:union>
</xsd:simpleType>

<xsd:simpleType name="mimeType">
  <xsd:restriction base="xsd:token">
    <xsd:annotation>
      <xsd:documentation>any valid mime type
        (see http://www.iana.org/assignments/media-types/)
      </xsd:documentation>
    </xsd:annotation>
  </xsd:restriction>
</xsd:simpleType>

These describe the data formats, used in an access attribute or dataset element, when the service is a bulk-transport protocol (like FTP), and the client has to know how to read the downloaded dataset file.

In addition to the file formats explicitly listed, you can use a mime type. We have listed relevant file formats above.

You can also use your own scientific file format. Send them to us, and we will add it to this list (check to see if it’s a mime type first).

Examples

<dataFormat>NcML</dataFormat>
<dataFormat>image/gif</dataFormat>
<dataFormat>image/jpeg</dataFormat>
<dataFormat>image/png</dataFormat>
<dataFormat>video/mpeg</dataFormat>
<dataFormat>video/quicktime</dataFormat>

`dataType` Enumeration

<xsd:simpleType name="dataTypes">
  <xsd:union memberTypes="xsd:token">
    <xsd:simpleType>
      <xsd:restriction base="xsd:token">
        <xsd:enumeration value="Grid"/>
        <xsd:enumeration value="Image"/>
        <xsd:enumeration value="Point"/>
        <xsd:enumeration value="Radial"/>
        <xsd:enumeration value="Station"/>
        <xsd:enumeration value="Swath"/>
        <xsd:enumeration value="Trajectory"/>
      </xsd:restriction>
    </xsd:simpleType>
  </xsd:union>
</xsd:simpleType>

These are the Feature Types of the datasets, which are used by clients to know how to display the data.

`date` Enumeration

<xsd:simpleType name="dateEnumTypes">
  <xsd:union memberTypes="xsd:token">
    <xsd:simpleType>
      <xsd:restriction base="xsd:token">
        <xsd:enumeration value="created"/>
        <xsd:enumeration value="modified"/>
        <xsd:enumeration value="valid"/>
        <xsd:enumeration value="issued"/>
        <xsd:enumeration value="available"/>
        <xsd:enumeration value="metadataCreated"/>
      </xsd:restriction>
    </xsd:simpleType>
  </xsd:union>
</xsd:simpleType>

The date type enumeration defines a basic set of types for a date element. These values were taken from the Dublin Core metadata set.

This set of values is not exclusive so other values are allowed. Alternate values must be strings that do not contain end-of-line characters or tabs (they must be of the xsd:token data type).

`documentation` Enumeration

<xsd:simpleType name="documentationEnumTypes">
 <xsd:union memberTypes="xsd:token">
  <xsd:simpleType>
   <xsd:restriction base="xsd:token">
     <xsd:enumeration value="funding"/>
     <xsd:enumeration value="history"/>
     <xsd:enumeration value="processing_level"/>
     <xsd:enumeration value="rights"/>
     <xsd:enumeration value="summary"/>
   </xsd:restriction>
  </xsd:simpleType>
 </xsd:union>
</xsd:simpleType>

The documentation type enumeration defines a basic set of types used by the documentation element.

This set of values is not exclusive so other values are allowed. Alternate values must be strings that do not contain end-of-line characters or tabs (they must be of the xsd:token data type).

`metadata` Enumeration

<xsd:simpleType name="metadataTypeEnum">
    <xsd:union memberTypes="xsd:token">
      <xsd:simpleType>
        <xsd:restriction base="xsd:token">
          <xsd:enumeration value="THREDDS"/>
          <xsd:enumeration value="ADN"/>
          <xsd:enumeration value="Aggregation"/>
          <xsd:enumeration value="CatalogGenConfig"/>
          <xsd:enumeration value="DublinCore"/>
          <xsd:enumeration value="DIF"/>
          <xsd:enumeration value="FGDC"/>
          <xsd:enumeration value="LAS"/>
          <xsd:enumeration value="ESG"/>
        <xsd:enumeration value="Other"/>
      </xsd:restriction>
     </xsd:simpleType>
   </xsd:union>
  </xsd:simpleType>

The metadata type enumeration defines a basic set of types used by the metadata element.

This set of values is not exclusive so other values are allowed. Alternate values must be strings that do not contain end-of-line characters or tabs (they must be of the xsd:token data type).

`serviceTypes` Enumeration

<xsd:simpleType name="serviceTypes">
 <xsd:union memberTypes="xsd:token">
  <xsd:simpleType>
   <xsd:restriction base="xsd:token">

    <!-- client/server -->
    <xsd:enumeration value="ADDE"/>
    <xsd:enumeration value="DAP4"/>
    <xsd:enumeration value="DODS"/> <!-- same as OpenDAP -->
    <xsd:enumeration value="OpenDAP"/>
    <xsd:enumeration value="OpenDAPG"/>
    <xsd:enumeration value="NetcdfSubset"/>
    <xsd:enumeration value="CdmRemote"/>
    <xsd:enumeration value="CdmFeature"/>
    <xsd:enumeration value="ncJSON"/>
    <xsd:enumeration value="H5Service"/>

    <!-- bulk transport -->
    <xsd:enumeration value="HTTPServer"/>
    <xsd:enumeration value="FTP"/>
    <xsd:enumeration value="GridFTP"/>
    <xsd:enumeration value="File"/>

    <!-- web services -->
    <xsd:enumeration value="ISO"/>
    <xsd:enumeration value="LAS"/>
    <xsd:enumeration value="LAS"/>
    <xsd:enumeration value="NcML"/>
    <xsd:enumeration value="UDDC"/>
    <xsd:enumeration value="WCS"/>
    <xsd:enumeration value="WMS"/>
    <xsd:enumeration value="WSDL"/>

    <!--offline -->
    <xsd:enumeration value="WebForm"/>

    <!-- THREDDS -->
    <xsd:enumeration value="Catalog"/>
    <xsd:enumeration value="Compound"/>
    <xsd:enumeration value="Resolver"/>
    <xsd:enumeration value="THREDDS"/>
   </xsd:restriction>
  </xsd:simpleType>
 </xsd:union>
</xsd:simpleType>

These are the known service types, used in a service element, that indicate how to access a dataset. A serviceType is similar, but not generally the same as the scheme of a URI, like http:, ftp:, file:, etc. In general, the combination of the serviceType and the dataFormat is intended to be sufficient for a client to access and read the dataset. Additional information can be encoded in service properties.

The OPeNDAP and ADDE service types correspond to the OPeNDAP and ADDE data access protocols. These are client/server protocols that specify both the access (or transport) protocol, and the data model; so no separate dataFormat attribute needed. DODS is a synonym for OPeNDAP; OpenDAP-G corresponds to OPeNDAP over GridFTP.

The next set of service types are all bulk-transfer protocols, and you need to also specify the dataFormat for datasets that use these. FTP is the well-known File Transfer Protocol, and GridFTP is a variant of that used by the Globus Data Grid. The File service is for local files, used for local catalogs or in situations like DODS Aggregation Server configuration. A File dataset is not readable by remote clients. HTTPServer should be used when your file is being served by an HTTP (Web) Server. This is used for bulk-transfer just like FTP, and also can be used by the NetCDF-Java library to access NetCDF files remotely (in that case just make sure the dataset has dataFormatType of NetCDF or NcML).

The LAS service type is for connection to Live Access Servers. WMS, WFS and WCS are for the Web Map, Feature, and Coverage Servers, respectively, from the OpenGIS Consortium. These are still experimental servers, at least for THREDDS. WSDL corresponds to a server using the Web Services Description Language to specify its data services. We do not yet have an example of that within THREDDS.

The WebForm service indicate that the dataset URL will take you to an HTML page where you can presumably order the data in some way, to be delivered later. It’s still a good idea to specify the dataset dataFormatType.

The last set of service types are THREDDS defined types. The Catalog and Resolver types return XML documents over HTTP. These are generally handled internally by THREDDS. A compoundService indicates the service is composed of other services.

`variableNameVocabulary` Enumerations

<xsd:simpleType name="variableNameVocabulary">
  <xsd:union memberTypes="xsd:token">
    <xsd:simpleType>
      <xsd:restriction base="xsd:token">
        <xsd:enumeration value="CF-1.0"/>
        <xsd:enumeration value="DIF"/>
        <xsd:enumeration value="GRIB-1"/>
        <xsd:enumeration value="GRIB-2"/>
      </xsd:restriction>
    </xsd:simpleType>
  </xsd:union>
</xsd:simpleType>

These are the known vocabularies for standard variable names, used in the variables element. CF refers to the Climate and Forecast Conventions metadata conventions for netCDF; they have a list of standard variable names. DIF is Directory Interchange Format from NASA’s Global Change Master Directory, which has a controlled variable classification scheme. The World Meteorological Organization’s GRIB (version 1) data file format defines a set of standard parameters.

You can also use another vocabulary name; send it to us, and we will add it to this list.

Dataset Access Methods

There are two ways a dataset’s access methods can be specified:

A dataset element may include a urlPath attribute. The value of the urlPath attribute along with the dataset default service specify one or more* access methods.
A dataset element may include child access elements. Each access element defines one or more access methods. The values of the access element’s urlPath and serviceName attributes specify one or more access methods. If the access element does not include a serviceName attribute, the dataset default service is used.

(*) Multiple access methods are defined whenever the service element is a compoundService.

Dataset Default Service

There are a number of ways a service element can be referenced by a dataset. When multiple references come into play for a given dataset, the following is the precedence for deciding on the default service to use with access methods:

A dataset may have a serviceName attribute or element directly in it.
A dataset may inherit a serviceName from a parent dataset.
A dataset may contain an access element that defines a serviceName and urlPath.
A dataset may have a featureType or dataType defined and a urlPath, in which case it will use the default services for that type.

Examples

A dataset element has a urlPath attribute and inherits a serviceName from a parent/ancestor dataset. This is a common case as many catalogs will contain datasets that all refer to the same service.

<dataset name="collection of data">
  <metadata inherited="true">
    <serviceName>myservice</serviceName>
  </metadata>
  <dataset name="my dataset" urlPath="myData.nc" />
  <dataset name="our dataset" urlPath="ourData.nc" />
  <dataset name="their dataset" urlPath="theirData.nc" />
  ...
</dataset>

A dataset element has a urlPath attribute and directly contains a serviceName element or attribute.

<dataset name="my dataset" urlPath="myData.nc">
  <serviceName>myservice</serviceName>
</dataset>
   
<dataset name="my dataset" urlPath="myData.nc" serviceName="myservice">

A dataset element contains a child access element.

<dataset name="my dataset">
  <access serviceName="myservice" urlPath="myData.nc" />
</dataset>

A dataset may have a featureType or dataType enumeration defined and a urlPath.

<dataset name="my dataset"  dataType="Grid" urlPath="myData.nc" />  

The standard services for Grids will be used.

Access Methods And Compound Services

Any service element of type Compound used in the construction of access methods results in one access method for each nested service.

Example

<service name="all" serviceType="Compound" base="" >
  <service name="odap" serviceType="OPENDAP" base="/thredds/dodsC/" />
  <service name="wcs" serviceType="WCS" base="/thredds/wcs/" />
</service>
<dataset name="cool data" urlPath="cool/data.nc">
  <serviceName>all</serviceName>
</dataset>

The above results in two access methods for cool data using the urlPath attribute value cool/data.nc:

one using the odap service element and;
the other using the wcs service element

Constructing URLs

A dataset access URL is constructed by concatenating the service base URL with the access urlPath. If the service has a suffix attribute, that is then appended:

URL = service.base + access.urlPath + service.suffix

These operations are straight string concatenations – a slash (/) is not automatically added. If a slash is needed between the base and urlPath, remember to include a trailing slash on the value of the service@base attribute.

Clients have access to each of these elements and may make use of the URL in protocol-specific ways. For example the OPeNDAP protocol appends dds, das, and dods to make the actual calls to the OPeNDAP server.

When a service base is a relative URL, it is resolved against the catalog base URL.

Example

If the catalog base URL is https://thredds.ucar.edu/thredds/dodsC/catalog.xml and a service base is airtemp/, then the resolved base is https://thredds.ucar.edu/thredds/dodsC/airtemp/.

If the service base is /airtemp/, the resolved URL is https://thredds.ucar.edu/thredds/airtemp/.

Dataset Classification

THREDDS Dataset Inventory Catalogs organize and describe collections of data. A catalog can be thought of as a logical directory of data resources available via the Internet. A dataset may be a:

direct dataset (describes how to directly access data over the Internet);
collection dataset (contains other datasets); or
dynamic dataset (content is generated by a call to a server).

Direct Datasets

A direct access dataset has an access URL and a service type (like FTP, DODS, WMS, etc.) that allows a THREDDS-enabled application to directly access its data, using the specified service’s protocol. It is represented simply by a dataset type element.

Collection Datasets

A collection dataset has nested <dataset> elements. We distinguish two types:

A heterogeneous collection dataset may have arbitrarily-deep nested datasets, and there are no constraints on how the datasets are related.
A coherent collection dataset contains nested datasets which must be direct and coherently related. A coherent dataset should have a collectionType attribute that describes the relationship of its nested datasets.

Dynamic Datasets

A dynamic dataset has an access URL and a service type Catalog, or Resolver. Its contents are generated dynamically by making a call to a server, and describe datasets that are constantly changing, and/or are too large to list exhaustively.

A resolver dataset is a kind of query dataset, with service type Resolver. It returns a catalog which must contain either a direct dataset, or a coherent collection dataset. It is typically used to implement a virtual dataset like “latest model run” or “latest measurement” on a real time dataset, where the actual URL must be generated when the user requests it.

A query dataset looks a lot like a catalogRef, since you de-reference a URL and get a catalog back. However, a catalogRef is cacheable, but a query dataset is inherently dynamic, so is not cacheable.

Datasets As Web Resources

Its important to distinguish a THREDDS dataset from its access URL. A dataset can have multiple ways of being accessed, and so have multiple access URLs. But, even in the simple case that a dataset has one access URL, the dataset potentially contains metadata that is not stored with the data pointed to by its access URL. In order to use the full power of THREDDS, you must work with the full dataset object, not just with its access URL.

One way to reference the dataset as a web resource is to use catalog.xml#datasetId, where catalogURL is the URL of a THREDDS catalog, and datasetId is the ID of a dataset inside of that catalog.

Example

http://server:8080/thredds/catalog/grib.v5/gfs_2p5deg/catalog.xml#grib.v5/gfs_2p5deg/TwoD

The reference implementation of THREDDS datasets is the netCDF-Java library, which accepts dataset URLS of the form thredds:catalog.xml#dataset_id, where the thredds: prefix ensures that the URL is understood as a THREDDS catalog and dataset.

In the context of a web browser, the dataset URL is catalog.html?dataset=datasetId, for example

Example

http://localhost:8081/thredds/catalog/GFS_CONUS_80km/catalog.html?dataset=GFS_CONUS_80km/Best

This URL, when sent to a THREDDS Data Server, shows the metadata for the dataset with ID GFS_CONUS_80km/Best in the catalog http://localhost:8081/thredds/catalog/GFS_CONUS_80km/catalog.html.

Client-Side Catalog Specification

Overview

Base Catalog Elements

catalog Element

Example

service Element

Examples

dataset Type

Examples

access Element

Example

catalogRef Element

Example

XLink Attribute Group

Example

THREDDS Metadata Elements

threddsMetadataGroup Element Group

documentation Element

Examples

Examples

documentation Type

metadata Element

Examples

property Element

Example

source Type

Example

contributor Element

Example

geospatialCoverage Element

Example

timeCoverage Element

Examples

date Type

Examples

dateTypeFormatted Type

Example

duration Type

Example

dataSize Element

Example

controlledVocabulary Type

Example

variables Element

Examples

Other Enumerations

dataFormat Enumeration

Examples

dataType Enumeration

date Enumeration

documentation Enumeration

metadata Enumeration

serviceTypes Enumeration

variableNameVocabulary Enumerations

Dataset Access Methods

Dataset Default Service

Examples

Access Methods And Compound Services

Example

Constructing URLs

Example

Dataset Classification

Direct Datasets

Collection Datasets

Dynamic Datasets

Datasets As Web Resources

Example

Example

`catalog` Element

`service` Element

`dataset` Type

`access` Element

`catalogRef` Element

`XLink` Attribute Group

`threddsMetadataGroup` Element Group

`documentation` Element

`documentation` Type

`metadata` Element

`property` Element

`source` Type

`contributor` Element

`geospatialCoverage` Element

`timeCoverage` Element

`date` Type

`dateTypeFormatted` Type

`duration` Type

`dataSize` Element

`controlledVocabulary` Type

`variables` Element

`dataFormat` Enumeration

`dataType` Enumeration

`date` Enumeration

`documentation` Enumeration

`metadata` Enumeration

`serviceTypes` Enumeration

`variableNameVocabulary` Enumerations