Output Targets

General Information

The primary target of ShapeChange are GML application schemas, represented as a set of XML Schema documents.  However, there are other targets that ShapeChange may be configured to produce.  The targets are described here, both conceptually (the specifications underlying each target) and practically (how ShapeChange may be configured to produce each form of output).

Encoding Rules

An encoding rule, as defined in ISO 19118:2005, is an “identifiable collection of conversion rules” that “is applied to application schema specific data structures to produce system-independent data structures suitable for transport or storage” (ISO 19118:2005, section 6.4.1).  Both input and output data structures are specified in a schema language, such as UML or XML Schema; accordingly, an encoding rule includes a schema conversion rule.

The encoding rule concept drives ShapeChange: the conversion from an application schema in UML to another data structure is (broadly) driven by a set of rules, encapsulated by the internal code of the classes in the Target packages.

The ShapeChange configuration framework contains provisions for specifying which of a set of possible encoding rules applies to a particular transformation, with the ability for an application schema in UML to support multiple encoding rules for different “platforms” or targets.  For example, the XML Schema target allows for detailled customization of the encoding rule.

Java Implementation Details

Within the ShapeChange Java framework, each target/output format definition is implemented as a Java class.  In keeping with the modularity of ShapeChange, each such target implements the de.interactive-instruments.ShapeChange.Target.Target interface, which contains method “hooks” for the various steps in the output process— initializing the target, processing each class in the application schema appropriately for the target type, and finally writing the output to one or more files (XSD, HTML or other file).  The fully-qualified name of this class must be provided in the configuration file.

Configuration

Each individual target for a run of ShapeChange is defined in the configuration file as its own <Target> element.  All <Target> definitions are nested under the <targets> element.

All <Target> definitions, no matter the actual target type, are configured via XML attributes and parameters.  <MapEntry> definitions may also be used to customize mappings.

Target Attributes

Each <Target> element has three attributes, one required and two optional.  These attributes are as follows:

Attribute Name Required / Optional Default Value Explanation
class Required

A string representing a fully-qualified target “handler” class (an implementation of the Target interface).

mode Optional enabled Whether or not this particular target is “turned on”.  This allows for multiple targets to be specified in a configuration file, and turned on/off at will.  The possible values are:

  • enabled: The target is processed.
  • disabled: The target is ignored.
  • diagnostics-only: The target is processed, but no output is created. However, not all targets support this mode yet and some will treat this mode identical to “enabled”.
inputs Optional defaults to the input model A (space-separated list of) identifiers, referencing the id of transformers and/or the input model. If multiple identifiers are provided, the target is executed for the output model of each referenced transformer and/or the input model. If the attribute is omitted then the target is applied on the input model.

Target Parameters

In addition to the required attributes, each <Target> may have additional parameters defined via <targetParameter> elements.

Each target type may define its own expected or required parameters; the target-specific subheadings of the subpages will describe these for each target type.

ShapeChange also supports a set of common tasks to process output files that were generated by a target. Further details, including the parameters to control the output processing, are described in the section Common Output Processing.

Map Entries

The <mapEntries> section of the <Target> element may contain a series of <MapEntry> definitions.

Map entries allow for customized mapping from UML classes to target elements, by enabling the specification of generic “rules”.

The attributes of a <MapEntry> are as follows:

Attribute Name Explanation
type (Required) The UML type/class name to be mapped..
rule

(Required) The “rule” for the mapping.  This is a freeform String field; the interpretation of its value is left to the code implementing the target.

targetType

The type to which the type will be mapped. The interpretation of its value is left to the code implementing the target.

param

An optional parameter for the mapping. The interpretation of its value is left to the code implementing the target.

A sample <mapEntries> element is given below (for a FME target that is part of an extension to ShapeChange):

<mapEntries>
  <!-- 19107 to FME geometry types -->
  <MapEntry rule="FME" targetType="*" type="GM_Primitive"/>
  <MapEntry param="fme_point" rule="FME" targetType="fme_point" type="GM_Point"/>
  <MapEntry param="fme_line,fme_aggregate" rule="FME" targetType="fme_line" type="GM_Curve"/>
  <MapEntry param="fme_polygon,fme_donut,fme_aggregate" rule="FME" targetType="fme_area"
    type="GM_Surface"/>
