ldproxy Configuration

(from v2.6.0)

1. Introduction

ldproxy is a software tool to share spatial data according to the W3C/OGC Spatial Data on the Web Best Practices and the draft OGC Web Feature Service standard. ldproxy 1.3.0 supports two data sources: OGC Web Feature Services 2.0 and PostgreSQL/PostGIS databases (PostgreSQL versions 9.5, 9.6, 10.5; PostGIS version 2.4). The ldproxy configuration for a dataset is internally stored in a set of JSON documents.

This ShapeChange target generates ldproxy configurations for data according to one or more application schemas. Currently only PostgreSQL/PostGIS databases are supported at the backend.

2. Description

2.1. Overview

The configuration depends on two aspects:

how the feature types of the application schema(s) are mapped to the database;
how you want the data to appear to users of the API published by ldproxy.

The configuration can be influenced using conversion rules and parameters that are described below.

The following configuration directories and JSON files are created. The JSON files are underlined. The directories and files in red are not created by ShapeChange and have to be created or edited by the administrator as described below.

config-store
- entities
  - services
    
    xyz [the serviceId, see below]
    
    overrides
    
    xyz [the same serviceId]
  - codelists
    
    codelist1 [the name of the code list classifier]
    
    codelist2
    
    …
- settings
  - ldproxy-target-geojson
    
    overrides
    
    GeoJsonConfig
  - ldproxy-target-gml
    
    overrides
    
    GmlConfig
  - xtraplatform-server
    
    CoreServerConfig
  - xtraplatform-auth-external
    
    overrides
    
    ExternalAuthConfig

2.2. The service override configuration file

The additional service override (xyz - see the example below) is a copy of the file with the same name created by ShapeChange. Unchanged JSON members can be removed. The service override at least has to contain the database connection info (JSON path "$.featureProvider.connectionInfo.*") and the coordinate reference system information (JSON path "$.featureProvider.nativeCrs"). For example:


  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

  {
  "id": "xyz",
  "featureProvider": {
    "connectionInfo": {
      "host": "172.17.0.1",
      "database": "postgres",
      "user": "postgres",
      "password": "eHl6Cg=="
    },
    "nativeCrs": {
      "code": 25832
    },
    "providerType": "PGIS"
  }
}

The value of "$.featureProvider.connectionInfo.host" has to be the hostname that is reachable from the ldproxy docker container (see below). In a local test environment where the database is on the same machine, this would typically be "172.17.0.1" (except on macOS, where it is "host.docker.internal").

The value of "$.featureProvider.connectionInfo.password" is the base64 encoded password.

The value of "$.featureProvider.nativeCrs.code" is the integer EPSG code of the coordinate reference system of the geometries in the database. 25832 from the example above is ETRS89 / UTM zone 32N.

In addition, the spatial extents for the feature types in the dataset should be set. The coordinate reference system is WGS 84 longitude/latitude. For feature types with temporal properties the temporal extent should be set, too.

The default values set by ShapeChange are the whole Earth as the spatial extent (-180° to 180° longitude, -90° to 90° latitude) and unlimited temporal extent (indicated by null values). To change this, set the values of "$.featureTypes.\{featureTypeId}.extent.spatial.*" and "$.featureTypes.\{featureTypeId}.extent.temporal.*"


  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

  {
  "id": "xyz",
  "featureProvider": { ...
  },
  "featureTypes": {
    "afeaturetype": {
      "id": "afeaturetype",
      "label": "A Feature Type",
      "description": "A description of the feature type",
      "extent": {
        "spatial": {
          "xmin": 6.1173598760,
          "ymin": 48.9662745077,
          "xmax": 8.5084754437,
          "ymax": 50.9404435711
        },
        "temporal": {
          "start": "2010-01-01T00:00:00Z",
          "end": null
        }
      }
    },
    "anotherfeaturetype": {
      "id": "anotherfeaturetype",
      "label": "Another Feature Type",
      "description": "A description of the feature type",
      "extent": {
        "spatial": {
          "xmin": 6.1173598760,
          "ymin": 48.9662745077,
          "xmax": 8.5084754437,
          "ymax": 50.9404435711
        },
       "temporal": {
         "start": "2010-01-01T00:00:00Z",
         "end": null
       }
     }
   },
   ...
  }
}

2.3. The security configuration file (optional)

If the ldproxy deployment includes services with access control (see the parameter "secured"), the configuration file ExternalAuthConfig has to be provided, too.

See the ldproxy documentation for details.

Example:


  1
2
3
4
5

  {
  "jwtSigningKey" : "eW91ci0yNTYtYml0LXNlY3JldA==",
  "externalDynamicAuthorizationEndpoint": "http://127.0.0.1:10010/authorize",
  "postProcessingEndpoint": "http://127.0.0.1:10010/postprocess"
}

The configuration has to contain either a "$.userInfoEndpoint" or a "$.jwtSigningKey" member for token validation.

If dynamic authorization using JSON XACML is used (JSON path"$.externalDynamicAuthorizationEndpoint"), ldproxy will provide the following attributes in the POST request to the endpoint:

"urn:oasis:names:tc:xacml:1.0:subject:subject-id" is the username, if it can be derived from the token.
"urn:oasis:names:tc:xacml:1.0:resource:resource-id" is the access path of the API for this request.
"urn:oasis:names:tc:xacml:1.0:action:action-id" is always "POST".
"payload" is the base64-encoded JSON payload.

The JSON Web Token is provided in the Authorization header, too.

If the response value is "Deny", ldproxy will reject the request. If the value is "Permit", the request will be processed.

In secured services, ldproxy also supports a preprocessing of the payload of a POST/PUT request to insert or update a feature. If the request has been permitted, the post-processing endpoint (JSON path "$.postProcessingEndpoint") is invoked. The post-processing endpoint has to return an updated feature that will then be inserted/updated in the dataset.

Request:


  1
2
3
4

  {
  "id": "abc",
  ...
}

Response:


  1
2
3
4
5
6
7
8
9

  {
  "id": "abc",
  ...
  "status": 0,
  "createdBy": "johndoe",
  "created": "2018-06-22T11:28:34Z",
  "changedBy": "johndoe",
  "changed": "2018-06-22T11:28:34Z"
}

2.4. The ldproxy deployment

To deploy an instance of ldproxy with the configuration, a docker container with a mounted volume has to be created, for example with the docker command line tool:


  1

  docker run --name ldproxy -d -p 7080:7080 -v /home/user/ldproxy_data:/ldproxy/data iide/ldproxy:v1.3.0

In this example "/home/user/ldproxy_data" has to be the parent directory of the "config-store" directory.

The published services are then available at http://localhost:7080/rest/services.

To change the external URL of a service, see the ldproxy documentation. Public services will typically hide the ldproxy manager. In this case, the value of the external URL (JSON path "$.externalUrl" in CoreServerConfig) from "/rest/services" to the new value.

2.5. Deployment issues

If you encounter issues with the deployment, inspect the log files to determine the cause of the issue. See the ldproxy documentation.

2.6. Limitations

Currently the conversion rules and parameters allow limited control. For example, flattening complex data structures in GeoJSON cannot be activated, the GeoJsonConfig is currently fixed. This may be changed in the future.

3. Configuration

3.1. Class

The class for the target implementation is de.interactive_instruments.ShapeChange.Target.Ldproxy.Config

3.2. Conversion Rules

3.2.1. rule-ldp-prop-all-datatype-relations-as-n-to-m-relations

This rule states that all properties with a value that is a data type are represented in the database using an intermediate table. The name of the table is determined by parameter templateNtoMTable.

Parameter(s):

templateNtoMTable

3.2.2. rule-ldp-prop-all-featuretype-relations-as-n-to-m-relations

This rule states that all properties with a value that is a feature type are represented in the database using an intermediate table. The name of the table is determined by parameter templateNtoMTable.

Parameter(s):

templateNtoMTable

3.2.3. rule-ldp-prop-all-codelist-values-as-strings

This rule states that all properties with a code list value are represented in the database using a string field.

Currently, no other mapping is supported.

Parameter(s): none

3.2.4. rule-ldp-prop-multiple-single-values-as-1-to-n-relations

This rule states that all properties with a value that is a simple value and a maximum multiplicity greater than 1 are represented in the database using a separate table. The name of the table is determined by parameter template1toNTable.

Parameter(s):

template1toNTable

3.2.5. rule-ldp-prop-separate-geometry-table

This rule states that all geometries are stored in a single geometry table (and not directly in the feature tables).

Parameter(s): none

3.2.6. rule-ldp-all-names-in-lowercase

This rule derives all table and field names as lower case from the model.

Currently, no other mapping is supported.

Parameter(s): none

3.2.7. rule-ldp-all-names-max-length

This rule limits table and field names to n characters where n is set using parameter maxLength.

Parameter(s):

maxLength

3.2.8. rule-ldp-cls-non-abstract-feature-types-as-collection

This rule maps all non-abstract feature types to a collection.

Parameter(s): none

3.2.9. rule-ldp-cls-table-per-feature-type

This rule states that all feature type classifiers are mapped to a separate table. I.e., for classes with superclasses, each of them will have a separate table. Each feature will have a row in each of those tables, all with the same identifier.

Note that this rule is a requirement, if the schema includes feature associations that involve non-abstract feature types.

Parameter(s): none

3.2.10. rule-ldp-cls-id-field

Create an id field for each feature or data type table

Parameter(s): none

3.2.11. rule-ldp-cls-generate-codelist

Try to process also the code list values and add a code list file to the configuration.

Parameter(s): none

3.2.12. rule-ldp-cls-oneo-metadata

Add OSIRIS-Neo metadata fields in feature tables. This assumes the following fields in each feature table:

erstelltvon character varying(255)
erstelltam timestamp without time zone
geaendertvon character varying(255)
geaendertam timestamp without time zone

Parameter(s): none

3.3. Parameters

3.3.1. outputDirectory

Required / Optional: optional

Type: String

Default Value: the current directory

Explanation: The directory where the configuration files will be created.