Difference between revisions of "DAP Capabilities"

From OPeNDAP Documentation
(Services)
(Services)
 
(13 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
== Overview ==
 
== Overview ==
  
Develop a definition of what a DAP servers Capabilities response should ;ook like.
+
Develop a definition of what a DAP servers Capabilities response should look like.
 
 
 
 
  
 
==What is a Capabilities response?==
 
==What is a Capabilities response?==
In the world of OGC it's a document that contains a description of the '''ownership''' (ows:ServiceProvider), '''service identification''' (ows:ServiceIdentification), '''service access''' (ows:OperationsMetadata), and '''holdings''' (*:Contents) of the server.
+
In the world of OGC it's a document that contains a description of the  
 
+
; ownership
 +
: (a.k.a  ows:ServiceProvider) Describes contact information and for both an individual and their parent organization for a  specific server instance.
 +
; service identification
 +
: (a.k.a. ows:ServiceIdentification) Provides a collection of keyword metadata and and the name and version number of the service.
 +
; service access
 +
: (a.k.a. ows:OperationsMetadata) Provides a set of service URLs for the OGC service. Since OGC services (all?? I'm not sure) rely on the constraint expression syntax of the URL or POST content  to identify and select data sets, the service components are easily tied to single URLs that identify the place in the URL space that the server will behave a s an OGC type service.
 +
; holdings
 +
: (a.k.a. *:Contents) Provides a catalog, generally flat,  but even when hierarchical must provided in it's entirety. No sub-setting or linking of catalog "nodes" that require making additional queries. This provides the convenience of one stop shopping with the disadvantage of the potential for clients to be overwhelmed by the size of the response.
  
 
==What are we doing now that's similar?==
 
==What are we doing now that's similar?==
Line 17: Line 22:
  
 
==How might a DAP Capabilities response look==
 
==How might a DAP Capabilities response look==
 +
Here are some ideas for components of the response:
 +
 +
 +
Just to start things off, the root element:
 +
<dap:Capabilities>
  
 
=== Ownership ===
 
=== Ownership ===
Line 23: Line 33:
 
     <dap:/Contact>
 
     <dap:/Contact>
  
=== Server-side functions.===
+
=== Holdings/Catalog ===
We need to develop XML machine readable description of server side functions.
+
 
Here's a straw man for geogrid, grid, linear_scale, and version:
+
Probably this would always be a child element of a service declaration.
 +
          <dap:CatalogRoot xlink:href="/opendap/catalog.xml"  xlink:type="simple">
 +
 
 +
What catalog metadata should we provide so that a complete enough picture of the holdings is available? The intent it to make it so that users don't need to delve into the granules to determine if the holding contains the information that they desire. See THREDDS Catalog Metadata section below
  
    <dap:ServerSideFunctions>
 
        <dap:ServerSideFunction>
 
            <dap:Name>geogrid</dap:Name>
 
            <dap:Description>
 
                The geogrid() function applies a constraint given in latitude and
 
                longitude to a DAP Grid variable. The arguments to the function are:
 
                geogrid(variable, top, left, bottom, right[, expression ...]) The
 
                variable is the data to be sub-sampled. The Top, left, bottom, right
 
                are the latitude and longitude coordinates of the northwesterm and
 
                southeastern corners of the selection box. The expressions consist of
 
                one or more quoted relational expressions.  Each relational expression
 
                is applied to the grid using the server's constraint evaluator and the
 
                resulting grid is returned. The expressions may use constants and the
 
                grid's map vectors but may not use any other variables. In particular,
 
                you cannot use the grid values themselves. Two forms of expression are
 
                provided: "var relop const" and "const relop var relop const" Where relop
 
                stands for one of the relational operators, like = and > For example:
 
                grid(sst,"20>TIME>=10") and grid(sst,"20>TIME","TIME>=10") are both legal
 
                and, in this case, also equivalent.
 
            </dap:Description>
 
            <dap:Parameter occurrence="1" presence="required" >
 
                <dap:Name>variable</dap:Name>
 
                <dap:Type>String</dap:Type>
 
                <dap:Description>The name of the Grid variable to subsample.</dap:Description>
 
            </Parameter>
 
            <dap:Parameter occurrence="1" presence="required" >
 
                <dap:Name>top</dap:Name>
 
                <dap:Type>Float</dap:Type>
 
                <dap:Description>Latitude Coordinate</dap:Description>
 
            </Parameter>
 
            <dap:Parameter occurrence="1" presence="required" >
 
                <dap:Name>left</dap:Name>
 
                <dap:Type>Float</dap:Type>
 
                <dap:Description>Longitude Coordinate</dap:Description>
 
            </Parameter>
 
            <dap:Parameter occurrence="1" presence="required" >
 
                <dap:Name>bottom</dap:Name>
 
                <dap:Type>Float</dap:Type>
 
                <dap:Description>Latitude Coordinate</dap:Description>
 
            </Parameter>
 
            <dap:Parameter occurrence="1" presence="required" >
 
                <dap:Name>right</dap:Name>
 
                <dap:Type>Float</dap:Type>
 
                <dap:Description>Longitude Coordinate</dap:Description>
 
            </Parameter>
 
            <dap:Parameter occurrence="*" presence="optional" >
 
                <dap:Name>expression</dap:Name>
 
                <dap:Type>String</dap:Type>
 
                <dap:Description>A Relational Expression</dap:Description>
 
            </Parameter>
 
        </dap:ServerSideFunction>
 
        <dap:ServerSideFunction>
 
            <dap:Name>grid</dap:Name>
 
            <dap:Description>
 
                The grid() function takes a DAP Grid variable and zero or more relational
 
                expressions.  Each relational expression
 
                is applied to the grid using the server's constraint evaluator and the
 
                resulting grid is returned. The expressions may use constants and the
 
                grid's map vectors but may not use any other variables. In particular,
 
                you cannot use the grid values themselves. Two forms of expression are
 
                provided: "var relop const" and "const relop var relop const" Where relop
 
                stands for one of the relational operators, like = and > For example:
 
                grid(sst,"20>TIME>=10") and grid(sst,"20>TIME","TIME>=10") are both legal
 
                and, in this case, also equivalent.
 
            </dap:Description>
 
            <dap:Parameter occurrence="1" presence="required" >
 
                <dap:Name>variable</dap:Name>
 
                <dap:Type>String</dap:Type>
 
                <dap:Description>The name of the Grid variable to subsample.</dap:Description>
 
            </Parameter>
 
            <dap:Parameter occurrence="*" presence="required" >
 
                <dap:Name>expression</dap:Name>
 
                <dap:Type>String</dap:Type>
 
                <dap:Description>A Relational Expression</dap:Description>
 
            </Parameter>
 
        </dap:ServerSideFunction>
 
        <dap:ServerSideFunction>
 
            <dap:Name>linear_scale</dap:Name>
 
            <dap:Description>
 
                The linear_scale() function applies the familiar y = mx + b equation to data.
 
                It has three forms: linear_scale(var), linear_scale(var,scale_factor,add_offset)
 
                linear_scale(var,scale_factor,add_offset,missing_value) If only the name of a
 
                variable is given, the function looks for the COARDS/CF-1.0 scale_factor,
 
                add_offset and missing_value attributes. In the equation, 'm' is scale_factor,
 
                'b' is add_offset and data values that match missing_value are not scaled. If
 
                add_offset cannot be found, it defaults to zero; if missing_value cannot be
 
                found, the test for it is not performed. In the second and third form, if the
 
                given values conflict with the dataset's attributes, the given values override.
 
            </dap:Description>
 
            <dap:Parameter occurrence="1" presence="required" >
 
                <dap:Name>var</dap:Name>
 
                <dap:Type>String</dap:Type>
 
                <dap:Description>The name of the Grid variable to subsample.</dap:Description>
 
            </Parameter>
 
            <dap:Parameter occurrence="1" presence="required" >
 
                <dap:Name>scale_factor</dap:Name>
 
                <dap:Type>Float</dap:Type>
 
                <dap:Description>The "m" in "y = mx + b"</dap:Description>
 
            </Parameter>
 
            <dap:Parameter occurrence="1" presence="required" >
 
                <dap:Name>add_offset</dap:Name>
 
                <dap:Type>String</dap:Type>
 
                <dap:Description>The "b" in "y = mx + b"</dap:Description>
 
            </Parameter>
 
            <dap:Parameter occurrence="1" presence="required" >
 
                <dap:Name>missing_value</dap:Name>
 
                <dap:Type>Float</dap:Type>
 
                <dap:Description>A data values that match missing_value are not scaled.</dap:Description>
 
            </Parameter>
 
        </dap:ServerSideFunction>
 
        <dap:ServerSideFunction>
 
            <dap:Name>version</dap:Name>
 
            <dap:Description>
 
                The version function provides a list of the server-side processing functions
 
                available on a given server along with their versions. For information on a
 
                specific function, call it with no arguments or look at this page.
 
            </dap:Description>
 
        </dap:ServerSideFunction>
 
    </dap:ServerSideFunctions>
 
  
=== Holdings ===
 
          <dap:CatalogRoot xlink:href="/opendap/catalog.xml" >
 
  
  
Line 155: Line 47:
 
     <dap:Services>
 
     <dap:Services>
 
      
 
      
         <dap:ServiceIdentification name="hyrax" base="/opendap/hyrax/" >
+
         <dap:Service name="hyrax" base="/opendap/hyrax/" >
 
           <dap:ServiceType>DAP</dap:ServiceType>
 
           <dap:ServiceType>DAP</dap:ServiceType>
 
           <dap:Version>2.0</dap:Version>
 
           <dap:Version>2.0</dap:Version>
 
           <dap:Version>3.1</dap:Version>
 
           <dap:Version>3.1</dap:Version>
 
           <dap:Version>3.2</dap:Version>
 
           <dap:Version>3.2</dap:Version>
           <dap:CatalogRoot xlink:href="/opendap/catalog.xml" >
+
           <dap:CatalogRoot xlink:href="/opendap/catalog.xml" xlink:type="simple" />
 
           <dap:ReturnFormat>DAP</dap:ReturnFormat>
 
           <dap:ReturnFormat>DAP</dap:ReturnFormat>
 
           <dap:ReturnFormat>NetCDF</dap:ReturnFormat>
 
           <dap:ReturnFormat>NetCDF</dap:ReturnFormat>
         <dap:ServiceIdentification>
+
         <dap:Service>
 
          
 
          
         <dap:ServiceIdentification name="hyrax-WCS" base="/opendap/WCS/" >
+
         <dap:Service name="hyrax-WCS" base="/opendap/WCS/" >
 
           <dap:ServiceType>WCS</dap:ServiceType>
 
           <dap:ServiceType>WCS</dap:ServiceType>
 
           <dap:Version>1.1.2</dap:Version>
 
           <dap:Version>1.1.2</dap:Version>
           <dap:CatalogRoot xlink:href="/opendap/WCS?service=WCS&version=1.1.2&request=GetCapabilities" >
+
           <dap:CatalogRoot  
         <dap:ServiceIdentification>
+
              xlink:href="/opendap/WCS?service=WCS&version=1.1.2&request=GetCapabilities" >
 +
              xlink:type="simple" />
 +
         <dap:Service>
 
          
 
          
 
     </dap:Services>
 
     </dap:Services>
 +
 +
==== Return Types/Formats ====
 +
 +
How do we advertise the different return types/formats available from the Server?
 +
 +
Does each service definition announce a list of return types?
 +
 +
=== Server-side functions.===
 +
We need to develop XML machine readable description of server side functions.
 +
 +
Here's a couple of straw men for geogrid, grid, linear_scale, and version:
 +
 +
With properties as elements:
 +
    <dap:ServerSideFunctions>
 +
        <function>
 +
            <name>grid</name>
 +
            <version>1.0</version>
 +
            <documentation
 +
                xlink:href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#grid"
 +
                xlink:type="simple" />
 +
        <function>
 +
 +
        <function>
 +
            <name>geogrid</name>
 +
            <version>1.1</version>
 +
            <documentation
 +
                xlink:href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#grid"
 +
                xlink:type="simple" />
 +
        <function>
 +
 +
        <function>
 +
            <name>linear_scale</name>
 +
            <version>1.0b1</version>
 +
            <documentation
 +
                xlink:href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#grid"
 +
                xlink:type="simple" />
 +
        <function>
 +
 +
        <function>
 +
            <name>version</name>
 +
            <version>1.0</version>
 +
            <documentation
 +
                xlink:href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#grid"
 +
                xlink:type="simple" />
 +
        <function>
 +
    </dap:ServerSideFunctions>
 +
 +
 +
With properties as attributes
 +
    <dap:ServerSideFunctions>
 +
        <function
 +
            name="grid"
 +
            version="1.0"
 +
            documentation="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#grid" >
 +
        <function
 +
            name="geogrid"
 +
            version="1.1"
 +
            documentation="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#geogrid"/>
 +
        <function
 +
            name="linear_scale"
 +
            version="1.0b1"
 +
            documentation="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#linear_scale"/>
 +
        <function
 +
            name="version"
 +
            version="1.0"
 +
            documentation="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#version"/>
 +
    </dap:ServerSideFunctions>
 +
 +
</dap:Capabilities>

Latest revision as of 19:57, 30 March 2010

1 Overview

Develop a definition of what a DAP servers Capabilities response should look like.

2 What is a Capabilities response?

In the world of OGC it's a document that contains a description of the

ownership
(a.k.a ows:ServiceProvider) Describes contact information and for both an individual and their parent organization for a specific server instance.
service identification
(a.k.a. ows:ServiceIdentification) Provides a collection of keyword metadata and and the name and version number of the service.
service access
(a.k.a. ows:OperationsMetadata) Provides a set of service URLs for the OGC service. Since OGC services (all?? I'm not sure) rely on the constraint expression syntax of the URL or POST content to identify and select data sets, the service components are easily tied to single URLs that identify the place in the URL space that the server will behave a s an OGC type service.
holdings
(a.k.a. *:Contents) Provides a catalog, generally flat, but even when hierarchical must provided in it's entirety. No sub-setting or linking of catalog "nodes" that require making additional queries. This provides the convenience of one stop shopping with the disadvantage of the potential for clients to be overwhelmed by the size of the response.

3 What are we doing now that's similar?

  • Ownership Nothing similar. Data providers can (but none that I have seen have) configure the OLFS to replace the standard documentation found through the Documentation link on every contents.html page. Otherwise they might get an email address about weho to write of the BES sends one in an error. The OLFS saves propagates the email address support@opendap.org from 14 different places in the code through a number of HTML responses . These could be modified by determined Hyrax installer, but it would be a hassle and wouldn't persist between installs. We have no structured response in this regard.
  • Service Identification Nothing similar. In the current version of Hyrax we return an list of the DAP versions the server supports in a larger XML document containing the names and version numbers of the software components running on the server.
  • Service Access Nothing similar
  • Holdings Currently we provide a linked list of holdings through THREDDS catalogs. Our THREDDS catalogs do not contain any THREDDS metadata, (or WCS metadata for that matter)


4 How might a DAP Capabilities response look

Here are some ideas for components of the response:


Just to start things off, the root element:

<dap:Capabilities>

4.1 Ownership

   <dap:Contact>
       <dap:Email>name@org.org</dap:Email>
   <dap:/Contact>

4.2 Holdings/Catalog

Probably this would always be a child element of a service declaration.

         <dap:CatalogRoot xlink:href="/opendap/catalog.xml"  xlink:type="simple">

What catalog metadata should we provide so that a complete enough picture of the holdings is available? The intent it to make it so that users don't need to delve into the granules to determine if the holding contains the information that they desire. See THREDDS Catalog Metadata section below



4.3 Services

   <dap:Services>
   
       <dap:Service name="hyrax" base="/opendap/hyrax/" >
         <dap:ServiceType>DAP</dap:ServiceType>
         <dap:Version>2.0</dap:Version>
         <dap:Version>3.1</dap:Version>
         <dap:Version>3.2</dap:Version>
         <dap:CatalogRoot xlink:href="/opendap/catalog.xml" xlink:type="simple" />
         <dap:ReturnFormat>DAP</dap:ReturnFormat>
         <dap:ReturnFormat>NetCDF</dap:ReturnFormat>
       <dap:Service>
       
       <dap:Service name="hyrax-WCS" base="/opendap/WCS/" >
         <dap:ServiceType>WCS</dap:ServiceType>
         <dap:Version>1.1.2</dap:Version>
         <dap:CatalogRoot 
             xlink:href="/opendap/WCS?service=WCS&version=1.1.2&request=GetCapabilities" >
             xlink:type="simple" />
       <dap:Service>
       
   </dap:Services>

4.3.1 Return Types/Formats

How do we advertise the different return types/formats available from the Server?

Does each service definition announce a list of return types?

4.4 Server-side functions.

We need to develop XML machine readable description of server side functions.

Here's a couple of straw men for geogrid, grid, linear_scale, and version:

With properties as elements:

   <dap:ServerSideFunctions>
       <function>
           <name>grid</name>
           <version>1.0</version>
           <documentation 
               xlink:href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#grid" 
               xlink:type="simple" />
       <function>

       <function>
           <name>geogrid</name>
           <version>1.1</version>
           <documentation 
               xlink:href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#grid" 
               xlink:type="simple" />
       <function>

       <function>
           <name>linear_scale</name>
           <version>1.0b1</version>
           <documentation 
               xlink:href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#grid" 
               xlink:type="simple" />
       <function>

       <function>
           <name>version</name>
           <version>1.0</version>
           <documentation 
               xlink:href="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#grid" 
               xlink:type="simple" />
       <function>
   </dap:ServerSideFunctions>


With properties as attributes

   <dap:ServerSideFunctions>
       <function 
           name="grid" 
           version="1.0" 
           documentation="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#grid" >
       <function 
           name="geogrid" 
           version="1.1" 
           documentation="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#geogrid"/>
       <function 
           name="linear_scale" 
           version="1.0b1" 
           documentation="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#linear_scale"/>
       <function 
           name="version" 
           version="1.0" 
           documentation="http://docs.opendap.org/index.php/Server_Side_Processing_Functions#version"/>
   </dap:ServerSideFunctions>
</dap:Capabilities>