THREDDS Reference: TDS Catalog Service

The TDS provides various services for THREDDS catalogs. Catalogs served by the TDS can be subset and/or viewed as HTML. Remote catalogs, if allowed, can be validated, displayed as HTML, or subset.

Configuration

Local catalogs always support subsetting and HTML viewing.

Catalog services on remote catalogs are only allowed if the following is added to the threddsConfig.xml configuration file:

<CatalogServices>
    <allowRemote>true</allowRemote>
</CatalogServices>

Catalog Services for Local TDS Served Catalogs

All catalogs served by a TDS can be operated on with the various catalog services. It does not matter if the catalog is the served version of a TDS catalog configuration file or produced from a datasetScan element.

The path of the request URL identifies the target catalog. The extension on the filename determines whether an XML or HTML view is returned, ".xml" or ".html" respectively.

Subsetting of the catalog is performed if a "dataset" parameter is included in the request. The value of the "dataset" parameter must match the ID of a dataset in the target catalog.

Examples

The following returns an HTML view of the main TDS catalog on motherlode:

http://motherlode.ucar.edu:8080/thredds/catalog.html

The following returns an HTML view of one of the datasets from the same catalog:

http://motherlode.ucar.edu:8080/thredds/catalog.html?dataset=IDD

Catalog Services for Remote Catalog

If enabled (see above), catalog services for remote catalogs must be requested from the following URL:

http://server:port/thredds/remoteCatalogService

The following parameters are recognized:

"catalog": [required] the URI of the target catalog.
"command": [optional] one of the following values: "SHOW", "SUBSET", or "VALIDATE".
"dataset": [optional] used only in (and required in) "SUBSET" requests, gives the ID of a dataset in the target catalog.
"htmlView": [optional] used only in "SUBSET" requests, a value of "false" causes an XML view to be returned, otherwise an HTML view is returned.
"verbose": [optional] used only in "VALIDATE" requests, a value of "true" increases the detail of the validation messages returned.

A few notes on the above parameters:

The values of the "command", "htmlView", and "verbose" parameters are case insensitive.
The target catalog URI must be an absolute URI that references a remote THREDDS catalog.
The default command (i.e., the value used when the request does not include a "command" parameter) depends on whether the request includes a "dataset" parameter. If a "dataset" parameter is included, the command defaults to "SUBSET", otherwise it defaults to "SHOW".

The action performed for each value of the "command" parameter are as follows:

"SHOW" - an HTML view of the entire target catalog is returned.
"SUBSET" - the ID given by the "dataset" parameter is used to find the dataset in the target catalog. If the "htmlView" parameter value is "false", an XML view of a catalog containing only that dataset is returned (this is a logical subset so the dataset contains all inherited metadata). Otherwise, an HTML view of the dataset is returned.
"VALIDATE" - an HTML page is returned which contains THREDDS catalog validation messages (warnings and errors).

Catalog subsetting is done on the logical structure of the catalog rather than directly on the XML. This means that all service elements are included in the catalog and all metadata inherited by the target dataset are included in the resulting dataset.

Examples

The following returns an HTML view of the main TDS catalog on motherlode:

http://server:port/thredds/remoteCatalogService?catalog=http://motherlode.ucar.edu:8080/thredds/catalog.xml

The following returns an HTML view of one of the datasets from the same catalog:

http://server:port/thredds/remoteCatalogService?catalog=http://motherlode.ucar.edu:8080/thredds/catalog.xml&dataset=IDD