From 62f5700e8f3a3a4213f01c038c63b36c0b4c0cb8 Mon Sep 17 00:00:00 2001 From: Heidi Vanparys Date: Sun, 22 Jan 2023 13:16:21 +0100 Subject: [PATCH] Update the overview of rules, make rule descriptions consistent Changes for consistency: - add identifier to every rule description - make the titles in the description of the rules consistent with the overview that describes all properties of the rules - use "simplification rule" and "substition rule" as categories - editorial changes Some of these changes were suggested in https://github.com/INSPIRE-MIF/2017.2/pull/99 --- rules/AssociatedComponentsHardType.md | 12 +++-- rules/AssociatedComponentsSoftType.md | 12 +++-- rules/EuropeanLegislationIdentifier.md | 14 +++--- rules/ExtractPrimitiveArray.md | 17 +++---- rules/GeneralFlattening.md | 8 ++-- rules/PropertyByReferenceOnly.md | 11 +++-- rules/README.md | 65 +++++++++++++++++++++++--- rules/SimplifiedCitation.md | 12 +++-- rules/SimplifiedCodelistReference.md | 12 +++-- rules/SimplifiedGeographicName.md | 8 ++-- rules/SimplifiedPeriod.md | 12 +++-- rules/_template.md | 4 +- 12 files changed, 132 insertions(+), 55 deletions(-) diff --git a/rules/AssociatedComponentsHardType.md b/rules/AssociatedComponentsHardType.md index 77e9490..844fa5f 100644 --- a/rules/AssociatedComponentsHardType.md +++ b/rules/AssociatedComponentsHardType.md @@ -1,8 +1,8 @@ -# Inline associated or aggregated components using type names +# Flatten Associated Components using Typenames (MT003) ## Category -General model simplification rules +simplification rule ## Description @@ -176,7 +176,7 @@ None. For each potential type of a value, a property is created, so instance values can be copied. Properties that are left empty after copying the source values can be removed (see example above). -## Solves usability issues +## Solved usability issues Data where key properties are in associated objects is hard to style and to filter for in most desktop GIS and web GIS software. The inlined data can be processed much easier by many tools, e.g. it can be converted to Excel easily. @@ -184,6 +184,10 @@ Data where key properties are in associated objects is hard to style and to filt Since this rule denormalizes components, it can increase total data volume. -## INSPIRE Compliance +## INSPIRE compliance conditions and reversibility This rule can only be applied if there is at maximum one occurrence of each type in a set of properties, i.e. where the components are a key-value map with the keys being defined by the type names. + +## Notes + +N/A \ No newline at end of file diff --git a/rules/AssociatedComponentsSoftType.md b/rules/AssociatedComponentsSoftType.md index a7f159f..879284d 100644 --- a/rules/AssociatedComponentsSoftType.md +++ b/rules/AssociatedComponentsSoftType.md @@ -1,8 +1,8 @@ -# Flatten aggregated or associated components using codelist values +# Flatten Associated Components using Codelist Values (MT004) ## Category -General model simplification rules +simplification rule ## Description @@ -126,7 +126,7 @@ Copy the value of the `valueProperty` to the newly created property. If the `valueProperty` is still a complex property, it might have to be transformed using a different rule in addition. -## Solves usability issues +## Solved usability issues The flattened data can be filtered and symbolized easily in desktop GIS and web GIS software. The flattened data can be processed much easier by many tools, e.g. it can be converted to excel easily. @@ -134,6 +134,10 @@ The flattened data can be filtered and symbolized easily in desktop GIS and web Flattening of large arrays will lead to a very large number of properties on the first level. Some software and formats can only work with a limited number of properties on a layer (ArcMap has 65.534, Shapefile is limited to 250), so this can limit usability in extreme cases. Some software also has limits on the length of property names (File Geodatabase = 64 characters, Shapefile = 10 characters). -## INSPIRE Compliance +## INSPIRE compliance conditions and reversibility This rule can only be applied if there is at maximum one occurrence of each codelist value for the type property in a set of properties. + +## Notes + +N/A \ No newline at end of file diff --git a/rules/EuropeanLegislationIdentifier.md b/rules/EuropeanLegislationIdentifier.md index 6b34c7e..54fdfe9 100644 --- a/rules/EuropeanLegislationIdentifier.md +++ b/rules/EuropeanLegislationIdentifier.md @@ -1,10 +1,8 @@ -# Name - -European Legislation Identifier +# European Legislation Identifier (MT010) ## Category -Alternative structures for specific types or type hierarchies +substitution rule ## Description @@ -101,7 +99,7 @@ N/A Give the property that has `LegalResource` as type the ELI of the legal resource as value. -## Solves usability issues +## Solved usability issues Reduces implementation effort of and duplication of data by data providers, as legal resources usually are managed by another data @@ -113,7 +111,11 @@ Display of `@xlink:href` may not be supported in all clients. However, this is the same problem as for code lists, which are widely used in INSPIRE. -## INSPIRE Compliance +## INSPIRE compliance conditions and reversibility Fully compliant if the referenced resource is stored in an external register or non-INSPIRE online application. + +## Notes + +N/A \ No newline at end of file diff --git a/rules/ExtractPrimitiveArray.md b/rules/ExtractPrimitiveArray.md index e3cc0f6..b676c1b 100644 --- a/rules/ExtractPrimitiveArray.md +++ b/rules/ExtractPrimitiveArray.md @@ -1,10 +1,8 @@ -# Name - -Extract Primitive Array +# Extract Primitive Array (MT002) ## Category -... +simplification rule ## Description @@ -16,8 +14,7 @@ complex property and then create an array of those simple values. An example where this can be applied is to store relationships between objects: -- lowerLevelUnits: LinktoToUnit_01, LinktoToUnit_02, LinktoToUnit_03, - ... +- lowerLevelUnits: LinktoToUnit_01, LinktoToUnit_02, LinktoToUnit_03, … ## Original model @@ -95,7 +92,7 @@ For each instance of the `valueProperty`, push its value to the array in the target property. The order of values that are copied from the source properties should be kept. -## Solves usability issues +## Solved usability issues This rule reduces overhead and makes it possible to have workable transformed data structures that are not polluted by hundreds or even @@ -106,7 +103,11 @@ simplification in case the target environment does not support arrays. Some software cannot process arrays. -## INSPIRE Compliance +## INSPIRE compliance conditions and reversibility The transformed model is fully compliant to INSPIRE as long as no mandatory properties other than the valueProperty have been left out. + +## Notes + +N/A \ No newline at end of file diff --git a/rules/GeneralFlattening.md b/rules/GeneralFlattening.md index 6a6ae63..dc1dce9 100644 --- a/rules/GeneralFlattening.md +++ b/rules/GeneralFlattening.md @@ -1,8 +1,8 @@ -# General Flattening +# Flattening of Nested Structures (MT001) ## Category -General model simplification rules +simplification rule ## Description @@ -126,7 +126,7 @@ None. As described above, this rule does not handle property cardinalities greater than 1; if more than one instance of a property occurs, only the first instance will be kept. -## Solves usability issues +## Solved usability issues This rule deals with most nested property structures and flattens them, so that the data can be used easily in analysis and visualisation. @@ -134,7 +134,7 @@ This rule deals with most nested property structures and flattens them, so that 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). -## INSPIRE Compliance +## INSPIRE compliance conditions and reversibility Data transformed using this rule is INSPIRE compliant as long as the cardinality of the affected properties in the source data was 0 or 1. diff --git a/rules/PropertyByReferenceOnly.md b/rules/PropertyByReferenceOnly.md index d371ac1..c6282a9 100644 --- a/rules/PropertyByReferenceOnly.md +++ b/rules/PropertyByReferenceOnly.md @@ -1,8 +1,8 @@ -# Restriction of property encoding options to only by-reference +# Refer to Property Values by Reference (MT006) ## Category -General model simplification rules +simplification rule ## Description @@ -167,7 +167,7 @@ full-blown bibliographic reference in the case of objects that are information resources (e.g. "Bekendtgørelse af lov om skove. 28 marts 2019. LBK nr 315."), if present, may be inserted in `@xlink:title`. -## Solves usability issues +## Solved usability issues This rule reduces nested structures (inline referencing causes nested structures with many levels). It also reduces implementation effort of and duplication of data by data providers, if the value of the property is a resource managed by another data provider. @@ -177,7 +177,10 @@ Display of `@xlink:href` and `@xlink:title` may not be supported in all clients. However, this is the same problem as for code lists, which are widely used in INSPIRE. -## INSPIRE Compliance +## INSPIRE compliance conditions and reversibility Fully compliant if the referenced resource is stored in an external register or non-INSPIRE online application. +## Notes + +N/A \ No newline at end of file diff --git a/rules/README.md b/rules/README.md index d1d276b..bb411c8 100644 --- a/rules/README.md +++ b/rules/README.md @@ -1,9 +1,60 @@ -# Overview of model transformation rules +# Model transformation rules -| Name | Category | -|---|---| -| [TODO](#) | TODO | +## Introduction + +The intent of this document is to describe multiple model +transformation rules. These model transformation rules reduce +complexity in encoded INSPIRE data, e.g. by reducing levels of +aggregation, indirect referencing, using simple geometries and +flattening structures such as arrays. As with alternative encodings, +they have different objectives and scopes. A rule may be used with any +number of encodings, including the default encoding, if applicable. + +An alternative encoding may refer to any number of such model +transformation rules in its requirements classes. For this purpose, each + model transformation rule receives a unique identifier. For an +alternative encoding to be the sole encoding, there may not be any +information loss for the particular data set in question. Where there is + information loss, such encoding may only be used as an additional +encoding. + +## Description of model transformation rules + +Each model transformation rule is described by these properties: + +- Name +- Unique identifier +- Category +- Description +- Original model +- Transformed model +- Original instance in default encoding +- Transformed instance in default encoding +- Model transformation rule +- Instance transformation rule +- Solved usability issues +- Known usability issues +- INSPIRE compliance conditions and reversibility +- Notes + +## Catalogue of model transformations rules + +This catalogue contains general model simplification rules identified so + far. + +The catalogue also contains several substitution rules, where existing +types are replaced with less complex types. + +| Identifier | Name | Category | +|---|---|---| +| MT001 | [Flattening of Nested Structures](./GeneralFlattening.md) |simplification rule | +| MT002 | [Extract Primitive Arrays](./ExtractPrimitiveArray.md) |simplification rule | +| MT003 | [Flatten Associated Components using Typenames](./AssociatedComponentsHardType.md) |simplification rule | +| MT004 | [Flatten Associated Components using Codelist Values](./AssociatedComponentsSoftType.md) |simplification rule | +| MT005 | [Simple Geographic Name](./SimplifiedGeographicName.md) | substitution rule | +| MT006 | [Refer to Property Values by Reference](./PropertyByReferenceOnly.md) |simplification rule | +| MT007 | [Simple Citation](./SimplifiedCitation.md) | substitution rule | +| MT008 | [Simple Codelist Reference](./SimplifiedCodelistReference.md) | substitution rule | +| MT009 | [Simple Period](./SimplifiedPeriod.md) | substitution rule | +| MT010 | [European Legislation Identifier](./EuropeanLegislationIdentifier.md) | substitution rule | -(status: the model transformation rules currently described at -https://github.com/INSPIRE-MIF/2017.2/blob/master/model-transformations/TransformationRules.md -will be copied here) \ No newline at end of file diff --git a/rules/SimplifiedCitation.md b/rules/SimplifiedCitation.md index b83c513..7d69540 100644 --- a/rules/SimplifiedCitation.md +++ b/rules/SimplifiedCitation.md @@ -1,8 +1,8 @@ -# Simplified Citation +# Simplified Citation (MT007) ## Category -Alternate structures for specific types or type hierarchies +substitution rule ## Description @@ -162,7 +162,7 @@ N/A Note that only one link may be present in the data. - Copy the value of `base2:level` to the property `simple:level`. -## Solves usability issues +## Solved usability issues The transformed data structure can easily be edited, filtered and symbolized in desktop GIS and web GIS software. This transformation also @@ -172,9 +172,13 @@ symbolized in desktop GIS and web GIS software. This transformation also None. -## INSPIRE Compliance +## INSPIRE compliance conditions and reversibility This rule works only with one external link, and it removes finer grained information about dates. It can be combined with the [Restriction of property encoding options to only by-reference](./PropertyByReferenceOnly.md) rule to add more information from an external register. + +## Notes + +N/A \ No newline at end of file diff --git a/rules/SimplifiedCodelistReference.md b/rules/SimplifiedCodelistReference.md index b78c6e8..a7a491f 100644 --- a/rules/SimplifiedCodelistReference.md +++ b/rules/SimplifiedCodelistReference.md @@ -1,8 +1,8 @@ -# Simplified Codelist Reference +# Simplified Codelist Reference (MT008) ## Category -Alternate Structures for specific types or type hierarchies +substitution rule ## Description @@ -114,7 +114,7 @@ register to the property whose name is `property`; - Copy the value of the `vocabulary` tagged value to the property whose name is `property` + `.href`. -## Solves usability issues +## Solved usability issues The transformed data structure can easily be edited, filtered and symbolized in desktop GIS and web GIS software. @@ -122,6 +122,10 @@ The transformed data structure can easily be edited, filtered and symbolized in None. -## INSPIRE Compliance +## INSPIRE compliance conditions and reversibility Fully compliant. + +## Notes + +N/A \ No newline at end of file diff --git a/rules/SimplifiedGeographicName.md b/rules/SimplifiedGeographicName.md index 0e11d31..daa2f5f 100644 --- a/rules/SimplifiedGeographicName.md +++ b/rules/SimplifiedGeographicName.md @@ -1,8 +1,8 @@ -# Simplified Geographic Name +# Simplified Geographic Name (MT005) ## Category -Alternate Structures for specific types or type hierarchies +substitution rule ## Description @@ -165,7 +165,7 @@ N/A Copy the value of the `spelling.text` property to the new property. -## Solves usability issues +## Solved usability issues The transformed data structure can easily be edited, filtered and symbolized in desktop GIS and web GIS software. This transformation also reduces data volume significantly in datasets that use in-place encoding of `GeographicalName`. @@ -173,7 +173,7 @@ The transformed data structure can easily be edited, filtered and symbolized in None. -## INSPIRE Compliance +## INSPIRE compliance conditions and reversibility This rule discards individual metadata about geographical names, such as the name status and its nativeness. If this information is homogeneous, it should be documented in the dataset metadata. If it is heterogeneous, this transformation will result in a loss of information. diff --git a/rules/SimplifiedPeriod.md b/rules/SimplifiedPeriod.md index 964f58c..7fcbe9b 100644 --- a/rules/SimplifiedPeriod.md +++ b/rules/SimplifiedPeriod.md @@ -1,8 +1,8 @@ -# Simplified Period +# Simplified Period (MT009) ## Category -Alternate Structures for specific types or type hierarchies +substitution rule ## Description @@ -116,7 +116,7 @@ N/A - Copy the value of the nested `endPosition` property to property `endPosition`. -## Solves usability issues +## Solved usability issues The transformed data structure can easily be edited, filtered and symbolized in desktop GIS and web GIS software. This transformation also reduces data volume in datasets. @@ -124,6 +124,10 @@ The transformed data structure can easily be edited, filtered and symbolized in None. -## INSPIRE Compliance +## INSPIRE compliance conditions and reversibility This rule works only with one external link, and it removed finer grained information about dates. It can be combined with the [Property Composition to Association](./PropertyByReferenceOnly.md) rule to add more information from an external register. + +## Notes + +N/A \ No newline at end of file diff --git a/rules/_template.md b/rules/_template.md index 67391d0..cc538af 100644 --- a/rules/_template.md +++ b/rules/_template.md @@ -42,14 +42,14 @@ -## Solves usability issues +## Solved usability issues ## Known usability issues -## INSPIRE Compliance +## INSPIRE compliance conditions and reversibility ## Notes