</mapEntries>

Common Output Processing

The following list of common processing tasks can be applied to output files created by a target:

  1. modifying the file name
  2. adding a generation comment to the content of the file
  3. applying an XSL transformation to the file

NOTE: The tasks are performed by ShapeChange in the given order.

The target parameters to control the output processing are documented in detail in the following sections.

Modify File Name

Add a prefix to the name of an output file.

Parameter(s):

Add Comment

Add a comment to the content of an output file.

Parameter(s):

Apply XSL Transformation

Apply an XSL transformation to output files.

Parameter(s):

Parameters

mainAppSchema

(available since v2.4.0)

Type: String

Default Value: none

Explanation: During a single execution of ShapeChange, a single or multiple application schemas can be processed. The relevant input parameters for controlling which schemas are selected for processing by ShapeChange are: appSchemaName, appSchemaNameRegex, and appSchemaNamespaceRegex.

Some ShapeChange targets process one schema at a time, and generate a result for each schema. However, ShapeChange also has targets, so called SingleTargets, which gather information from all schemas selected for processing, and generate a combined result for all these schemas. Examples of SingleTargets are: the SQL DDL target and the ArcGIS Workspace target.

If multiple schemas have been selected for processing, ShapeChange may need to get information from a specific schema, like target namespace, XML namespace abbreviation, and version. For output processing, version information can be important. By adding the mainAppSchema parameter to the target configuration, with the name of one of the application schemas that were selected for processing as value, ShapeChange will get this information from that schema.

Applies to:

processOutput_addComment

(available since v2.4.0)

Type: Boolean

Default Value: false

Explanation: If set to “true”, a comment will be added to output files (with one of the following file extensions: xml, xsd, rdf, owl, sch, trix, sql, ddl, ttl, nt, trig, nq). The comment is given via parameter processOutput_comment.

Applies to:

processOutput_applyXslt

(available since v2.4.0)

Type: Boolean

Default Value: false

Explanation: If set to “true”, an XSL transformation will be applied to output files created by the target, with one of the following file extensions: xml, xsd, rdf, owl, sch, trix, html, sql, ddl, ttl, nt, trig, nq. Default is “false”.

Applies to:

processOutput_comment

(available since v2.4.0)

Type: String

Default Value: Last modified date of the output file, formatted according to yyyyMMdd, followed by the schema version if appropriate (target is a) either not a SingleTarget, or a SingleTarget and a main schema has been defined – see mainAppSchema parameter – or only a single schema is processed by ShapeChange, and b) the target is not a DeferrableOutputWriter (like the FeatureCatalogue target), and a link to shapechange.net. Example: Created by ShapeChange on 20170818 from application schema version 1.1 – http://shapechange.net/.

Explanation: Comment to add to the content of output files (see parameter processOutput_addComment). If no value is provided for this parameter, the default value applies (i.e., the comment will be auto-generated).

Applies to:

processOutput_fileNamePrefix

(available since v2.4.0)

Type: String

Default Value: Last modified date of the output file, formatted according to yyyyMMdd, followed by the schema version if appropriate (target is a) either not a SingleTarget, or a SingleTarget and a main schema has been defined – see mainAppSchema parameter – or only a single schema is processed by ShapeChange, and b) the target is not a DeferrableOutputWriter (like the FeatureCatalogue target), and a link to shapechange.net. Example: 20170818.v1.1.s1.xsd

Explanation: Prefix to add to the name of output files (see parameter processOutput_modifyFileName). If no value is provided for this parameter, the default value applies (i.e., the prefix will be auto-generated).

Applies to:

processOutput_modifyFileName

(available since v2.4.0)

Type: Boolean

Default Value: false

Explanation: If set to “true”, the name of output files will be augmented with a prefix. The prefix is given via parameter processOutput_fileNamePrefix.

Applies to:

processOutput_xslt_outputSuffix

(available since v2.4.0)

Type: String

Default Value: “_transformed.xml”

Explanation: Define the suffix to append to base names of files (i.e. the file name without file extension) created by applying an XSL transformation to output files. The suffix is required to identify the intended type of output files. For example, if an XML Schema file is transformed, the result could be an XML Schema but also an XML file. If the suffix is set to the same file extension as the input file of the transformation (e.g. “.xsd” when processing an XML Schema file), the input file will be overwritten.

