(since v2.9.0)

This target creates a GeoPackage template from a set of application schemas. The resulting GeoPackage is compliant with the OGC GeoPackage Encoding Standard v1.2.

The overall workflow consists of four steps:

1. Loading the model with the application schema
2. Flattening the schema
3. optional: Executing additional transformations (e.g. for handling keywords)
4. Converting the schema contents to a GeoPackage

Steps 2 and 4 are described in more detail in the following sections.

Pre-Processing: Flattening

In order to achieve a schema structure that can be converted to a GeoPackage, a number of flattening rules need to be executed:

• rule-trf-cls-flatten-inheritance
• rule-trf-prop-flatten-multiplicity
• rule-trf-prop-flatten-types

NOTE: the flattening rules and parameters are documented in detail on the Flattener transformation page.

The following parameters should be set for the flattening transformation:

• maxOccurs: set the default value for representing properties with maximum cardinality > 1
• flattenObjectTypes: setting this parameter to false will result in object types not being flattened, thus allowing the GeoPackage conversion process to generate instructions for creating tables not only for feature types but also for object types.

Conversion to a GeoPackage

Overview

The target creates:

• Feature and Attribute tables from feature and object types, with columns for the properties of these types.
  • NOTE: Object types will only be processed if rule-gpkg-cls-objecttype is enabled.
• Descriptions of the tables and of the columns of the tables, including definitions of the values of enumerations, along with the necessary tables required by the GeoPackage Schema extension. See also the guidance on this extension.
• Spatial Reference System definitions.

NOTE: in v2.9 and v2.10, only columns that refer to enumerations are described (including definitions of the enumerated values). In v2.11 and higher, all columns are described.

Feature and Attribute Tables

A class (excluding data types, unions, code lists, and enumerations) must have at least one property in order to be converted to a table within the GeoPackage. If this requirement is fulfilled, the class is converted to:

• a feature table, if one of the properties is a geometric one
  • The SRS of such tables is defined globally via the configuration parameters organizationCoordSysId and srsOrganization.
• an attribute table, if none of its properties is a geometry property

NOTE: In order for a property to be recognized as a geometric property, the name of its value type must either start with ‘GM_’ or be equal to (ignoring case) ‘DirectPosition’.

NOTE: The table name is computed as described in section Naming.

The properties of the class are converted as described section Property Conversion.

Each table must have a primary key column of type INTEGER. By default, such a column is generated, with the value of target parameter idColumnName as name. The default behavior can be modified using rule-gpkg-cls-identifierStereotype, which supports converting a property of the feature or object type to the primary key column instead (for further details, see the documentation of the rule).

An enumeration with at least one enum is converted to data column constraints of type enum, as defined by the GeoPackage Schema extension (gpkg_schema). The (normalized) name of the enumeration is used as the constraint name, and the name of each enum (not normalized) is used as the constraint value. These constraints will apply to columns that represent properties with the enumeration as value type.

Naming

When converting feature and object types as well as their properties to GeoPackage tables and columns, the names of the model elements are normalized as follows: the name is trimmed, converted to lowercase, and all whitespace characters are replaced with underscores.

The reason for this normalization approach is a recommendation from the GeoPackage getting started guide: For maximum interoperability, start your database identifiers (table names, column names, etc.) with a lowercase character and only use lowercase characters, numbers 0-9, and underscores (_).

NOTE: In the future, the GeoPackage template target can be extended to support different, configurable normalization strategies, much like the SqlDdl target.

Property Conversion

A property is converted as follows:

• If the property has stereotype <<identifier>> and matches rule-gpkg-cls-identifierStereotype, it is converted to a primary key column of type INTEGER.
• If the value type is a geometric type, a geometry column is created, with a GeoPackage geometry type as defined via map entries (also see section Data Types), and the SRS as defined by the configuration parameters organizationCoordSysId and srsOrganization. By default, z and m values are prohibited for a geometry column. However, by setting tagged value gpkgM and gpkgZ on the UML property, or the corresponding target parameters to 1 (values mandatory) or 2 (values optional), these defaults can be overwritten (the setting via tagged value has higher priority than the setting via target parameter).
• If the value type is a code list, then the column type is TEXT.
• If the value type is an enumeration, then the column type is TEXT. Furthermore, if the enumeration has at least one enum, the column is added to the data columns table (defined by the GeoPackage Schema extension), referencing the data constraint defined for the enumeration. That will ensure that the column only has values as defined by the enumeration.
• Otherwise, a normal column is created, with the GeoPackage data type as defined via map entries (also see section Data Types).

If a property is not converted to a primary key column, then:

