Difference between revisions of "Discovery Cast Atom Response Format v1.1"
Line 39: | Line 39: | ||
== rel links == | == rel links == | ||
− | + | We adopt the [http://www.iana.org/assignments/link-relations/link-relations.xhtml values from the registry of the Internet Assigned Numbers Authority (IANA)] conventions where applicable. The IANA rel link types are intended for the simplest cases, where returned items include only one type data link, one type of documentation link, and a small browse image. For deviations from this scenario, such as multiple data links (say, an HDF version and a netCDF version) or documentation links (e.g., User's Guide vs. Quality Guide), the server is expected to use ESIP namespaced rel links. This is also the case for link types that do not map well to an IANA type, such as "event" or "metadata". | |
{| class="wikitable" | {| class="wikitable" | ||
|- | |- | ||
! Link type | ! Link type | ||
− | ! | + | ! Description |
− | |||
|- | |- | ||
− | |||
|enclosure | |enclosure | ||
− | |Default data link. | + | |(IANA) Default data link. Data Casting Granules. OpenSearch Granules response. |
|- | |- | ||
− | |||
|icon | |icon | ||
− | |Appropriate for smaller browse images. See following for alternate browse links. | + | |(IANA) Appropriate for smaller browse images. See following for alternate browse links. |
|- | |- | ||
− | |||
|describedby | |describedby | ||
− | |Default documentation. See following for alternate documentation links. | + | |(IANA) 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# | ||
+ | |Natural phenomenon. | ||
+ | |- | ||
+ | |http://esipfed.org/ns/discovery/1.1/feed# | ||
+ | |Feed of various feeds. | ||
|} | |} | ||
− | + | The ''rel'' links shall have an expected return type. Currently, there are no constraints on allowed types. Though a ''mime-type'' is highly recommended. | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | The ''rel'' links shall have | ||
=== Example === | === Example === | ||
<pre> | <pre> | ||
− | <link href="http://host.com/my/file.nc" length="64959344" rel=" | + | <link href="http://host.com/my/file.nc" length="64959344" rel="enclosure" title="Granule File" type="application/x-netcdf" /> |
</pre> | </pre> | ||
Revision as of 19:53, March 1, 2011
Notice
- This specification is based on DCP-1: ESIP Discovery Cast Atom Response Format v1.1
- This is currently a working draft document.
- See other versions.
- See Discussion Page for discussion of this.
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
- discovery: "http://esipfed.org/ns/discovery/1.1/"
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>
rel links
We adopt the values from the registry of the Internet Assigned Numbers Authority (IANA) conventions where applicable. The IANA rel link types are intended for the simplest cases, where returned items include only one type data link, one type of documentation link, and a small browse image. For deviations from this scenario, such as multiple data links (say, an HDF version and a netCDF version) or documentation links (e.g., User's Guide vs. Quality Guide), the server is expected to use ESIP namespaced rel links. This is also the case for link types that do not map well to an IANA type, such as "event" or "metadata".
Link type | Description |
---|---|
enclosure | (IANA) Default data link. Data Casting Granules. OpenSearch Granules response. |
icon | (IANA) Appropriate for smaller browse images. See following for alternate browse links. |
describedby | (IANA) 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# | Natural phenomenon. |
http://esipfed.org/ns/discovery/1.1/feed# | Feed of various feeds. |
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="enclosure" 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" /> <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>
References
- OpenSearch
- OpenSearch Geo extension
- OpenSearch Time extension
- OpenSearch convention for pagination
- OGC OpenSearch GeoSpatial and Temporal Extensions (link needed)