wiki:SecoreUserGuide

SECORE User Guide

SECORE (Semantic Coordinate Reference System Resolver) is a server which resolves CRS URLs into full CRS definitions represented in GML 3.2.1. The implementation constitutes the official resolver of OGC, accessible under http://www.opengis.net/def/crs/... .

This manual, which is taken from Annex A of OGC 11-135 ''CRS Name Type Specification'' describes the interface of SECORE. It delivers definitions identified by CRS and Axis URIs, provides CRS Parametrized definitions, and builds CRS specifications through composition and concatenation.

1 Implementation and availability

The source code of this CRS Name Resolver, SECORE, is provided open-source under GNU LGPL as part of the rasdaman software available from rasdaman.org. SECORE is implemented in Java using the BaseX embedded XML database system. In the rasdaman source tree it can be found in subdirectory applications/secore.

2 Service elements

The OGC CRS Name Resolver accepts Axis Identifiers, CRS Identifiers, and CRS Template Identifiers as input URLs. Further, it accepts general XQuery requests on its CRS database.

3 Service URI

The OGC CRS Name Resolver is accessible at the following service endpoint:

4 Service syntax

The OGC CRS Name Resolver accepts queries in GET-KVP and RESTful syntax as defined in this Name Type Specification.

5 Resolution

Resolution of a CRS URL results in either a CRS Definition, a CRS Template, a CRS Set, or an exception. Parameters in the URL query shall all match; non-matching parameters shall raise an exception.

6 CRS Templates

6.1 Overview

CRS Templates are concrete definitions targeted by CRSs parametrized where one or more named parameters allow the customization of one or more elements in the template itself. As such, they describe (possibly infinite) sets of concrete CRSs.

In SECORE, there are 2 files of GML Database (UserDictionary?.xml and GmlDictionary?.xml). User will add/update/delete only in UserDictionary?.xml when GmlDictionary?.xml is conserved.

Note The term "parametrized" is generally avoided because it may lead to confusion with the term “para-metric” in OGC Abstract Topic 2 / ISO 19111-2:2009 which has a significantly different meaning.

Parameters can be resolved through values provided in the CRS URI, or through defaults defined in the CRS Template definition. Additionally, expressions ("formulae") can be associated with a CRS Template which evaluate to values when instantiated with parameter values. All values, whether instantiated in a URL request or coming from a default or a formula, can be substituted in one or several places in the concrete CRS definition associated with the CRS Template.

Example The following URI defines the Auto Orthographic CRS 42003 specified in sub clauses 6.7.3.4 and B.9 of WMS 1.3.0 for “meter” as unit of measure and centred at 100° West longitude and 45° North latitude:

http://www.opengis.net/def/crs?
    authority=OGC&
    version=1.3&
    code=AUTO42003&
    UoM=m&
    CenterLongitude=-100&
    CenterLatitude=45&

Note Additional examples of not-completely-specified objects are specified in sub clauses B.7, B.8, B.10, and B.11 of WMS 1.3.0, and in sub clauses 10.1 through 10.3 of OGC 05-096r1 (GML 3.1.1 grid CRSs profile).

6.2 Structure

Formally, a CRS Template is a GML document with root crsnts:AbstractCRS¬Template. It contains an element crsnts:CrsDefinition of some instantiatable subtype of gml:AbstractCRS together with a list of formal parameters.

Parameters are crsnts:Parameter elements listed in the crsnts:Parameters section. A formal parameter consists of a locally unique name, an XPath target expression indicating one or a set of substitution points relative to the CRS subnode, optionally a default value, and optionally a formula. Further, each parameter has a type associated.

The crsnts:value element contains a well-formed formula adhering to the JSR scripting syntax as specified in JSR-233 [5]. The type associated in the formula’s crsnts:Parameters element denotes the result type of the expression. Names are enclosed in ${ and }; when used in a formula they shall contain only references to parameter names defined in the same CRS Template, and no (direct or indirect) recursive references across formulae.

Note In particular, a formula cannot have its own parameter name as a free parameter. The target expression in crsnts:target indicates the places where, during request evaluation, the resulting parameter (obtained from URL input, or formula evaluation, or by using the default) gets applied to the CRS definition, assuming crsnts:CrsDefinition as the relative document root for XPath evaluation.

