﻿[[associations]]
== GetAssociations operation

=== Introduction

When a service provider deploys a suite of OGC web services each component
service typically exists in isolation and external clients are unaware of the
relationships that might exists between these services, their offerings and
other OGC and non-OGC web resources.  The services themselves, however,
typically have much more internal knowledge about such relationships or
associations.  Services know what data sources where accessed to provide their
offerings; they know what other representations might exist, etc.  For example,
a WMS knows if the source data for a layer it offers is a SHAPE file, or a WFS
feature type, or another WMS layer (i.e. cascading), or if a WMTS layer exists
that renders the same information more efficiently.  In short OGC web services
have a lot of internal association knowledge that is currently inaccessible to
client applications, especially catalogues.  A great deal of added value can be
derived if this internal association knowledge can be externalized.
Thus, the scope of this clause is to define methods and apparatus to allow OGC
web services to externalize this internal association knowledge.  This clause
describes how associations between OGC and non-OGC resource can be represented
in XML.  This clause further defines a new operation; named GetAssociations,
that existing OGC web services can implement to allow client applications to
interrogate an OGC web service about its internal association knowledge.

=== Associations

==== Introduction

This clause defines a general XML Schema for representation associations
between two resources.  

An association is logically of the form "SOURCE REL TARGET" where the SOURCE
resource is the subject of a directional RELationship of the specified type
with the TARGET resource (e.g. layer X renders feature type Y).

[[assoc_res_types]]
==== Types of association resources

This engineering report distinguishes two types of resources that may
participate in an association:

. OGC web service resources
. URL-addressable resources 

OGC web service resources are resources that are only accessible from within an
OGC web service.  The classic set of OGC resources -- WMS map, WFS feature type
and WCS coverage -- are examples of OGC web service resources since the only
way to access instances of each is through the services that offer them.  Thus,
OGC web service resources are not addressable using a URL alone.

URL-addressable resources are resources which can be accessed directly via URL.
Many OGC resources are URL-addressable.  Examples include OGC web services,
which are accessible via their _<<baseURL,base URL>>_ or symbology encoding
documents stored in some web-accessible location.  For the purposes of this
engineering report the only recognized URL-addressable OGC resources are those
for which an identifier has been registered with the OGC Naming Authority (OGC
NA).

OGC web service resources are distinguished from URL-addressable resources
because two components are required for access; the _<<baseURL,base URL>>_ of
the OGC web service offering the resource and the service-specific identifier
which locates the resource within the service.

Example: A WMS layer named Foundation"INWATER_1M and served by an OGC WMS would
be identified using the following two components: 

. baseURL of the WMS:		http://www.somecorp.com/wms
. service-specific identifier:	Foundation.INWATERA_1M

Interaction with an OGC web service can only commence once the 
_<<baseURL,base URL>>_ of the service has been discovered.  Communication with
the OGC web service commences with the client obtaining the capabilities
document of the service by appending the appropriate GetCapabilities request
parameters to the previously-discovered _<<baseURL,base URL>>_ of the service.
The service-specific identifiers for the OGC web service resources the service
offers can then be obtained from the capabilities document’s content section.  

==== UML 

The following UML diagram defines the schema of an association.

[[association_uml]]
.UML class diagram for an Association
image::includes/images/UML_Association.png["UML_Association",scaledwidth="60%",align="center"]

[[assoc_xml_encoding]]
==== XML-encoding

The following XML Schema fragments defines the XML-encoding for an association.

----
   <xsd:element name="Association" type="wos:AssociationType"/>
   <xsd:complexType name="AssociationType">
      <xsd:complexContent>
         <xsd:extension base="wis:BaseElementType">
            <xsd:sequence>
               <xsd:element name="Source" type="wos:ResourceType"/>
               <xsd:element name="Target" type="wos:ResourceType"/>
            </xsd:sequence>
            <xsd:attribute name="id"
                           type="wos:TokenOrAnyURI" use="optional"/>
            <xsd:attribute name="rel"
                           type="wos:TokenOrAnyURI" use="required"/>
         </xsd:extension>
      </xsd:complexContent>
   </xsd:complexType>
