1. Overview

The GML Codelist Dictionary target is a tool for encoding GML dictionaries for the code lists and – if so configured – the enumerations of an application schema.

ISO 19103 defines a code list as an "open enumeration", one which is extensible under certain circumstances.  It is therefore convenient to be able to produce listings of the allowable values for these enumerations.

ISO 19136:2007 (the GML 3.2.1 specification), clause 15, provides a GML Dictionary schema for capturing and disseminating definitions in an easily-accessible and nestable format.

The following rules apply:

  • A code list will be processed except if its "asDictionary" tagged value is set to false.

  • An enumeration will be processed if parameter enumerations is set to true.

  • Each code list / enumeration will be output as its own XML file with a top-level <gml:Dictionary> element.

  • The filename will be the name of the UML class with an ".xml" extension.

  • For each <gml:Dictionary>:

    • The gml:id attribute of the dictionary will be the name of the code list / enumeration.

    • The value of the <gml:description> element of the dictionary is derived via the parameters documentationTemplate and documentationNoValue, using the descriptors of the code list / enumeration. If the value is empty, no <gml:description> is created.

    • The value of the <gml:identifier> element of the dictionary will be the first non-empty value retrieved via one of the sources specified by parameter identifier. The @codeSpace of that element will be the target namespace of the schema to which the code list / enumeration belongs.

    • A <gml:name> element will be added to the dictionary for each non-empty source specified by parameter names.

    • A <gml:Definition> will be added to the dictionary for each of the codes/enumerants defined for the code list / enumeration - as well as its direct and indirect supertypes.

  • For each <gml:Definition>:

    • The gml:id attribute of the definition will have the value retrieved from the source specified by parameter gmlid (prepending an underscore if the value does not start with a letter or an underscore). If no value was found, then the value of gml:id will be an underscore followed by the model id of the code / enumerant.

    • The value of the <gml:description> element of the definition is derived via the parameters documentationTemplate and documentationNoValue, using the descriptors of the code / enumerant. If the value is empty, no <gml:description> is created.

    • The value of the <gml:identifier> element of the definition will be the first non-empty value retrieved via one of the sources specified by parameter identifier. The @codeSpace of that element will be looked up in the following order:

      • tagged value codeList

      • tagged value infoURL

      • the target namespace of the schema to which the code list / enumeration belongs, followed by "/" and the name of the code list / enumeration

    • A <gml:name> element will be added to the definition for each non-empty source specified by parameter names.

 

2. Configuration

The <Target> element definition for the GML Codelist Dictionary target is a standard ShapeChange target.  An example is given below:


  
1
2
3
4
5


  
<Target
class="de.interactive_instruments.ShapeChange.Target.Codelists.CodelistDictionaries"
mode="enabled">
<targetParameter name="outputDirectory" value="results/dictionaries" />
</Target>

2.1. Class

The class for the Target implementation is de.interactive_instruments.ShapeChange.Target.Codelists.CodelistDictionaries.

2.2. Target Parameters

2.2.1. 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 (see the according parameter), but has no value, this parameter will be used. See here for more information about descriptors.

Applies to Rule(s): none – default behavior

2.2.2. documentationTemplate

Alias: none

Required / Optional: optional

Type: String

Default Value: [[definition]]

Explanation:

The template for the documentation that is generated for <gml:description> 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

2.2.3. enumerations

Alias: none

Required / Optional: optional

Type: Boolean

Default Value: false

Explanation: If set to true, enumerations are also encoded as dictionaries.

Applies to Rule(s): none – default behavior

2.2.4. gmlid

Alias: none

Required / Optional: optional

Type: String

Default Value: id

Explanation: Specify the source for the value of the gml:id attribute of a <gml:Definition> element, which corresponds to a code / enumerant. Valid sources are:

  • "id" – corresponding to the id of the code / enumerant

  • "name" – corresponding to the name of the code / enumerant

  • "alias" – corresponding to the alias name of the code / enumerant

  • "initialValue" – corresponding to the initial value that may be defined for the code / enumerant

  • A tagged value of the code / enumerant, identified via "@" + \{tagged value name}

Applies to Rule(s): none – default behavior

2.2.5. identifier

Alias: none

Required / Optional: optional

Type: List of Strings (comma-separated)

Default Value: name

Explanation: Specify the sources for the value of the <gml:identifier> element that is created for <gml:Dictionary> and <gml:Definition> elements. The elements correspond to a code list / enumeration and its codes / enumerants. The first non-empty value retrieved from the sources will be chosen. Valid sources are:

  • "id" – corresponding to the id of the model element

  • "name" – corresponding to the name of the model element

  • "alias" – corresponding to the alias name of the model element

  • "initialValue" – corresponding to the initial value that may be defined for a code / enumerant

  • A tagged value of the model element, identified via "@" + \{tagged value name}

Applies to Rule(s): none – default behavior

2.2.6. names

Alias: none

Required / Optional: optional

Type: List of Strings (comma-separated)

Default Value: alias, initialValue

Explanation: Specify the sources for the values of the <gml:name> elements that are created for <gml:Dictionary> and <gml:Definition> elements (which correspond to a code list / enumeration and its codes / enumerants). For each non-empty value, a <gml:name> element will be created. Valid sources are:

  • "id" – corresponding to the id of the model element

  • "name" – corresponding to the name of the model element

  • "alias" – corresponding to the alias name of the model element

  • "initialValue" – corresponding to the initial value that may be defined for a code / enumerant

  • A tagged value of the model element, identified via "@" + \{tagged value name}

Applies to Rule(s): none – default behavior

2.2.7. outputDirectory

Type: String

Default Value: <the current run directory>

Explanation: The path to which the XML files representing the dictionaries will be written. Because there may be a large number of such files, it is suggested that a unique directory be designated for this purpose.

Applies to Rule(s): none – general behaviour

3. Sample Configuration


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


  
<TargetXmlSchema
 class="de.interactive_instruments.ShapeChange.Target.Codelists.CodelistDictionaries" mode="enabled"
 inputs="TRF">
 <targetParameter name="outputDirectory"
  value="results/codeLists/CodeListDictionaries_GML"/>
 <targetParameter name="sortedOutput" value="true"/>
 <targetParameter name="documentationTemplate" value="[[documentation]]"/>
 <targetParameter name="enumerations" value="true"/>
 <targetParameter name="gmlid" value="name"/>
 <targetParameter name="names" value="alias, initialValue, @name"/>
 <targetParameter name="identifier" value="name"/>
 <xi:include href="https://shapechange.net/resources/config/StandardNamespaces.xml"/>
</TargetXmlSchema>