Difference between revisions of "Discovery Cast Atom Response Format"

From Earth Science Information Partners (ESIP)
 
(One intermediate revision by one other user not shown)
Line 1: Line 1:
== Notice ==
+
== Versions ==
  
This is a working draft document.
+
* [[Discovery Cast Atom Response Format v1.1]] ([[Discovery Change Proposal-1 | DCP-1]], currently open for voting)
We will be adding a version number to this 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>
 

Latest revision as of 11:34, March 11, 2011

Versions