----

The "Source" parameter shall identify the source resource of the association.

The "Target" parameter shall identify the target resource of the association.

The "rel" parameter shall be used to specify the association type.  The
canonical value of the rel attribute shall either be a token taken from the
IANA Link Relations registry (see RFC 5988) or it shall be a URI registered
with the OGC Naming Authority.  Vendor or domain specific "rel" values may
also be used.  However, this engineering report does not assign any specified
meaning or interpretation to these values.  A association Parser shall not fail
if it encounters an associations with an unrecognized "rel" value and is free
to ignore that association.

The "id" parameter may used to assign an identifier to the association itself.

The following XML fragment defines a reference to a resource that participates
as the source or target of an association.  

----
   <xsd:complexType name="ResourceType">
      <xsd:sequence>
         <xsd:element ref="assoc:Identifier" minOccurs="0"/>
      </xsd:sequence>
      <xsd:attribute name="type" type="assoc:TokenOrAnyURI" use="optional"/>
      <xsd:attribute ref="xlink:href" use="required"/>
   </xsd:complexType>
   <xsd:element name="Identifier">
      <xsd:complexType>
         <xsd:simpleContent>
            <xsd:extension base="xsd:string">
               <xsd:attribute name="namespace" type="xsd:anyURI"/>
            </xsd:extension>
         </xsd:simpleContent>
      </xsd:complexType>
   </xsd:element>
   <xsd:simpleType name="TokenOrAnyURI">
      <xsd:union memberTypes="xsd:token xsd:anyURI"/>
   </xsd:simpleType>
----

If the resource is a _<<assoc_res_types,URL-addressable resource>>_ then its
URL shall be specified using the "xlink:href" parameter and its type shall be
specified using the "type" parameter. The "Identifier" parameter shall be
omitted in this case.  

If the resource is an _<<assoc_res_types,OGC web service resource>>_, then its
_<<baseURL,base URL>>_ shall be specified using the "xlink:href" parameter,
its type shall be specified using the "type" parameter and the service-specific
identifier that locates the  resource within the OGC service offering the
resource shall be specified using the "Identifier" parameter.  If the
service-specific resource identifier within the OGC web service is scoped then
its namespace shall be specified using the "namespace" parameter.  The OGC
service type serving the resource shall be deduced from the specified resource
type.  For example, a WMS layer resource is served by a WMS while a WFS feature
type resource is served by a WFS.

[[assoc_xml_response]]
==== Associations container

The following XML Schema fragment defines a container for a set of associations.

----
   <xsd:element name="Associations">
      <xsd:complexType>
         <xsd:sequence>
            <xsd:element ref="assoc:Association"
                         minOccurs="0" maxOccurs="unbounded"/>
         </xsd:sequence>
         <xsd:attribute name="version" type="xsd:string"
                        use="required" fixed="1.0.0"/>
      </xsd:complexType>
   </xsd:element>
----

The Associations element is a container for zero or more _<<assoc_xml_encoding,Association>>_ elements.

==== MIME type

This engineering report defines the following MIME type to represent an XML
document that encodes a set of associations: *application/ogc-as+xml*.

=== Standard identifiers

The following tables define standard identifiers for resources and association
types used by OGC.  This is by no means a comprehensive list but represents the
main set of OGC web services and their resources.

[[assoc_service_identifiers]]
.Service Type Identifiers
[options="header",width="90%",cols="20%,20%,30%,30%"]
|===
| Title | Description | HTTP-URI form | URN form

| Web Integration Service
| An OGC service whose only function is to identify a collection of other OGC services
| http://www.opengis.net/serviceType/wis
| urn:ogc:serviceType:wis

