Skip to content

Commit

Permalink
WIP transformation rules for ems, editorial updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@thorsten-reitz
thorsten-reitz committed Mar 11, 2019
1 parent 052ce61 commit 2f53ceb
Show file tree
Hide file tree
Showing 11 changed files with 357 additions and 72 deletions.
42 changes: 31 additions & 11 deletions GeoJSON/specification.md
View file
Expand Up @@ -110,10 +110,28 @@ This section describes how the the logical model for the encoding is derived fro

### Mapping from Conceptual Model to GeoJSON Logical Model

* DECIDE: Should namespace prefixes be retained?
* DECIDE: Should namespace prefixes be retained for the JSON property names?

All model transformation rules are applied in such a way that the resulting proeprty names for valid XML element and type names, and are useable as property names in JSON.

All property types are transformed to the simple types that JSON knows about: Number, String, Boolean and Object. The exact mapping is outlined in the following table:

| XML Schema datatype | JSON datatype | Conversion Notes |
| ------ | ----- | ----- |
| string | string | |
| boolean | boolean | |
| decimal | integer | |
| float | number | |
| double | number | |
| duration | string | |
| dateTime | string | |
| time | string | |
| date | string | |
| hexBinary | string | |
| base64Binary | string | |
| anyURI | string | |
| QName | string | |

### Common Rules

* `GEOJSON-REQ-01`: The character encoding of all data encoding in GeoJSON shall be UTF-8.
Expand Down Expand Up @@ -266,11 +284,12 @@ An additional objective is to provide an efficient structure for the measurement
This section describes which rules with which parameters are applied to the Environmental Monitoring Facilities conceptual model before applying the general rules of this encoding:

1. Substitute all occurences of `LegalCitation` with the Simple Citation through Rule `MT007()`.
2. Substitute all attributes that have a property type with a Codelist Sterotype through a inline codelist reference using `MT008()`.
3. Substitute `OperationalActivityPeriod` with the Simple Period using `MT009()`.
4. Substitute all `OM` and `OMSO` model elements through the respective `OMSF` model elements
5. Apply the `OMSF GeoJSON` model mapping to the `OMSO` model elements
6. Apply the General Flattening rule to simplify the remaining properties: `MT001(separator: '.')`
2. Apply `MT006()` to add optional external information about citations.
3. Substitute all attributes that have a property type with a Codelist Sterotype through a simple codelist reference using `MT008()`.
4. Substitute `OperationalActivityPeriod` with the Simple Period using `MT009()`.
5. Substitute all `OM` and `OMSO` model elements through the respective `OMSF` model elements.
6. Apply the `OMSF GeoJSON` model mapping to the `OMSO` model elements.
7. Apply the General Flattening rule to simplify the remaining properties: `MT001(separator: '.')`.

#### Examples (Informative)

