Discovery Cast Atom Response Format

From Earth Science Information Partners (ESIP)

Notice

This is a working draft document.


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.

Namespace

TODO. esip? others?

rel links

Currently, the supported rel links of "http://esipfed.org/ns/discovery/1.1/cast_type#" where "cast_type" is of one of the following values:

  • data
    • Data Casting Granules. OpenSearch Granules response
  • collection
    • Data Casting Collection. Not for OpenSearch Collection response which uses OSDD instead.
  • service
    • Service Casting
  • event
    • natural phenomenon
  • feed
    • feed of various feeds
  • browse
    • browse image
  • documentation
    • arbitrary documentation
  • metadata
    • data and collection metadata

The rel links shall have types. 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" />

Geo extensions

Similar to the OpenSearch Geo extension. Use the "geo" namespace for defining box, radius, and polygon regions for each entry.

Example

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

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>

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" />
          <geo:box>-180.0 -90.0 180.0 90.0</geo: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>

Pagination Support

TODO. 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>