| Web Feature Service
| An OGC service for serving and managing features
| http://www.opengis.net/serviceType/wfs
| urn:ogc:serviceType:wfs

| Web Object Service
| An OGC service for serving and managing generic (perhaps binary) objects
| http://www.opengis.net/serviceType/wos
| urn:ogc:serviceType:wos

| Web Map Service
| An OGC service that serves maps
| http://www.opengis.net/serviceType/wms
| urn:ogc:serviceType:wms

| Web Map Tiling Service
| An OGC service that serves map tiles
| http://www.opengis.net/serviceType/wmts
| urn:ogc:serviceType:wmts

| Web Processing Service
| An OGC service that exposes Web Processing Services
| http://www.opengis.net/serviceType/wps
| urn:ogc:serviceType:wps

| Web Coverage Service
| An OGC service that serves coverages
| http://www.opengis.net/serviceType/wcs
| urn:ogc:serviceType:wcs

| Catalogue Service
| An OGC catalogue service
| http://www.opengis.net/serviceType/csw
| urn:ogc:serviceType:csw

| Web Registry Service
| A profile of an OGC catalogue service that uses ebRIM as its information model
| http://www.opengis.net/serviceType/wrs
| urn:ogc:serviceType:csw

| Geosynchronization Service
| An OGC service supporting data crowdsourcing.
| http://www.opengis.net/serviceType/gss
| urn:ogc:serviceType:gss
|===

NOTE: A version number may be appended to the end of the HTTP-URI or URN to reference to a specific version of a service.

[[assoc_content_identifiers]]
.Content Type Identifiers
[options="header",width="90%",cols="20%,20%,30%,30%"]
|===
| Title | Description | HTTP-URI form | URN form

| WFS Feature Type
| A feature type offered by an OGC Web Feature Service
| http://www.opengis.net/resourceType/wfs/featureType
| urn:ogc:resourceType:wfs:featureType

| WOS Object      
| A generic object offered by an OGC Web Object Service
| http://www.opengis.net/resourceType/wos/object
| urn:ogc:resourceType:wos:object

| WMS Theme
| A collection of WMS layers.
| http://www.opengis.net/resourceType/wms/theme
| urn:ogc:resourceType:wms:theme

| WMS Layer
| A map layer offered by an OGC Web Map Service
| http://www.opengis.net/resourceType/wms/layer
| urn:ogc:resourceType:wms:layer

| WMTS Theme
| A collection of WMTS layers.
| http://www.opengis.net/resourceType/wmts/theme
| urn:ogc:resourceType:wmts:theme

| WMTS Layer
| A tiles map layer offered by an OGC Web Map Tiling Service
| http://www.opengis.net/resourceType/wmts/layer
| urn:ogc:resourceType:wmts:layer

| WPS Process
| A processing service offered by an OGC Web Processing Service
| http://www.opengis.net/resourceType/wps/process
| urn:ogc:resourceType:wps:process

| WCS Theme
| A collection of WCS coverages
| http://www.opengis.net/resourceType/wcs/theme
| urn:ogc:resourceType:wcs:theme

| WCS Coverage
| A coverage offered by an OGC Web Coverage Service
| http://www.opengis.net/resourceType/wcs/coverage
| urn:ogc:resourceType:wcs:coverage

| Metadata
| A document, conforming to a well-known standard that contains metadata about the resource
| http://www.opengis.net/resourceType/metadata
| urn:ogc:resourceType:metadata

| Dublin Core Metadata
| Metadata about a resource that uses the Dublin Core set of elements
| http://www.opengis.net/resourceType/metadata/dublinCore
| urn:ogc:resourceType:metadata:dublinCore

| Symbology Encoding Document
| A document that encodes symbology in a machine readable format
| http://www.opengis.net/resourceType/symbologyEncoding
| urn:ogc:resourceType:symbologyEncoding
|===

[[assoc_rel_identifiers]]
.Association Type Identifiers
[options="header",width="90%",cols="20%,20%,30%,30%"]
|===
| Title | Description | HTTP-URI form | URN form