Expand All @@ -292,11 +311,12 @@ Example 1: One Environmental Monitoring Facility with a single measurement resul
"inspireId.localId": "EnvironmentalMonitoringFacility_1",
"inspireId.namespace": "https://https://github.com/INSPIRE-MIF/2017.2/GeoJSON/examples/ems/",
"identifier": "https://https://github.com/INSPIRE-MIF/2017.2/GeoJSON/examples/ems/EnvironmentalMonitoringFacility_1",
"legalBackground.citationDate": "",
"legalBackground.citationLink": "",
"legalBackground.citationName": "",
"legalBackground.citationLevel": "",
"legalBackground.citationType": "",
"legalBackground.date": "",
"legalBackground.link": "",
"legalBackground.name": "",
"legalBackground.level": "",
"legalBackground.level.href": "",
"legalBackground.type": "",
"mediaMonitored": "water",
"mediaMonitored.href": "http://inspire.ec.europa.eu/codelist/MediaValue/water",
"mobile": false,
Expand Down
2 changes: 1 addition & 1 deletion model-transformations/AssociatedComponentsHardType.md
View file
Expand Up @@ -25,7 +25,7 @@
</tr>
<tr>
<td>UML Model</td>
<td>TODO</td>
<td>Not applicable (there is no single UML model that results from this transformation rule)</td>
</tr>
<tr>
<td>Original instance in default encoding:</td>
Expand Down
2 changes: 1 addition & 1 deletion model-transformations/AssociatedComponentsSoftType.md
View file
Expand Up @@ -18,7 +18,7 @@
</tr>
<tr>
<td>UML Model</td>
<td>TODO</td>
<td>Not applicable (there is no single UML model that results from this transformation rule)</td>
</tr>
<tr>
<td>Original instance in default encoding:</td>
Expand Down
2 changes: 1 addition & 1 deletion model-transformations/ExtractPrimitiveArray.md
View file
Expand Up @@ -15,7 +15,7 @@
</tr>
<tr>
<td>UML Model</td>
<td>...</td>
<td>Not applicable (there is no single UML model that results from this transformation rule)</td>
</tr>
<tr>
<td>Original instance in default encoding:</td>
Expand Down
26 changes: 13 additions & 13 deletions model-transformations/GeneralFlattening.md
View file
Expand Up @@ -10,15 +10,15 @@
<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>
<ul>
<li>inspireId_namespace</li>
<li>name_spelling_text</li>
<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>
</td>
</tr>
<tr>
<td>UML Model</td>
<td>...</td>
<td>Not applicable (there is no single UML model that results from this transformation rule)</td>
</tr>
<tr>
<td>Original instance in default encoding:</td>
Expand Down Expand Up @@ -60,14 +60,14 @@
```xml
<ams:ManagementRestrictionOrRegulationZone>
<!-- ... -->
<ams:legalBasis_name>Bekendtgørelse af lov om skove</ams:legalBasis_name>
<ams:legalBasis_shortName>LBK nr 122 af 26/01/2017</ams:legalBasis_shortName>
<ams:legalBasis_date_date>2017-01-26</ams:legalBasis_date_date>
<ams:legalBasis_date_dateType_codeListValue>creation</ams:legalBasis_date_dateType_codeListValue>
<ams:legalBasis_date_dateType_codeList>http://standards.iso.org/ittf/PubliclyAvailableStandards/ISO_19139_Schemas/resources/codelist/ML_gmxCodelists.xml#CI_DateTypeCode</ams:legalBasis_date_dateType_codeList>
<ams:legalBasis_link>http://www.retsinformation.dk/eli/lta/2017/122</ams:legalBasis_link>
<ams:legalBasis_linklevel_title>national</ams:legalBasis_linklevel>
<ams:legalBasis_linklevel_href>http://inspire.ec.europa.eu/codelist/LegislationLevelValue/national</ams:legalBasis_linklevel>
<ams:legalBasis.name>Bekendtgørelse af lov om skove</ams:legalBasis.name>
<ams:legalBasis.shortName>LBK nr 122 af 26/01/2017</ams:legalBasis.shortName>
<ams:legalBasis.date.date>2017-01-26</ams:legalBasis.date.date>
<ams:legalBasis.date.dateType.codeListValue>creation</ams:legalBasis.date.dateType.codeListValue>
<ams:legalBasis.date.dateType.codeList>http://standards.iso.org/ittf/PubliclyAvailableStandards/ISO_19139_Schemas/resources/codelist/ML_gmxCodelists.xml#CI_DateTypeCode</ams:legalBasis.date.dateType.codeList>
<ams:legalBasis.link>http://www.retsinformation.dk/eli/lta/2017/122</ams:legalBasis.link>
<ams:legalBasis.linklevel>national</ams:legalBasis.linklevel>
<ams:legalBasis.linklevel.href>http://inspire.ec.europa.eu/codelist/LegislationLevelValue/national</ams:legalBasis.linklevel.href>
<!-- ... -->
</ams:ManagementRestrictionOrRegulationZone>
```
Expand All @@ -79,9 +79,9 @@
<td>
<p>Parameters:</p>
<ul>
<li>`separator`: The character to use to separate the original property name from the type name of the components.</li>
<li><code>separator`: 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 `separator` 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. `gml:name` vs. `gn:name`. 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. 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>
</td>
</tr>
<tr>
Expand Down
18 changes: 9 additions & 9 deletions model-transformations/PropertyCompositionToAssociation.md
View file
Expand Up @@ -7,14 +7,14 @@
</tr>
<tr>
<td>Description</td>
<td><p>Information regarding resources such as legal documents can be stored in an external register or non-INSPIRE online application, possibly using other standardised encodings. Such information should not be duplicated in the INSPIRE model if possible. THus, the information should be referred to from a GML application schema "by reference".</p>
<td><p>Information regarding resources such as legal documents can be stored in an external register or non-INSPIRE online application, possibly using other standardised encodings. Such information should not be duplicated in the INSPIRE model if possible. Thus, the information should be referred to from a GML application schema "by reference".</p>

<p>It gives a lot of work for data providers when they have to document a lot of metadata regarding e.g. laws, documents, authorities, etc. that they are not responsible for, and when this information is already online somewhere else this is redundant work. Therefore, properties referring to laws, documents, authorities and other online resources not typically belonging to the geographic information domain should be implemented by reference, and it should be recognised that their values are not necessarily encoded in GML.</p>
</td>
</tr>
<tr>
<td>UML Model</td>
<td>...</td>
<td>Not applicable (there is no single UML model that results from this transformation rule)</td>
</tr>
<tr>
<td>Original instance in default encoding:</td>
Expand Down Expand Up @@ -56,14 +56,14 @@
<td>

```xml
<am:ManagementRestrictionOrRegulationZone>
<ams:ManagementRestrictionOrRegulationZone>
<!-- ... -->
<am:legalBasis
<ams:legalBasis
xlink:href="http://www.retsinformation.dk/eli/lta/2017/122"
xlink:title="Bekendtgørelse af lov om skove"
/>
<!-- ... -->
</am:ManagementRestrictionOrRegulationZone>
</ams:ManagementRestrictionOrRegulationZone>
```

</td>
Expand All @@ -73,15 +73,15 @@
<td>
<p>Parameters:</p>
<ul>
<li>`referenceProperty`: The name of the property which to change to a reference.</li>
<li><code>referenceProperty</code>: The name of the property which to change to a reference.</li>
</ul>
<p>On the model level, this changes the tagged value `inlineOrByReference` to have the value `byReference` on the property.</p>
<p>On the model level, this changes the tagged value <code>inlineOrByReference</code> to have the value <code>byReference</code> on the property.</p>
</td>
</tr>
<tr>
<td>Instance transformation rule:</td>
<td><p>Parameters: None</p>
<p>It is only possible to convert an instance using the "inline" pattern when the URL is present somewhere in the data, which then must be inserted in `@xlink:href`. A name or title, if present, may be inserted in `@xlink:title`.</p>
<p>It is only possible to convert an instance using the "inline" pattern when the URL is present somewhere in the data, which then must be inserted in <code>@xlink:href</code>. A name or title, if present, may be inserted in <code>@xlink:title</code>.</p>
</td>
</tr>
<tr>
Expand All @@ -90,7 +90,7 @@
</tr>
<tr>
<td>Known usability issues:</td>
<td>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.</td>
<td>Display of <code>@xlink:href</code> and <code>@xlink:title</code> may not be supported in all clients. However, this is the same problem as for code lists, which are widely used in INSPIRE.</td>
</tr>
<tr>
<td>INSPIRE Compliance:</td>
Expand Down
74 changes: 56 additions & 18 deletions model-transformations/SimpleCitation.md
View file
Expand Up @@ -7,16 +7,16 @@
</tr>
<tr>
<td>Description</td>
<td><p>Citations are another element type that is used in many different places throughout the INSPIRE data specifications. There are concrete types such as `LegislationCitation`, which is an INSPIRE base type, but also types coming from other schemas, such as `CI_Citation` from ISO 19115. All of these structures tend to bury key information in deeply nested structures, creating a lot of overhead. This rule proposes a simplified altenrative representation.</p>
<td><p>Citations are another element type that is used in many different places throughout the INSPIRE data specifications. There are concrete types such as <code>LegislationCitation</code>, which is an INSPIRE base type, but also types coming from other schemas, such as <code>CI_Citation</code> from ISO 19115. All of these structures tend to bury key information in deeply nested structures, creating a lot of overhead. This rule proposes a simplified alternative representation.</p>
<p>The simplified citation is based on a link to an external publication and adds minimal information with four properties:</p>
<ul>
<li>citationDate</li>
<li>citationLink</li>
<li>citationName</li>
<li>citationLevel</li>
<li>citationType</li>
<li>citationLink</li>
<li>citationName</li>
<li>citationLevel</li>
<li>citationType</li>
</ul>
<p>Each of these properties maps directly to an existing property of the original citation types. The `citationType` property can be used to indicate what kind of citation is represented by this object; its values can be taken from the original type name, or can be base don a codelist.</p>
<p>Each of these properties maps directly to an existing property of the original citation types. The <code>citationType</code> property can be used to indicate what kind of citation is represented by this object; its values can be taken from the original type name, or can be based on a codelist.</p>
</td>
</tr>
<tr>
Expand All @@ -28,7 +28,32 @@
<td>

```xml

