﻿[[WIS]]

== Web Integration Service

=== GetCapabilities operation

==== Introduction

The Web Integration Service (WIS) is an aggregation service whose only purpose is to provide a list of references to a suite of other, perhaps related OGC services available at an endpoint.
In keeping with the evolutionary refinement and reuse goal stated in Clause 6.1, the web integration service only defines a single operation, GetCapabilities, and responds using a standard OGC capabilities document whose content section lists the available services accessible at that end point.
A web integration service shall implement the KVP-encoding of the GetCapabilities operation.
A web integration service may optionally implement the XML-encoding of the GetCapabilities operation.

==== Request 

===== UML

The following figure defines the schema of the GetCapabilities request.

[[get_capabilities_uml]]
.UML class diagram for the GetCapabilities operation
image::includes/images/UML_GetCapabilities.png["UML_GetCapabilities",scaledwidth="50%",align="center"]

===== KVP encoding

The KVP encoding of the GetCapabilities request shall be as specified in OGC 06-121r3:2009, 7.2.2.  The value of the service parameter shall be fixed to "WIS".

===== XML encoding

The following XML Schema fragment defines the XML-encoding of the GetCapabilities request.
----
   <xsd:element name="GetCapabilities" type="wfs:GetCapabilitiesType"/>
   <xsd:complexType name="GetCapabilitiesType">
      <xsd:complexContent>
         <xsd:extension base="ows:GetCapabilitiesType">
            <xsd:attribute name="service" type="ows:ServiceType"
                     use="required" fixed="WIS"/>       
         </xsd:extension>
      </xsd:complexContent>
   </xsd:complexType>
----

==== Response

===== UML

The WIS's response to a GetCapabilities request is  essentially a standard OGC capabilities document with a content section composed of zero or more ows:ServiceIdentification sections each describing one OGC web service available at the endpoint.

The following figure defines the schema of the ServiceIdentification section:

[[service_ident_uml]]
.UML class diagram for the ServiceIdentification section
image::includes/images/UML_ServiceIdentification.png["service_ident_uml",scaledwidth="80%",align="center"]

Each service is characterized by its type (i.e. WMS, WMTS, WFS, etc.), the base
URL of the service and the standard ServiceIdentification description of the
service from Web Service Common (see OGC 06-121r9).  

The value of the "type" parameter can be a token – such as the three letter
acronyms commonly used by OGC – or a _<<assoc_service_identifiers,URI identifier>>_ for the service.

The value of the "baseURL" parameter is the service URL to which
GetCapabilities request (see 06-121r9, Clause 7) parameters are appended
to form a valid request URL.

===== XML encoding

The following XML Schema fragment defines the schema for the XML-encoded
response to a WIS GetCapabilities request.

----
   <xsd:element name="Capabilities" type="wis:WIS_CapabilitiesType"/>
   <xsd:complexType name="WIS_CapabilitiesType">
      <xsd:complexContent>
         <xsd:extension base="ows:CapabilitiesBaseType">
            <xsd:sequence>
               <xsd:element ref="wis:Contents"/>
            </xsd:sequence>
         </xsd:extension>
      </xsd:complexContent>
   </xsd:complexType>

   <xsd:element name="Contents" type="wis:ContentsType"/>
   <xsd:complexType name="ContentsType">
      <xsd:sequence>
         <xsd:element ref="wis:Service" maxOccurs="unbounded"/>
      </xsd:sequence>
   </xsd:complexType>

   <xsd:element name="Service" type="wis:ServiceType"/>
   <xsd:complexType name="ServiceType">
      <xsd:sequence>
         <xsd:element ref="ows:ServiceIdentification"/>
      </xsd:sequence>
      <xsd:attribute name="type"
                     type="wis:TokenOrAnyURI" use="required"/>
      <xsd:attribute name="baseUrl" type="xsd:anyURI" use="required"/>
   </xsd:complexType>
   <xsd:simpleType name="TokenOrAnyURI">
      <xsd:union memberTypes="xsd:token xsd:anyURI"/>
   </xsd:simpleType>
----

==== NoOp operation