| Renders
| Associates two resources where one resource renders another resources (e.g. a WMS layer that renders a WFS feature type)
| http://www.opengis.net/associationType/renders 
| urn:ogc:associationType:renders

| Tiled By
| Associated two resource where one resource is a tiled representation of the other resource (e.g. a WMTS layers that is a tiles representation of a WMS layer)
| http://www.opengis.net/associationType/tiledBy 
| urn:ogc:associationType:tiledBy

| ParentOf
| Associates two resources where one resource is the parent of the other resource.  This is typically used to register a nested hierarchy of resources
| http://www.opengis.net/associationType/parentOf 
| urn:ogc:associationType:parentOf

| Cascades
| Associates two services where one OGC service is using the other OGC service as a data source.  For examples where one WMS "cascades" a number of other WMS's
| http://www.opengis.net/associationType/cascades 
| urn:ogc:associationType:cascades

| CreatedBy
| Associates two services where one is responsible for the other creation
| http://www.opengis.net/associationType/createdBy
| urn:ogc:associationType:createdBy

| Symbolizes
| Associates the symbology encoding document with a WFS Feature Type
| http://www.opengis.net/associationType/symbolizes 
| urn:ogc:associationType:symbolizes

| OperatesOn
| Associates two resources where one operates on the other
| http://www.opengis.net/associationType/operatesOn
| urn:ogc:associationType:operatesOn

| DescribedBy
| Associates two resources where one resource is a description of the other using some metadata standard
| http://www.opengis.net/associationType/describedBy
| urn:ogc:associationType:describedBy
|===

[[getAssociations_request]]
=== GetAssociations operation

==== Introduction

As previously discussed, OGC web services have internal knowledge about what
associations exist between the service, its offerings and other OGC and non-OGC
resources.  The GetAssociations operation is the means by which an OGC web
service may be interrogated about the associations of which it is aware.  

Once externalized in this way, this association information can be automatically
harvested and made discoverable from OGC catalogues creating a richer
environment for discovery.

It is anticipated that existing OGC web services, wishing to participate as part
of an integrated suite of OGC web services, would implement this operation as an
add-on to the existing set of operations that the service implements.

It is further anticipated that this operation shall eventually be defined as a
mandatory operation for all OGC web services in the OGC Web Services Common
standard (see OGC 06-121r9).  The document shall be posted as a change request
against OGC 06-121r9.

==== UML

The following UML diagrams define the request and response for the
GetAssociations operation.

[[get_associations_uml]]
.UML class diagram for the GetAssociations operation
image::includes/images/UML_GetAssociations.png["UML_GetAssociations",scaledwidth="50%",align="center"]

[[get_associations_response_uml]]
.UML class diagram for the GetAssociations response
image::includes/images/UML_Associations.png["UML_Associations",scaledwidth="50%",align="center"]

The mandatory service parameter of the GetAssociations operation shall encode
the service identifier of the service being invoked to execute the operation.

The mandatory version parameter of the GetAssociations operation shall be the
fixed values of "1.0.0".

The optional contents parameter may be used to interrogate the known association
of a specified subset of resources that a service offers.  If the parameter is
omitted the response document shall contains all knows associations.

The optional outputFormat parameter may be used to request the response in a
specific format.  The default value is application/ogc-as+xml (see 8.3.5).
Other output format values are allowed (e.g. a JSON response) to which this
engineering report does not assign any meaning.

==== KVP-encoding

The following table defines the KVP-encoding for the GetAssociations operation.

[[getassociations_kvp_encoding]]
.GetAssociations KVP encoding
[options="header",width="90%",cols="30%,10%,60%"]
|===
| URL Component | O/M | Description

| REQUEST
| M
| Fixed value of GetAssociations

| SERVICE
| M
| Identifier for the service offering the operation

| VERSION
| M
| Fixed value of 1.0.0