<am:ManagementRestrictionOrRegulationZone>
<!-- ... -->
<am:legalBasis
xlink:href="http://www.retsinformation.dk/eli/lta/2017/122"
xlink:title="Bekendtgørelse af lov om skove">
<base2:LegislationCitation>
<base2:name>Bekendtgørelse af lov om skove</base2:name>
<base2:shortName>LBK nr 122 af 26/01/2017</base2:shortName>
<base2:date>
<gmd:CI_Date>
<gmd:date>
<gco:Date>2017-01-26</gco:Date>
</gmd:date>
<gmd:dateType>
<gmd:CI_DateTypeCode
codeListValue="creation"
codeList="http://standards.iso.org/ittf/PubliclyAvailableStandards/ISO_19139_Schemas/resources/codelist/ML_gmxCodelists.xml#CI_DateTypeCode" />
</gmd:dateType>
</gmd:CI_Date>
</base2:date>
<base2:link>http://www.retsinformation.dk/eli/lta/2017/122</base2:link>
<base2:level xlink:href="http://inspire.ec.europa.eu/codelist/LegislationLevelValue/national" xlink:title="national" />
</base2:LegislationCitation>
</am:legalBasis>
<!-- ... -->
</am:ManagementRestrictionOrRegulationZone>
```

</td>
Expand All @@ -38,39 +63,52 @@
<td>

```xml