This engineering report defines an additional WIS operation named "NoOp" that all clients shall ignore.  The NoOp operation only exists to satisfy XML validation requirements for capabilities documents imposed by the Web Service Common standard (see OGC 06-121r9, 7.4.6) which requires that OGC web services implement the GetCapabilities operation plus one additional operation.  Clearly, the web service common standard did not anticipate the usefulness of a service that only implements the GetCapabilities request.  A change request has been posted against OGC 06-121r9 to remove this requirement (see OGC 14-026).

==== Security considerations

Given the focus on security in Testbed-12, it is worth mentioning that the 
content of a WIS capabilities document may be tailored to suite the
authentication level of the user.  An authenticate user may see more services
listed in the capabilities document than a non-authenticated user might.

==== Relationship to CSW

The question may be raised about the difference between a WIS and a CSW
registry service.  Unlike a CSW, the WIS provides a light weight, standalone,
peer-to-peer discovery mechanism that clients may use to interrogate a providers
offerings at an endpoint.  The discovery possible using the WIS is not quite as 
rich as that possible using a CSW but it may be sufficient for many user cases
including the harvesting use case described in
_<<CatPackage,Catalogue extension package>>_ clause.  From an implementation
standpoint, the WIS is certainly a more lightweight implementation.

==== Example

