Discovery Cast Atom Response Format v1.1

From Earth Science Information Partners (ESIP)

Notice

Introduction

At the NASA Earth Science Data System Working Group meeting in New Orleans on October 21, 2010, a proposal was made to expand the scope of Federated search to cover Discovery more generally, thus bringing into the fold datacasting and servicecasting. Therefore a common Atom response format is needed that extends the Atom Syndication Format (RFC 4287) with extensions specific for Earth science data usage.

Scope

The Response Format is a common format used by OpenSearch, datacasting and servicecasting. However, note that some attributes (e.g., the Geo elements) may be less relevant for certain types of casts.

Namespace

Geo extensions

Adopted from the OpenSearch Geo extension and GeoRSS-Simple specifications. Use the "georss" namespace for defining box, circle, and polygon regions for each entry.

When spatial information is available for a response object, the <georss:box> element should always be provided. Additional spatial elements may be provided along with the <georss:box> element. When this occurs, it is to be assumed that the coordinates of the <georss:box> element represent a Minimum Bounding Rectangle encompassing the object's spatial coverage. If an object's spatial area requires a more complicated representation than that which is available through the usage of the GeoRSS-Simple specification, the GeoRSS GML specification may be used.

It is the responsibility of the OpenSearch client to choose which spatial types it will support. However, since the <georss:box> element is required, a client reading a response formatted according to this specification will always be able to rely on the simple <georss:box> contents.

box (required support)

A bounding box with coordinates (west, south, east, north).

Example:

<georss:box>-180.0 -90.0 180.0 90.0</georss:box>

circle (optional)

A shape containing three coordinates (centerpoint latitude, centerpoint longitude, circle radius), where the lat/lon are in WGS84 format, and radius is in meter units.

Example of radius around a lat/lon point:

<georss:circle>34.0 -118.0 10000</georss:circle>

polygon (optional)

A list of lat-lon pairs in WGS84 format. space-delimited.

Example of radius around a lat/lon point:

<georss:polygon>45.256 -110.45 46.46 -109.48 43.84 -109.86 45.256 -110.45</georss:polygon>

Time extensions

Similar to the OpenSearch Time extension. Use the "time" namespace for defining time start and end for each entry. vallues for times must be in ISO 8601 string format.

Example:

<time:start>2005-01-01T00:00:00Z</time:start>
<time:end>2005-01-01T03:00:00Z</time:end>

rel links

Describes links to external information. These links include a relation and type.

rel

Link type Description
http://esipfed.org/ns/discovery/1.1/data# Default data link. Data Casting Granules. OpenSearch Granules response.
http://esipfed.org/ns/discovery/1.1/browse# Appropriate for smaller browse images. See following for alternate browse links.
http://esipfed.org/ns/discovery/1.1/documentation# Default documentation. See following for alternate documentation links.
http://esipfed.org/ns/discovery/1.1/metadata# Data, collection, and service metadata.
http://esipfed.org/ns/discovery/1.1/collection# Data Casting Collection. Not for OpenSearch Collection response which uses OSDD instead.
http://esipfed.org/ns/discovery/1.1/service# Service Casting.
http://esipfed.org/ns/discovery/1.1/event# Micro-articles of natural phenomenon.
http://esipfed.org/ns/discovery/1.1/feed# Feed of various feeds. Enables hierarchy of feeds.

types

The rel links shall have an expected return type. Currently, there are no constraints on allowed types. Though a mime-type is highly recommended.

Example

<link href="http://host.com/my/file.nc" length="64959344" rel="http://esipfed.org/ns/discovery/1.1/data#" title="Granule File" type="application/x-netcdf" />

Pagination Support

Should we follow something like the OpenSearch convention for pagination? Pagination stats would be under the "opensearch" namespace. rel links to other pages contain precomputed links to the other paged feeds.

Example

<feed>
  ...
  <link href="http://host/to/this/feed" rel="self" />
  <link href="http://host/to/first/page/feed" rel="first" />
  <link href="http://host/to/next/page/feed" rel="next" />
  <link href="http://host/to/last/page/feed" rel="last" />
  <opensearch:totalResults>1000000</opensearch:totalResults>
  <opensearch:startIndex>0</opensearch:startIndex>
  <opensearch:itemsPerPage>10</opensearch:itemsPerPage>
  ...
</feed>

Custom tag extensions

Domain-specific tags can be added with namespace at the top-level of <entry> tags.

Example

<entry>
...
<gesdisc:dayNightFlag>day</gesdisc:dayNightFlag>
...
</entry>

Example ESIP Discovery Atom response

An example of an Atom discovery response feed:

   <?xml version="1.0" encoding="UTF-8"?>
    <feed xmlns="http://www.w3.org/2005/Atom" 
          xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
          xmlns:georss="http://www.georss.org/georss">
      <title>Granules</title> 
      <updated>2010-12-13T18:30:02Z</updated>
      <author>
        <name>A NASA Center</name>
      </author>
      <id>urn:uuid:00000000-0000-0000-0000000000</id>
      <opensearch:totalResults>100000</opensearch:totalResults>
      <opensearch:startIndex>0</opensearch:startIndex>
      <opensearch:itemsPerPage>10</opensearch:itemsPerPage>
      <entry>
          <title>regrid-modis.aqua-avg.1hr.p5deg-v1.0-2005.01.01.blk1.nc</title>
          <link href="http://host.com/my/file.nc" length="64959344" title="Granule File" type="application/x-netcdf" />
          <link href="http://host.com/my/file.nc" length="64959344" rel="http://esipfed.org/ns/discovery/1.1/data#" title="Granule File" type="application/x-netcdf" />
          <georss:box>-180.0 -90.0 180.0 90.0</georss:box>
          <time:start>2005-01-01T00:00:00Z</time:start>
          <time:end>2005-01-01T03:00:00Z</time:end>
          <updated>2008-12-16T15:00:26Z</updated>
      </entry>
  </feed>

References