Example The following XML snippet defines a geodetic Parametrized CRS with formal parameter x substituting parameter values in all (fictitious) axisName elements appearing the GeodeticCRS root of the CRS definition:

<crsnts:ParameterizedCRS>
  <gml:identifier>...</gml:identifier>
  <gml:scope>...</gml:scope>
  <crsnts:parameters>
    <crsnts:parameter name="lon" >
      <crsnts:value>90</crsnts:value>
      <crsnts:target>//longitude | //Longitude</crsnts:target>
    </crsnts:parameter>
    <crsnts:parameter name="zone">
      <crsnts:target>//greenwichLongitude</crsnts:target>
      <crsnts:value>
        min(floor((${lon} + 180.0) / 6.0) + 1,60)
      </crsnts:value>
    </crsnts:parameter>
  </crsnts:parameters>
  <crsnts:targetReferenceSystem xlink:href="http://www.opengis.net/def/crs/EPSG/0/4326"/>
</crsnts:ParameterizedCRS>

6.3 Resolution

The result of a URI request against a Parametrized CRS depends on the degree of parameter matching, it is GML document with its root being an instantiatable subtype of either gml:AbstractCRS or crsnts:AbstractCRS¬Template. The response is:

  • In case all formal parameters in the Parametrized CRS addressed are matched: a CRS definition where all parameters matched are resolved.

Example Assuming that the name of the above Parametrized CRS example is my-own-crs, a possible instantiation of this CRS to a concrete CRS Identifier is

http://www.opengis.net/def/crs/my-own-crs?lon=47.6

The response to this instantiation is

<gml:GeodeticCRS>
  ...
<gml:GeodeticCRS>
  • In case not all parameters are matched: a Parametrized CRS where all parameters matched are resolved, their corresponding crsnts:Parameter is removed, and only the non-matched parameters remain in the template.

Example Assuming the same example as above, the CRS itself can be obtained through

http://www.opengis.net/def/crs/my-own-crs

The response to this request is

<crsnts:ParameterizedCRS>
  <gml:identifier>...</gml:identifier>
  <gml:scope>...</gml:scope>
  <crsnts:parameters>
    ...
  </crsnts:parameters>
  <crsnts:targetReferenceSystem xlink:href="..."/>
</crsnts:ParameterizedCRS>

7 CRS equality

It is possible that one and the same CRS, axis, etc. is identified by a number of syntactically different URLs, and it is not straightforward for applications to decide about equivalence of two given URIs. To remedy this, a comparison predicate is available in the resolver. A request sent to URL

http://www.opengis.net/def/equal?1=A&2=B

containing two URLs A and B listed as GET/KVP parameters with names 1 and 2, respectively, will result in a response of true if and only if both URLs identify the same concept, and false otherwise; the response is embedded in an XML document.

Example Comparing EPSG codes 4327 and 4326 can be done with this URL:

http://www.opengis.net/def/equal?
  1=http://www.opengis.net/def/crs/EPSG/0/4327
 &2=http://www.opengis.net/def/crs/EPSG/0/4326

The response will look like this:

<crsnts:comparisonResult xmlns='http://www.opengis.net/crs-nts/1.0'>
  <crsnts:equal>false</crsnts:equal>
  <crsnts:reason>
    <![CDATA[ ...description text... ]]>
  </crsnts:reason>
</crsnts:comparisonResult>

8 XQuery

An XQuery GET or POST request sent to URL http://www.opengis.net/def/crs-query will result in a document obtained from evaluating the XQuery request according to the XQuery standard.

9 Exceptions

Exceptions shall be thrown in the situations described in Table 3, with the http code and values indicated there.

Table 3 — CRS resolver exception codes

exceptionCode value HTTP code Meaning of exception code locator value
NO_SUCH_CRS 404 CRS not available on this server. First offending range field name in the parameter list
CANNOT_ENUMERATE_CRS_SET 404 Query resolves to an infinite number of CRSs. none
DUPLICATE_KEY 404 Query contains duplicate keys in the query part. First duplicate
NO_SUCH_KEY 404 Query contains a non-matching key (i.e., a key which has no meaning for the resolver) in the query part. First non-matching key
XQUERY_ERROR 404 XQuery request passed is not well-formed or cannot be evaluated against database contents none
Last modified 22 months ago Last modified on Dec 1, 2015 2:18:23 PM