• the cardinality of the property defines whether the column that represents the property can or cannot be NULL. If the minimum cardinality of the property is 0, then the column can be NULL.
• the initial value of the property is set as the default value of the column.

Data Types

The following GeoPackage types are recognized by the target:

• non-geometric types:
  • BLOB
  • BOOLEAN
  • DATE
  • DATETIME
  • DOUBLE
  • FLOAT
  • INT
  • INTEGER
  • MEDIUMINT
  • REAL
  • SMALLINT
  • TEXT
  • TINYINT
• geometric types:
  • CIRCULARSTRING
  • COMPOUNDCURVE
  • CURVE
  • CURVEPOLYGON
  • GEOMETRY
  • GEOMETRYCOLLECTION
  • LINESTRING
  • MULTICURVE
  • MULTILINESTRING
  • MULTIPOINT
  • MULTIPOLYGON
  • MULTISURFACE
  • POINT
  • POLYGON
  • POLYHEDRALSURFACE
  • SURFACE
  • TIN
  • TRIANGLE

Map entries can map UML types to these GeoPackage types.

Note: If no map entry is defined for the value type of a property, then ShapeChange will assign GeoPackage type TEXT to the resulting column, and log a warning.

Spatial Reference Systems

Feature tables within a GeoPackage, as well as their geometry columns, must be assigned to a specific spatial reference system (SRS). A GeoPackage supports three SRSs by default:

• WGS-84, as defined by organization EPSG for SRS code 4326.
• Undefined cartesian coordinate reference system, with organization NONE and SRS code -1.
• Undefined geographic coordinate reference system, with organization NONE and SRS code 0.

For further details, see the chapter Spatial Reference Systems in the GeoPackage standard.

A GeoPackage also supports other SRSs. They just need to be registered in the GeoPackage, before they can be used.

The configuration of the GeoPackage Template target can include such SRS definitions within the advanced process configuration element. Any such SRS definition will be registered in the GeoPackage created by ShapeChange. One of them can be configured to be used in the definition of feature tables and geometry columns, via the target parameters organizationCoordSysId and srsOrganization.

Documentation

GeoPackage has a few fields where descriptive information of UML model elements can be included. The documentation derived by applying the documentation template as defined by the according target parameter is used to populate the following fields:

• Description of a table (within the gpkg_contents table) that represents a feature or object type.
• Description of a column (within the gpkg_data_columns table)
• Description of an enumerated value (within the gpkg_data_column_constraints table).

Note: in v2.9 and v2.10, only columns that refer to enumerations are described (including definitions of the enumerated values). In v2.11 and higher, all columns are described.

Restrictions

The following restrictions currently apply to this target:

• Properties with maximum multiplicity greater than one cannot be converted. Also, association roles cannot be converted. The OGC GeoPackage Related Tables Extension could provide the means to fully convert such properties in the future.
• GeoPackage does not support feature types with multiple geometric properties. In GeoPackage, a feature has exactly one geometric property. The GeoPackage Template target currently has no specific behavior to encode such feature types, other than encoding a feature type with only one of its geometric properties.
• The target has a single strategy for normalizing the names of classes and properties, when used as table and column names within the resulting GeoPackage. In the future, multiple normalization strategies could be implemented, much like in the SqlDdl target.
• Data type and union classes are not converted. The UML model should be flattened as described in the flattening section, before it is converted into a GeoPackage.

Configuration

Class

The class for the target implementation is de.interactive_instruments.ShapeChange.Target.GeoPackage.GeoPackageTemplate

Rules

An <EncodingRule> element defines an encoding rule.

Example 1:

<EncodingRule name="geopackage">
   <rule name="rule-gpkg-cls-objecttype"/> 
</EncodingRule>

The name attribute of the <EncodingRule> element defines the identifier of the encoding rule to be used. The value of the target parameter defaultEncodingRule must contain this name.

NOTE: The encoding rule with name ‘geopackage’ is pre-configured in ShapeChange. It can thus be used as-is, without the need to explicitly define it in the configuration. It can also be extended as required (see example 2).

The optional extends attribute (shown in example 2) of the <EncodingRule> element includes all rules from the referenced encoding rule in this encoding rule, too.

Example 2:

<EncodingRule name="my_gpkg_rule" extends="geopackage">
  <rule name="rule-gpkg-cls-identifierStereotype"/>
</EncodingRule>

Each <rule> references either a conversion rule or – possibly in the future – a requirement or recommendation to be tested during the validation before the conversion process.

The default behavior of this target is described in the conversion section.

The following sections list the rules that are supported by this target.

rule-gpkg-all-notEncoded

This conversion rule suppresses the conversion of any model elements (more specifically: application schemas, classes, and properties) for which the “gpkgEncodingRule” tag is set to “notEncoded”.