In response to the following request:
----
http://www.somcorp.com/wis?service=WIS&request=GetCapabilities
----
a web integration service might generate the following capabilities document:
----
<?xml version="1.0"?>
<Capabilities version="1.0.0"
   xmlns="http://www.opengis.net/wis/1.0"
   xmlns:ows="http://www.opengis.net/ows/2.0"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xmlns:xml="http://www.w3.org/XML/1998/namespace"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.opengis.net/wis/1.0 wis.xsd">
   <ows:ServiceIdentification>
      <ows:Title>SomeSERV</ows:Title>
      <ows:Abstract xml:lang="en">A suite of OGC web services by Some Corp.</ows:Abstract>
      <ows:ServiceType>SomeSERV</ows:ServiceType>
      <ows:ServiceTypeVersion>7.0.1</ows:ServiceTypeVersion>
   </ows:ServiceIdentification>
   <ows:ServiceProvider>
      <ows:ProviderName>Some Corp.</ows:ProviderName>
      <ows:ProviderSite xlink:href="http://www.somecorp.com"/>
      <ows:ServiceContact>
         <ows:IndividualName>John Smith</ows:IndividualName>
         <ows:PositionName>Senior Developer</ows:PositionName>
         <ows:ContactInfo>
            <ows:Phone>
               <ows:Voice>+1-416-555-1234</ows:Voice>
               <ows:Facsimile>+1-416-555-5678</ows:Facsimile>
            </ows:Phone>
            <ows:Address>
               <ows:DeliveryPoint>1 Main St., Suite 1</ows:DeliveryPoint>
               <ows:City>SomeCity</ows:City>               <ows:AdministrativeArea>SomeProvince</ows:AdministrativeArea>
               <ows:PostalCode>X1X 2Y2</ows:PostalCode>
               <ows:Country>Canada</ows:Country>               <ows:ElectronicMailAddress>jsmith@somecorp.com</ows:ElectronicMailAddress>
            </ows:Address>
         </ows:ContactInfo>
      </ows:ServiceContact>
   </ows:ServiceProvider>
   <ows:OperationsMetadata>
      <ows:Operation name="GetCapabilities">
         <ows:DCP>
            <ows:HTTP>
               <ows:Get xlink:href="http://portal.somecorp.com/somecorp/projects/ows9/someserv.cgi?">
                  <ows:Constraint name="GetEncoding">
                     <ows:AllowedValues>
                        <ows:Value>KVP</ows:Value>
                     </ows:AllowedValues>
                  </ows:Constraint>
               </ows:Get>
            </ows:HTTP>
         </ows:DCP>
         <ows:Parameter name="Format">
            <ows:AllowedValues>
               <ows:Value>application/xml</ows:Value>
               <ows:Value>application/x-bxml</ows:Value>
            </ows:AllowedValues>
         </ows:Parameter>
      </ows:Operation>
      <!-- Clients shall ignore the following operation. -->
      <ows:Operation name="NoOp">
         <ows:DCP>
            <ows:HTTP>
               <ows:Get xlink:href="http://portal.somecorp.com/somecorp/projects/ows9/someserv.cgi?">
               </ows:Get>
            </ows:HTTP>
         </ows:DCP>
      </ows:Operation>
   </ows:OperationsMetadata>
   <Contents>
      <Service type="WMS" baseUrl="http://portal.somecorp.com/somecorp/projects/ows9/someserv.cgi">
         <ows:ServiceIdentification>
            <ows:Title>SomeSERV WMS</ows:Title>
            <ows:Abstract xml:lang="en">OGC-compliant cascading web map server (WMS) by Some Corp.</ows:Abstract>
            <ows:ServiceType>WMS</ows:ServiceType>
            <ows:ServiceTypeVersion>1.3.2</ows:ServiceTypeVersion>
            <ows:ServiceTypeVersion>1.3.1</ows:ServiceTypeVersion>
            <ows:ServiceTypeVersion>1.3.0</ows:ServiceTypeVersion>
            <ows:ServiceTypeVersion>1.1.1</ows:ServiceTypeVersion>
            <ows:ServiceTypeVersion>1.1.0</ows:ServiceTypeVersion>
            <ows:ServiceTypeVersion>1.0.0</ows:ServiceTypeVersion>
         </ows:ServiceIdentification>
      </Service>
      <Service type="WFS" baseUrl="http://portal.somecorp.com/somecorp/projects/ows9/someserv.cgi?DATASTORE=OWS9">
         <ows:ServiceIdentification>
            <ows:Title>The USGS National Map Web Feature Service (subset)</ows:Title>
            <ows:Abstract>This web feature service offers a subset of the USGS National Map. The National Map is a collaborative effort among the USGS and other Federal, State, and local partners to improve and deliver topographic information for the Nation. The geographic information available from The National Map includes hydrography, boundaries, transportation, structures, and land cover. Other types of geographic information can be added within the viewer or brought in with The National Map data into a Geographic Information System to create specific types of maps or map views. The National Map is a significant contribution to the National Spatial Data Infrastructure (NSDI) and currently is being transformed to better serve the geospatial community by providing high quality, integrated geospatial data and improved products and services including new generation digital topographic maps.</ows:Abstract>
            <ows:Keywords>
               <ows:Keyword>WFS</ows:Keyword>
               <ows:Keyword>USGS</ows:Keyword>
               <ows:Keyword>TNM</ows:Keyword>
               <ows:Keyword>Web</ows:Keyword>
               <ows:Keyword>Feature</ows:Keyword>
               <ows:Keyword>Service</ows:Keyword>
               <ows:Keyword>hydrography</ows:Keyword>
               <ows:Keyword>boundaries</ows:Keyword>
               <ows:Keyword>transportation</ows:Keyword>
               <ows:Keyword>structures</ows:Keyword>
               <ows:Keyword>land</ows:Keyword>
               <ows:Keyword>cover</ows:Keyword>
            </ows:Keywords>
            <ows:ServiceType>WFS</ows:ServiceType>
            <ows:ServiceTypeVersion>2.0.0</ows:ServiceTypeVersion>
            <ows:ServiceTypeVersion>1.1.0</ows:ServiceTypeVersion>
            <ows:ServiceTypeVersion>1.0.0</ows:ServiceTypeVersion>
            <ows:Fees>None</ows:Fees>
            <ows:AccessConstraints>None</ows:AccessConstraints>
         </ows:ServiceIdentification>
      </Service>
      <Service type="WFS" baseUrl="http://portal.somecorp.com/somecorp/projects/ows9/someserv.cgi?DATASTORE=STDS">
         <ows:ServiceIdentification>
            <ows:Title>The USGS National Map Web Feature Service (subset)</ows:Title>
            <ows:Abstract>This web feature service offers a subset of the USGS National Map. The National Map is a collaborative effort among the USGS and other Federal, State, and local partners to improve and deliver topographic information for the Nation. The geographic information available from The National Map includes hydrography, boundaries, transportation, structures, and land cover. Other types of geographic information can be added within the viewer or brought in with The National Map data into a Geographic Information System to create specific types of maps or map views. The National Map is a significant contribution to the National Spatial Data Infrastructure (NSDI) and currently is being transformed to better serve the geospatial community by providing high quality, integrated geospatial data and improved products and services including new generation digital topographic maps.</ows:Abstract>
            <ows:Keywords>
               <ows:Keyword>WFS</ows:Keyword>
               <ows:Keyword>USGS</ows:Keyword>
               <ows:Keyword>TNM</ows:Keyword>
               <ows:Keyword>Web</ows:Keyword>
               <ows:Keyword>Feature</ows:Keyword>
               <ows:Keyword>Service</ows:Keyword>
               <ows:Keyword>hydrography</ows:Keyword>
               <ows:Keyword>boundaries</ows:Keyword>
               <ows:Keyword>transportation</ows:Keyword>
               <ows:Keyword>structures</ows:Keyword>
               <ows:Keyword>land</ows:Keyword>
               <ows:Keyword>cover</ows:Keyword>
            </ows:Keywords>
            <ows:ServiceType>WFS</ows:ServiceType>
            <ows:ServiceTypeVersion>2.0.0</ows:ServiceTypeVersion>
            <ows:ServiceTypeVersion>1.1.0</ows:ServiceTypeVersion>
            <ows:ServiceTypeVersion>1.0.0</ows:ServiceTypeVersion>
            <ows:Fees>None</ows:Fees>
            <ows:AccessConstraints>None</ows:AccessConstraints>
         </ows:ServiceIdentification>
      </Service>
      <Service type="WCS" baseUrl="http://portal.somecorp.com/somecorp/projects/ows9/someserv.cgi?DATASTORE=OWS9">
         <ows:ServiceIdentification>
            <ows:Title>SomeSERV WCS - OWS9</ows:Title>
            <ows:Abstract xml:lang="en">OGC-compliant web coverage server (WCS) by Some Corp.</ows:Abstract>
            <ows:ServiceType>WCS</ows:ServiceType>
            <ows:ServiceTypeVersion>1.1.2</ows:ServiceTypeVersion>
            <ows:ServiceTypeVersion>1.1.1</ows:ServiceTypeVersion>
            <ows:ServiceTypeVersion>1.0.0</ows:ServiceTypeVersion>
         </ows:ServiceIdentification>
      </Service>
      <Service type="WCS" baseUrl="http://portal.somecorp.com/somecorp/projects/ows9/someserv.cgi?DATASTORE=STDS">
         <ows:ServiceIdentification>
            <ows:Title>SomeSERV WCS - STDS</ows:Title>
            <ows:Abstract xml:lang="en">OGC-compliant web coverage server (WCS) by Some Corp.</ows:Abstract>
            <ows:ServiceType>WCS</ows:ServiceType>
            <ows:ServiceTypeVersion>1.1.2</ows:ServiceTypeVersion>
            <ows:ServiceTypeVersion>1.1.1</ows:ServiceTypeVersion>
            <ows:ServiceTypeVersion>1.0.0</ows:ServiceTypeVersion>
         </ows:ServiceIdentification>
      </Service>
      <Service type="CSW"         baseUrl="http://portal.somecorp.com/somecorp/projects/ows9/someserv.cgi">
         <ows:ServiceIdentification>
            <ows:Title xml:lang="en-CA">Catalogue Service Web (CSW) by Some Corp.</ows:Title>
            <ows:Abstract xml:lang="en">The Some Corp. Catalog Service Web (CSW) implements a web registry service that complies to the Open Geospatial Consortium Inc.'s Catalogue Service implementation specification V2.0.2 (see 07-006r1) which specifies the interfaces, bindings, and a framework for defining application profiles required to publish and access digital catalogues of metadata for geospatial data, services, and related resource information. Metadata act as generalized properties that can be queried and returned through catalogue services for resource evaluation and invocation or retrieval of the referenced resource.</ows:Abstract>
            <ows:Keywords>
               <ows:Keyword xml:lang="en-CA">catalogue</ows:Keyword>
            </ows:Keywords>
            <ows:ServiceType>CSW</ows:ServiceType>
            <ows:ServiceTypeVersion>2.0.2</ows:ServiceTypeVersion>
            <ows:Fees>none</ows:Fees>
            <ows:AccessConstraints>none</ows:AccessConstraints>
         </ows:ServiceIdentification>
      </Service>
   </Contents>
</Capabilities>
----
Since this capabilities document is composed mostly of standard OGC components it is an easy task to extend an OGC catalogue to consume this document.  The catalogue can then automatically determine which services are offered by this provider and harvest each one in turn also maintaining the associations between the web integration service and its child services.