Applies to:

processOutput_xslt_deleteInputFilesAfterTransformation

(available since v2.4.0)

Type: Boolean

Default Value: false

Explanation: If set to “true”, the input file of an XSL transformation (that is applied to output files created by a target) will be deleted – unless the result file of the transformation has overwritten the input file.

Applies to:

processOutput_pathToXsltDirectory

(available since v2.4.0)

Type: String

Default Value: “.” (i.e. the current run directory)

Explanation: Path to the directory that contains the XSL transformation file(s). Can be an HTTP URL.

Applies to:

processOutput_xsltFileName

(available since v2.4.0)

Type: String

Default Value: none

Explanation: Name of the XSL transformation file to apply. The file must be contained in the directory identified by parameter processOutput_pathToXsltDirectory.

Applies to:

xslTransformerFactory

(available since v2.4.0)

Type: String

Default Value: none

Explanation: Identifies the XSLT processor implementation, to be used for processing output files (see parameter processOutput_applyXslt). In order to process XSLT transformations with version 2.0 or higher, this parameter should point to the implementation of an XSLT processor that is capable of processing such XSLTs, for example Saxon-HE (home edition; open source):

  • sf.saxon.TransformerFactoryImpl (download the Saxon-HE jar and copy it to the lib folder of your ShapeChange distribution; note: name the file ‘Saxon-HE-9.5.1-1.jar’ – or explicitly include the jar in your classpath, using the ‘-cp’ command when invoking java to execute ShapeChange)

Applies to:

Configuration Example

<TargetXmlSchema class="de.interactive_instruments.ShapeChange.Target.XmlSchema.XmlSchema"
  inputs="trf" mode="enabled">
  <targetParameter name="processOutput_modifyFileName" value="true"/>
  <targetParameter name="processOutput_addGenerationComment" value="true"/>
  <targetParameter name="processOutput_applyXslt" value="true"/>
  <targetParameter name="processOutput_xslt_outputSuffix" value="_transformed.xsd"/>
  <targetParameter name="processOutput_pathToXsltDirectory"
   value="src/test/resources/outputProcessing/xslt"/>
  <targetParameter name="processOutput_xsltFileName" value="onlyRoot_transformation.xsl"/>
  <targetParameter name="processOutput_xslt_deleteInputFilesAfterTransformation" value="false"/>
  <targetParameter name="xslTransformerFactory" value="net.sf.saxon.TransformerFactoryImpl"/>
  <!-- ... other target parameters (like outputDirectory and defaultEncodingRule), rules, map entries etc. ... -->
 </TargetXmlSchema>

Supported Target Types

XML Schema

The original and still the most commonly used functionality of ShapeChange is to generate XML Schema representations of application schemas, encoded as a set of XML Schema documents (XSDs). ShapeChange supports the standard encoding rules from

  • GML 3.2 (ISO 19136)
  • GML 3.3
  • ISO/TS 19139
  • SWE Common 2.0

An extension supports the generation of a Schematron schema from the OCL constraints in an application schema.

In addition, a number of community-specific encoding rule extensions for

  • GSIP
  • INSPIRE
  • CityGML ADEs
  • ISO 19115 metadata profiles
  • OKSTRA

are supported.

More information…

Feature Catalogues

ISO 19110 specifies a methodology for classifying and organizing feature types into a feature catalogue.  ShapeChange contains a target for generating a feature catalogue from an application schema in UML (or one of its contained packages).

The Feature Catalogue target can produce a feature catalogue in the following formats:

  • HTML
  • DOCX

More information…

RDF/OWL

The target creates a RDF/OWL ontology representation of an application schema.

More information…

ArcGIS Workspace

An ISO 19109 application schema can be converted to an ArcGIS workspace document. That document can be imported as a schema to the various Esri Geodatabases using ArcGIS. This enables the use of ArcGIS in conjunction with ISO 19109 based application schema.

More information…

JSON Schema

More information…

SQL DDL and Replication Schema

More information…

Model Export

More information…

UML Model

More information…

First Order Logic to Schematron

More information…

Profile Transfer to EA Repository

More information…

Application Schema Metadata

More information…