[[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 _<>_ 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 _<>_ 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 _<>_ 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 _<>_ 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. ---- ---- 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. ---- ---- If the resource is a _<>_ 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 _<>_, then its _<>_ 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. ---- ---- The Associations element is a container for zero or more _<>_ 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. ---- ---- ==== /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 _<>_ 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 _<>_ clause. ==== Example In response to the following request for all known associations: ---- ---- an OGC web map service might generate the following response: ---- version="1.0.0"> Demo.Foundation.aerofacp_1m Foundation.aerofacp_1m Demo.Foundation.aerofacp_1m Foundation.aerofacp_1m Demo.Foundation.aerofacp_1m aerofacp_1m Demo.Foundation.etopo2 etopo2 ---- === 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 _<>_ 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"]