<ems:EnvironmentalMonitoringFacility>
<!-- ... -->
<ems:legalBackground>
<simple:SimpleCitiation>
<simple:name>Bekendtgørelse af lov om skove</simple:name>
<simple:type>LegislationCitation</simple:type>
<simple:date>2017-01-26</simple:date>
<simple:link>http://www.retsinformation.dk/eli/lta/2017/122</simple:link>
<simple:level xlink:href="http://inspire.ec.europa.eu/codelist/LegislationLevelValue/national" xlink:title="national" />
</simple:LegislationCitation>
</ems:legalBackground>
<!-- ... -->
</ems:EnvironmentalMonitoringFacility>
```

</td>
</tr>
<tr>
<td>Model transformation rule: </td>
<td>
<p>Parameters:</p>
<ul>
<li>`separator`: The character to use to separate the original property name from the ISO 639-3 language code.</li>
<li>`languageCodes`: A List of ISO 693-3 or ISO 693-5 codes for which to create the specific proeprties.</li>
</ul>
<p>Create a new property for every language given as a parameter. Give each property as name the concatenation of "name", the value of the separator parameter and the ISO 693-3 or ISO 693-5 code of the language.</p>
<p>Substitute existing <code>LegislationCitation</code> and <code>CI_Citation</code> types with this SimpleCitation type.</p>
</td>
</tr>
<tr>
<td>Instance transformation rule:</td>
<td>
<p>Copy the value of the `spelling.text` to the new property.</p>
<ul>
<li>Copy the value of <code>base2:dateEnteredIntoForce</code> to the property <code>simple:date</code>.</li>
<li>Copy the value of <code>base2:name</code> to the property <code>simple:name</code>.</li>
<li>Copy the value of <code>base2:dateEnteredIntoForce</code> to the property <code>simple:date</code>.</li>
<li>Copy the value(s) of <code>base2:level</code> to the property <code>simple:level</code>. Note that only one link may be present in the data.</li>
<li>Insert the element name <code>LegislationCitation</code> to the property <code>simple:type</code>.</li>
</ul>
</td>
</tr>
<tr>
<td>Solves usability issues:</td>
<td>The transformed data structure can easily be edited, filtered and symbolized in desktop GIS and web GIS software. This transformation also reduced data volume significantly in datasets that use in-place encoding of `GeographicalNames`.</td>
<td>The transformed data structure can easily be edited, filtered and symbolized in desktop GIS and web GIS software. This transformation also reduces data volume.</td>
</tr>
<tr>
<td>Known usability issues:</td>
<td>None.</td>
</tr>
<tr>
<td>INSPIRE Compliance:</td>
<td>This rule discards individual metadata abour 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 and is not bijective.</td>
<td>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](./PropertyCompositiontoAssociation.md) rule to add more information from an external register.</td>
</tr>
<tr>
<td>Examples of this encoding rule:</td>
Expand All @@ -80,4 +118,4 @@

Notes:

- This rule may be enhanced by storing additional properties that were present on the original name in "subfields" such as `name_deu_nativeness`.
* None.

0 comments on commit 2f53ceb

Please sign in to comment.