View source for Discovery Cast Atom Response Format v1.1

== Notice ==

This specification is based on the [[Discovery Change Proposal-1 | DCP-1: ESIP Discovery Cast Atom Response Format v1.1]]
This is currently 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 [http://www.ietf.org/rfc/rfc4287.txt 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 ==

Some possible choices include:
* discovery: "http://esipfed.org/ns/discovery/1.1/"
* esipdiscovery: "http://esipfed.org/ns/discovery/1.1/"
* esipfeddiscovery: "http://esipfed.org/ns/discovery/1.1/"

== Geo extensions ==

Similar to the [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Geo/1.0/Draft_1 OpenSearch Geo extension]. Use the "geo" namespace for defining box, radius, and polygon regions for each entry.

=== Example ===
<pre>
<geo:box>-180.0 -90.0 180.0 90.0</geo:box>
</pre>

== Time extensions ==

Similar to the [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Time/1.0/Draft_1 OpenSearch Time extension]. Use the "time" namespace for defining time start and end for each entry. vallues for times must be in [http://en.wikipedia.org/wiki/ISO_8601 ISO 8601] string format.

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

== 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 ===
<pre>
<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" />
</pre>

== Pagination Support ==

Should we follow something like the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements 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 ===
<pre>
<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>
</pre>

== Custom tag extensions ==

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

=== Example ===

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

== Example ESIP Discovery Atom response ==

An example of an Atom discovery response feed:
<pre>
   <?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>
</pre>

== References ==

* [http://www.opensearch.org OpenSearch]
* [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Geo/1.0/Draft_1 OpenSearch Geo extension]
* [http://www.opensearch.org/Specifications/OpenSearch/Extensions/Time/1.0/Draft_1 OpenSearch Time extension]
* [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_response_elements OpenSearch convention for pagination]
* OGC OpenSearch GeoSpatial and Temporal Extensions (link needed)