| SOURCEID
| O
| A URL reference to a source resource (or the base URL of an OGC service) of an association

| LOCALSOURCEID
| O
| The local identifier of a source resource of an association.  The base URL of the OGC web service offering the resource shall be specified as the value of the SOURCEID parameter

| TARGETID
| O
| A URL reference to a target resource (or the base URL of an OGC service) of an association

| LOCALTARGETID
| O
| The local identifier of a target resource of an association.  The base URL of the OGC web service offering the resource shall be specified as the value of the TARGETID parameter

| REL
| O
| The link relation (or association type) of an association

| OUTPUTFORMAT
| O
| The response format of the operation.  The default values is application/ogc-as+xml.
|===

[[assoc_xml_request]]
==== XML-encoding

The following XML Schema fragment defines the XML-encoding for the
GetAssociations operation.

----
   <xsd:element name="GetAssociations" type="ows:GetAssociationsType"/>
   <xsd:complexType name="GetAssociationsType">
      <xsd:sequence>
         <xsd:element ref="ows:ResponseHandler"
                      minOccurs="0" maxOccurs="unbounded"/>
         <xsd:element name="SourceId"
                      type="assoc:ResourceType" minOccurs="0"/>
         <xsd:element name="TargetId"
                      type="assoc:ResourceType" minOccurs="0"/>
         <xsd:element name="Rel"
                      type="xsd:anyURI" minOccurs="0"/>
      </xsd:sequence>
      <xsd:attribute name="service"
                     type="ows:ServiceType" use="required"/>
      <xsd:attribute name="version" type="xsd:string"
                     use="required" fixed="1.0.0"/>
      <xsd:attribute name="outputFormat"
                     type="xsd:string" default="application/as+xml"/>
   </xsd:complexType>
----

==== /associations resource (REST)

Servers implementing the REST architectural style shall provide a
_/associations_ resource.  The query parameters SOURCEID, LOCALSOURCEID,
TARGET, LOCALTARGETID, REL and OUTPUTFORMAT (see the
_<<getassociations_kvp_encoding,GetAssociations KVP encoding>>_ table) may be
appended to this resource path to query specific association information.

==== Parameter discussion

Without any parameters, an OGC web service implementing the GetAssociations
operation shall return a document containing all known associations.

The function of the parameters defined on the GetAssociations operation is to
provide a rudimentary query capability.  Specifying any of the parameters is
equivalent to defining a query predicate composed of AND'ed equality
expressions.  For example, the following request fragment:

----
... request=GetAssociations&SourceId=urn:uuid:...&Rel=renders ...
----

is equivalent to the query predicate:

----
 (SourceId==urn:uuid:...) AND (Rel==renders)
----

In this example, a service implementing the GetAssociations operation would 
return all associations where "Rel==Renders" for the specified SourceId.

==== Response

The response to a GetAssociations operation, when the output format is the
default value application/ogc-as+xml, shall be a set of associations encoded
as an XML document that validates against the schema describe in the 
_<<getAssociations_response,Associations>>_ clause.

==== Example

In response to the following request for all known associations:

----
<?xml version="1.0"?>
<ows:GetAssociations
   service="WFS"
   version="1.0.0"
   outputFormat="application/ogc-as+xml"
   xmlns:ows="http://www.opengis.net/ows/2.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.opengis.net/ows/2.0 
             http://schemas.opengis/net/ows/2.0/owsGetAssociations.xsd">
</ows:GetAssociations>
----

an OGC web map service might generate the following response:

----
   <?xml version="1.0"?>
   <Associations xmlns="http://www.opengis.net/associations/1.0"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.opengis.net/associations/1.0
                http://schemas.opengis.net/wis/1.0.0/associations.xsd">
      version="1.0.0">
      <Association rel="http://www.opengis.net/associationType/cascades">
         <Source type="http://www.opengis.net/serviceType/wms"
            xlink:href="https://onestop.somecorp.com/somecorp/srvr"/>
         <Target type="http://www.opengis.net/serviceType/wms"
            xlink:href="https://demo.somecorp.com/srvr"/>
      </Association>
      <Association rel="http://www.opengis.net/associationType/cascades">
         <Source type="http://www.opengis.net/resourceType/wms/layer"
            xlink:href="https://onestop.somecorp.com/srvr">
            <Identifier>Demo.Foundation.aerofacp_1m</Identifier>
         </Source>
         <Target type="http://www.opengis.net/resourceType/wms/layer"
            xlink:href="https://demo.somecorp.com/srvr">
            <Identifier>Foundation.aerofacp_1m</Identifier>
         </Target>
      </Association>
      <Association rel="http://www.opengis.net/associationType/tiledBy">
         <Source type="http://www.opengis.net/resourceType/wms/layer"
            xlink:href="https://onestop.somecorp.com/srvr">
            <Identifier>Demo.Foundation.aerofacp_1m</Identifier>
         </Source>
         <Target type="http://www.opengis.net/resourceType/wmts/layer"
            xlink:href="https://demo.somecorp.com/somecorp/srvr">
            <Identifier>Foundation.aerofacp_1m</Identifier>
         </Target>
      </Association>
      <Association rel="http://www.opengis.net/associationType/renders">
         <Source type="http://www.opengis.net/resourceType/wms/layer"
            xlink:href="https://onestop.somecorp.com/srvr">
            <Identifier>Demo.Foundation.aerofacp_1m</Identifier>
         </Source>
         <Target type="http://www.opengis.net/resourceType/wfs/featureType"
            xlink:href="https://demo.somecorp.com/srvr?DATASTORE=Foundation">
            <Identifier namespace="http://www.somecorp.com/ns">aerofacp_1m</Identifier>
         </Target>
      </Association>
      <Association rel="http://www.opengis.net/associationType/renders">
         <Source type="http://www.opengis.net/resourceType/wms/layer"
            xlink:href="https://onestop.somecorp.com/srvr">
            <Identifier>Demo.Foundation.etopo2</Identifier>
         </Source>
         <Target type="http://www.opengis.net/def/resourceType/ogc/wcs/coverage"
            xlink:href="https://demo.somecorp.com/srvr?DATASTORE=Foundation">
            <Identifier>etopo2</Identifier>
         </Target>
      </Association>
   </Associations>
----

=== Harvesting associations into an ebRIM CSW catalogue

To properly harvest the GetAssocations response it is important that each
object returned either as a part of the source or the target also be harvested
into the catalogue. This can accomplished in a number of ways but the following
basic algorithm below should be used as a guideline. 

* Harvest the service the containing the GetAssociations operation first as the
generated UUIDs will be needed to create the proper ebRIM Association objects

* For each Association returned from the GetAssociations response

** Process the Source object

*** Use the Identifier value and the generated ebRIM service id to retrieve the Identifier's ebRIM id

** Process the Target object

*** Use the xlink:href parameter to retrieve the associated ebRIM service id for the Target object in the ebRIM database

**** If the service does not exist in the catalogue it will need to be harvested

*** Use the Identifier value and namespace attribute to retrieve the Identifier's ebRIM id

** Using the ebRIM id retrieved for the Source, the Association's rel attribute value and the ebRIM id retrieved for the Target object, create an ebRIM Association object

* Once all associations have been processed the generated ebRIM Association objects should submitted has part of an ebRIM transaction document

The figure _<<ebRIM_catalogue_view,ebRIM Catalogue View>>_ presents a typical
view of what the various ebRIM Associations might look like in an ebRIM
database once all the appropriate services and other objects have been
successfully harvested.

[[ebRIM_catalogue_view]]
.ebRIM Catalogue View
image::includes/images/ebRIMCatalogueView.png["ebRIM_catalogue_view",scaledwidth="70%",align="center"]