NOTE: The encoding rule “notEncoded” is defined in the standard rules, which can be included in the target configuration via:

<xi:include href=”https://shapechange.net/resources/config/StandardRules.xml” />

rule-gpkg-cls-identifierStereotype

Enables use of stereotype <<identifier>> on class attributes. If an attribute with that stereotype belongs to a class, then the column to represent that attribute will be used as primary key (and no extra identifier column will be generated).

rule-gpkg-cls-objecttype

If this rule is part of the encoding rule, then object types will be converted as well.

Parameters

The <targetParameters> recognized for this target are described in the following sections.

createSpatialIndexes

(since 2.11.0)

Alias: none

Required / Optional: optional

Type: Boolean

Default Value: false

Explanation: When true, spatial indexes are created according to the RTree Spatial Indexes extension.

Applies to Rule(s): none – default behavior

defaultEncodingRule

Alias: none

Required / Optional: optional

Type: String

Default Value: geopackage

Explanation: The identifier of the default encoding rule governing the conversion to a GeoPackage. To use a custom encoding rule defined in the configuration, simply provide the name of the custom encoding rule via this parameter.

Applies to Rule(s): none – default behavior

documentationNoValue

Alias: none

Required / Optional: optional

Type: String

Default Value: “” (i.e., the empty string)

Explanation: If a descriptor is used in the documentation template, but has no value, this parameter will be used. See here for more information about descriptors.

Applies to Rule(s): none – default behavior

documentationTemplate

Alias: none

Required / Optional: optional

Type: String

Default Value: [[definition]]

Explanation:

The template for the documentation that is generated for schema elements. The patterns “[[descriptor]]” will be replaced by the value of the descriptor, or the value of parameter documentationNoValue, if the descriptor has no value for the model element. A single quote will be escaped with two single quotes. See here for more information about descriptors.

Applies to Rule(s): none – default behavior

idColumnName

Alias: none

Required / Optional: optional

Type: String

Default Value: id

Explanation: NOTE: If an <<identifier>> attribute is defined on a class, and rule-gpkg-cls-identifierStereotype is included in the encoding rule, then ShapeChange will not generate an additional identifier column. It will use the column that represents the <<identifier>> attribute as primary key.

Applies to Rule(s): none – default behavior

gpkgM

Alias: none

Required / Optional: optional

Type: Enumeration (0, 1, or 2)

Default Value: 0

Explanation: Global default for the value of field ‘m’ within a geometry column, that represents a geometric property. This value can be overwritten by setting tagged value gpkgM to either 0, 1, or 2 on the geometric property. The values have the following meaning:

• 0 – m values prohibited
• 1 – m values mandatory
• 2 – m values optional

Applies to Rule(s): none – default behavior

gpkgZ

Alias: none

Required / Optional: optional

Type: Enumeration (0, 1, or 2)

Default Value: 0

Explanation: Global default for the value of field ‘z’ within a geometry column, that represents a geometric property. This value can be overwritten by setting tagged value gpkgZ to either 0, 1, or 2 on the geometric property. The values have the following meaning:

• 0 – z values prohibited
• 1 – z values mandatory
• 2 – z values optional

Applies to Rule(s): none – default behavior

organizationCoordSysId

Alias: none

Required / Optional: optional

Type: Integer

Default Value: 4326

Explanation: ID (assigned by the organization from parameter srsOrganization) of the spatial reference system to use for definition of geometry columns. Must be equal to one of the SRS IDs defined via the advanced process configuration (in XML element srsId) or to one of the minimal SRSs defined for a GeoPackage (-1, 0, or 4326).

Applies to Rule(s): none – default behavior

outputDirectory

Alias: none

Required / Optional: optional

Type: String

Default Value: <the current run directory>

Explanation: The path to the folder in which the resulting GeoPackage file will be created.

Applies to Rule(s): none – default behavior

outputFilename

Required / Optional: Required

Type: String

Default Value: the name of the main schema, if defined – otherwise the name of the first schema that is being processed

Explanation: The name of the GeoPackage file (can be without file extension).

Applies to Rule(s): none – default behavior

srsOrganization

Alias: none

Required / Optional: optional

Type: String

Default Value: EPSG

Explanation: Name of the organization that assigned the ID of the spatial reference system to use when creating feature tables (see parameter organizationCoordSysId). Must be equal to (ignoring case) ‘NONE’, ‘EPSG’, or to the organization name of one of the SRSs defined via the advanced process configuration.

Applies to Rule(s): none – default behavior

Map Entries

<mapEntries> contain individual <MapEntry> elements, which for this target contain information for mapping specific types (classes) from the UML model to GeoPackage types.

Examples:

<mapEntries>
 <MapEntry type="CharacterString" rule="*" targetType="TEXT"/>
 <MapEntry type="Boolean" rule="*" targetType="BOOLEAN"/>
 <MapEntry type="GM_Point" rule="*" targetType="POINT"/>
</mapEntries>

A <MapEntry> element contains the attributes described in the following sections.

NOTE: The following file defines standard mappings for a number of types of the ISO Harmonized Model: StandardGeoPackageMapEntries.xml

This file can be included in ShapeChange configuration files (via XInclude – see the configuration examples). Additional XInclude files, or individual <MapEntry> elements added to the <mapEntries> section of the configuration file, may be used to customize the map entries to support additional pre-defined conceptual UML classes.

type

Required / Optional: Required

Explanation: The unqualified UML type/class name to be mapped. Should be unique within the model (if it is not unique, this can lead to unexpected results).

rule

Required / Optional: Required

Explanation: The encoding rule to which this mapping applies. May be “*” to indicate that the mapping applies to all encoding rules.

targetType

Required / Optional: Required

Explanation: Name of the type to use within the GeoPackage.

param

Required / Optional: Optional

Explanation: Defines one or more parameters for the mapping. If no parameter is provided (leaving the ‘param’ attribute empty) then the map entry contains a straightforward mapping to one of the GeoPackage types.

Thus far, no specific map entry parameters have been defined for the GeoPackage Template target.

Advanced Process Configuration

The advancedProcessConfigurations element inside of the Target configuration element is used to define additional spatial reference systems – see the configuration example. A GeoPackageSrsDefinition element must be added for each additional SRS that shall be added to the (table gpkg_spatial_ref_sys of the) GeoPackage produced by the target. This element has the following children:

• srsName (required) – Human readable name of the SRS.
• srsId (required) – Unique identifier for the SRS within the GeoPackage.
• organization (required) – Case-insensitive name of the organization defining the SRS, e.g. EPSG or epsg.
• organizationCoordSysId (required) – Numeric ID of the SRS assigned by the organization; can be equal to the value of srsId.
• definition (required) – Well-known Text representation of the Spatial Reference System following the WKT format defined by http://portal.opengeospatial.org/files/?artifact_id=999
• description (optional) – Human readable description of the SRS
• definition_12_063 (optional) – Well-known Text representation of the Spatial Reference System, following the WKT format defined by http://docs.opengeospatial.org/is/12-063r5/12-063r5.html

TIP: the command line tool projinfo can be used to retrieve Well-known Text representations in different WKT formats.

Configuration Example

<Target class="de.interactive_instruments.ShapeChange.Target.GeoPackage.GeoPackageTemplate" mode="enabled">
 <advancedProcessConfigurations>
  <GeoPackageSrsDefinitions>
   <srsDefinition>
    <GeoPackageSrsDefinition>
     <srsName>DHDN / 3-degree Gauss-Kruger zone 3</srsName>
     <srsId>31467</srsId>
     <organization>EPSG</organization>
     <organizationCoordSysId>31467</organizationCoordSysId>
     <definition>PROJCRS["DHDN / 3-degree Gauss-Kruger zone 3", BASEGEODCRS["DHDN", DATUM["Deutsches Hauptdreiecksnetz", ELLIPSOID["Bessel 1841",6377397.155,299.1528128,LENGTHUNIT["metre",1.0]]]], CONVERSION["3-degree Gauss-Kruger zone 3", METHOD["Transverse Mercator",ID["EPSG",9807]], PARAMETER["Latitude of natural origin",0,ANGLEUNIT["degree",0.01745329252]], PARAMETER["Longitude of natural origin",9,ANGLEUNIT["degree",0.01745329252]], PARAMETER["Scale factor at natural origin",1,SCALEUNIT["unity",1.0]], PARAMETER["False easting",3500000,LENGTHUNIT["metre",1.0]], PARAMETER["False northing",0,LENGTHUNIT["metre",1.0]]], CS[cartesian,2], AXIS["northing (X)",north,ORDER[1]], AXIS["easting (Y)",east,ORDER[2]], LENGTHUNIT["metre",1.0], ID["EPSG",31467]]</definition>
    </GeoPackageSrsDefinition>
   </srsDefinition>
  </GeoPackageSrsDefinitions>
 </advancedProcessConfigurations>
 <targetParameter name="outputDirectory" value="results/gpkg"/>
 <targetParameter name="sortedOutput" value="true"/>
 <targetParameter name="defaultEncodingRule" value="geopackage"/>
 <targetParameter name="organizationCoordSysId" value="31467"/>
 <xi:include href="https://shapechange.net/resources/config/StandardGeoPackageMapEntries.xml"/>
</Target>