Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update GeneralFlattening.md #104

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update GeneralFlattening.md #104

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 26 additions & 17 deletions model-transformations/GeneralFlattening.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,30 @@
## General Flattening
## Flatten Nested Structures

<table>
<tr>
<td>Category</td>
<td>General model simplification rules</td>
<td>Simplification Rule</td>
</tr>
<tr>
<td>Description</td>
<td><p>The complex structure of model elements can be reduced by applying a flattening method. The principle of the flattening is to derive a flat model structure by moving the nested child elements to its parent. The elements can be renamed to represent the former element path in the name of the resulting element and to avoid naming conflicts. The cardinality of the derived elements should be calculated from the cardinalities of the former element path. When applied recursively, this method flattens the structure of multiple levels.</p>
<p>When applied recursively, this method flattens the structure of multiple levels and will result in properties such as these:</p>
<td><p>The complex structure of model elements can be reduced by applying a flattening method. The principle of the flattening is to derive a flat model structure in the parent level by moving the first instance of nested child elements to its parent. The child elements so moved to the parent can be renamed to represent the former (child) path as aprefix in the name of the resulting element to avoid naming conflicts.</p>
<p>When applied recursively, this method flattens the structure of multiple levels into the parent level, and will result in properties such as these:</p>
<ul>
<li>inspireId_namespace</li>
<li>name_spelling_text</li>
</ul>
<p>This model transformation rule does not handle cardinalities greater than 1; it thus does not introduce any numeric elements into the new property name to account for multiple occurences. It also does not make use of the element names as they would be encoded in XML to keep the resulting proeprty names shorter. In most cases outside the use of substitution groups, this does not lead to issues. These should be resolved using any of the three Transformation Rules that can deal with that ([Primitive Array](./ExtractPrimitiveArray.md), [Associations to Soft Typed properties](./AssociatedComponentsSoftType.md), [Associations to Hard Typed properties](./AssociatedComponentsHardType.md)).</p>
<p>This model transformation rule does not handle cardinalities greater than 1, i.e., it does not introduce multiple occurrences of child elements into the parent level; it thus does not introduce any numeric elements into the new property names. It also does not make use of the element names as they would be encoded in XML to keep the resulting property names shorter. In most cases outside the use of substitution groups, this does not lead to issues in property name length. Where issues do exist, they should be resolved using any of the following Model Transformation (MT) rules:
<ul>
<li>[MT002 Extract Primitive Array](./ExtractPrimitiveArray.md)</li>
<li>[MT003 Flatten Associated Components Using TypeNames](./AssociatedComponentsHardType.md)</li>
<li>[MT004 Flatten Associated Components Using Codelist](./AssociatedComponentsSoftType.md)</li>
<li>MT00X (PROPOSED) Abbreviate Prefix of Compound Property Names</li>
</ul>
<p>This model transformation rule does not retain additional occurrences that may exist in child elements. To avoid loss of information from the source data, this rule can be combined with (proposed) MT rule “Retain Additional Nested Child Elements.”</p>
</td>
</tr>
<tr>
<td>Original instance in default encoding:</td>
<td>Original instance in default encoding</td>
<td>

```xml
Expand Down Expand Up @@ -50,7 +57,7 @@
</td>
</tr>
<tr>
<td>Transformed instance in default encoding:</td>
<td>Transformed instance in default encoding</td>
<td>

```xml
Expand All @@ -71,32 +78,34 @@
</td>
</tr>
<tr>
<td>Model transformation rule: </td>
<td>Model transformation rule</td>
<td>
<p>Parameters:</p>
<ul>
<li><code>separator</code>: The character to use to separate the original property name from the type name of the components.</li>
</ul>
<p>Recursively go down through the complex structure of the property and concatenate the local name of the property, using the <code>separator</code> character in between each local name. This rule will drop inherited properties that have the same local name as a property declared on the feature type or property type itself, e.g. <code>gml:name</code> vs. <code>gn:name</code>. Note that Geometry properties are excluded from this rule!</p>
<p>Recursively go down through the complex structure of the property and concatenate the local name of the property, using the <code>separator</code> character in between each local name.</p>
<p>This rule will drop inherited properties that have the same local name or same local name prefix as a property declared on the feature type or property type itself, e.g. <code>gml:name</code> vs. <code>gn:name</code>. Note that Geometry properties are excluded from this rule.</p>
</td>
</tr>
<tr>
<td>Instance transformation rule:</td>
<td>Instance transformation rule</td>
<td><p>Parameters: None</p>
<p>As described above, this rule does not handle property occurences greater than 1; if more than one instance of a property occur, only the first instance will be kept.</p>
<p>As described above, this rule does not handle property occurrences greater than 1 in the parent; if more than one instance of a property occur, only the first instance will be kept in the parent.</p>
</td>
</tr>
<tr>
<td>Solves usability issues:</td>
<td>This rule deals with most nested property structures and flattens them, so that the data can be used easily in analysis and visualisation.</td>
<td>Solves usability issues</td>
<td>This rule deals with most nested property structures and flattens them into the parent structure, so that the data can be used easily in analysis and visualisation.</td>
</tr>
<tr>
<td>Known usability issues:</td>
<td>This rule has no fixed limit in the character length of the resulting property names. Some of these names can get very long. The rule should thus be combined with others that reduce the likelyhood of that happening, such as [SimpleGeographicName](./SimpleGeographicName.html).</td>
<td>Known usability issues</td>
<td><p>This rule may result in information loss where there are multiple occurrences in the child structure. The rule may be combined with others that reduce the likelihood of information loss, such as [(proposed) “Retain Nested Child Elements”](https://github.com/INSPIRE-MIF/2017.2/issues/100) or [Extract Primitive Array](./ExtractPrimitiveArray.md).</p>
<p>This rule has no fixed limit in the character length of the resulting property names. Some of these compound property names can get very long. The rule should thus be combined with others that reduce the likelihood of that happening, such as [SimpleGeographicName](./SimpleGeographicName.html) and [(proposed) “Abbreviate Prefix of Compound Property Names.”](https://github.com/INSPIRE-MIF/2017.2/issues/103).</p></td>
</tr>
<tr>
<td>INSPIRE Compliance:</td>
<td>Data transformed using this rule is INSPIRE compliant as long as the cardinality of the source data was 0..1 for all affected properties.</td>
<td>INSPIRE Compliance</td>
<td>Data transformed using this rule is INSPIRE compliant as long as there is no information loss from the source data. This can be achieved when either the cardinality of the source data is 0..1 for all affected properties or when additional rules are applied to retain additional child elements.</td>
</tr>
</table>

Expand Down