Add note regarding primaryGeometry determination

Signed-off-by: Johannes Echterhoff <[email protected]>

document.html

@@ -1433,7 +1433,7 @@ <h1 id="content">Contents</h1>
 <div class="boilerplate-feedback">
 
 </div>
-</div><br /><div id="_abstract"><h1 class="AbstractTitle" id="toc0">I.  Abstract</h1><p id="_e4989fa6-f9db-453a-7fbc-2b1dc200b6c9">This best practice document on UML to JSON encoding rules is an initiative of Geonovum. The aim is to come to a standardized encoding from UML to JSON, in order to achieve technical interoperability in the chain from conceptual models to JSON implementation. In this document, JSON implementation includes plain JSON, GeoJSON and JSON-FG.</p><p id="_caf5ccf8-c530-9006-6680-5b026697deec">Application schemas in UML are used to model geospatial information for a given domain, as part of data specifications defining information and data content of a relevant universe of discourse. In the geospatial domain, UML profiles are defined by <a href="#ref_iso19103">ISO 19103:2015</a> and <a href="#ref_iso19109">ISO 19109:2015</a>. These profiles are also used in this document. Application schemas operate at the conceptual level. At the implementation or data level, JSON is one of the major data encodings used by current web applications. The UML to JSON encoding rules defined in the context of this document is a best practice. Eventually, this document may also support the development of an international standard for the conversion of UML to JSON (Schema) in the geospatial domain.</p><p id="_5dbf284e-2112-fd6f-aa16-b8f5dabf0abb">To facilitate a proper JSON encoding, an extension of the ISO 19103 and 19109 UML profiles is proposed, resulting in a UML-JSON encoding profile.</p><p id="_dca36df9-c787-e860-6fe3-72bfcb5cde7f">The encoding rules are structured in 40 requirements and a number of recommendations, subdivided into 18 core requirements, 1 requirement specific for plain JSON schema format, 5 for GeoJSON format, 5 for JSON-FG Schema format, 3 requirements for binding and referencing of elements, 2 for union constructs, 5 for code lists and 1 for encoding a dedicated entity property in JSON. The requirement classes are supported by UML examples and subsequent JSON encodings.</p></div><div class="Section3" id="_50f36b34-0751-47e6-a606-6910359e7302"><h1 class="IntroTitle" id="toc1">II.  Keywords</h1><p>The following are keywords to be used by search engines and
+</div><br /><div id="_abstract"><h1 class="AbstractTitle" id="toc0">I.  Abstract</h1><p id="_e4989fa6-f9db-453a-7fbc-2b1dc200b6c9">This best practice document on UML to JSON encoding rules is an initiative of Geonovum. The aim is to come to a standardized encoding from UML to JSON, in order to achieve technical interoperability in the chain from conceptual models to JSON implementation. In this document, JSON implementation includes plain JSON, GeoJSON and JSON-FG.</p><p id="_caf5ccf8-c530-9006-6680-5b026697deec">Application schemas in UML are used to model geospatial information for a given domain, as part of data specifications defining information and data content of a relevant universe of discourse. In the geospatial domain, UML profiles are defined by <a href="#ref_iso19103">ISO 19103:2015</a> and <a href="#ref_iso19109">ISO 19109:2015</a>. These profiles are also used in this document. Application schemas operate at the conceptual level. At the implementation or data level, JSON is one of the major data encodings used by current web applications. The UML to JSON encoding rules defined in the context of this document is a best practice. Eventually, this document may also support the development of an international standard for the conversion of UML to JSON (Schema) in the geospatial domain.</p><p id="_5dbf284e-2112-fd6f-aa16-b8f5dabf0abb">To facilitate a proper JSON encoding, an extension of the ISO 19103 and 19109 UML profiles is proposed, resulting in a UML-JSON encoding profile.</p><p id="_dca36df9-c787-e860-6fe3-72bfcb5cde7f">The encoding rules are structured in 40 requirements and a number of recommendations, subdivided into 18 core requirements, 1 requirement specific for plain JSON schema format, 5 for GeoJSON format, 5 for JSON-FG Schema format, 3 requirements for binding and referencing of elements, 2 for union constructs, 5 for code lists and 1 for encoding a dedicated entity property in JSON. The requirement classes are supported by UML examples and subsequent JSON encodings.</p></div><div class="Section3" id="_54de338d-4193-46d9-b460-65da50556220"><h1 class="IntroTitle" id="toc1">II.  Keywords</h1><p>The following are keywords to be used by search engines and
     document catalogues.</p><p>ogcdoc, OGC document, UML, JSON, JSON Schema, encoding, GeoJSON, JSON-FG</p></div><br /><div id="_preface"><h1 class="ForewordTitle" id="toc2">III.  Preface</h1><p id="_9835ea72-0778-d76c-9dd3-aca451feb45b">The project leading to this document was initiated by Geonovum. In collaboration with Interactive Instruments a best practice is developed on encoding UML to JSON. The project team consisted of the following persons:</p><ul id="_00647300-135c-76d6-0eb2-e9045e14e798"><li><p id="_c0455962-bd3f-8aa9-eab2-f811d699c7f5">Clemens Portele (Interactive Instruments)</p>
 </li>
 <li><p id="_226ac698-c0b3-b004-6b92-d39ac26f7a31">Johannes Echterhoff (Interactive Instruments)</p>
@@ -1446,7 +1446,7 @@ <h1 id="content">Contents</h1>
 </li>
 <li><p id="_bad8e162-8e8d-8b12-71a9-6af484976c41">Wilko Quak (Geonovum).</p>
 </li>
-</ul><p id="_35fbef76-1286-603d-f747-f63cd841abfc">This document defines how a conceptual schema in UML, compliant to <a href="#ref_iso19103">ISO 19103:2015</a> and <a href="#ref_iso19109">ISO 19109:2015</a>, can be encoded in JSON. A number of requirements classes are defined, which contain the necessary requirements and technical details.</p><p id="_e99a11a1-63ad-eaff-4a7a-f67c742a5d36">JSON is one of the major data encodings used by current web applications. In order to achieve a high level of interoperability when exchanging JSON encoded data between such applications, especially when the applications are developed by different entities, the semantics and structure of the data need to be well defined. In the geospatial domain, conceptual schemas are used to define application relevant information. Typically, some additional schema language is used to define the structures for encoding the information. For JSON encoded data, such a schema language is JSON Schema. Ideally, the JSON Schema constructs can automatically be derived from a conceptual schema. For that task, a set of encoding rules is needed.</p><p id="_a6faafb0-1d3b-c59f-edd2-0dc8c2cf06f5">Within the OGC, the <a href="https://www.ogc.org/projects/initiatives/ugas-2020">UML-to-GML Application Schema Pilot 2020</a> (UGAS-2020) was the first innovation initiative that produced a comprehensive set of encoding rules, for the conversion of ISO 19109 compliant application schemas in UML to JSON Schema. The <a href="#ref_ugas2020">UGAS-2020 Engineering Report</a> documents the findings of that initiative.</p><p id="_560bb0b7-6ff5-96e5-7122-272485d55800">This document is based on and extends the results of UGAS-2020 regarding JSON Schema encoding rules. It defines the conversion behavior in an implementation agnostic way, adhering to the requirements defined in <a href="#ref_modspec">OGC 08-131r3</a> for writing OGC standards. This document thus represents the next step on the way to standardizing JSON Schema encoding rules in the geospatial domain.</p><p id="_70e57ccb-4bfc-48ac-e0ef-e0ea6b4e8f25"><b>IMPORTANT</b> This working document is developed and maintained by Geonovum. It is intended for presentation to OGC later on, and will potentially be put forward into the OGC process.</p><p id="_f1349e24-df00-bd4c-f382-3685a40a02d9">Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.</p><p id="_1397be25-19cd-13ae-cad4-6336d1352ed3">Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.</p></div><div class="Section3" id="_security_considerations"><h1 class="IntroTitle" id="toc3">IV.  Security Considerations</h1><p id="_6bffb48c-5a4a-c73f-8352-74e8ed0d680a">No security considerations have been made for this document.</p></div><div class="Section3" id="_f620490c-671b-4fe0-a5ed-d94527f7f4f4"><h1 class="IntroTitle" id="toc4">V.  Submitting Organizations</h1><p>The following organizations submitted this Document to the
+</ul><p id="_35fbef76-1286-603d-f747-f63cd841abfc">This document defines how a conceptual schema in UML, compliant to <a href="#ref_iso19103">ISO 19103:2015</a> and <a href="#ref_iso19109">ISO 19109:2015</a>, can be encoded in JSON. A number of requirements classes are defined, which contain the necessary requirements and technical details.</p><p id="_e99a11a1-63ad-eaff-4a7a-f67c742a5d36">JSON is one of the major data encodings used by current web applications. In order to achieve a high level of interoperability when exchanging JSON encoded data between such applications, especially when the applications are developed by different entities, the semantics and structure of the data need to be well defined. In the geospatial domain, conceptual schemas are used to define application relevant information. Typically, some additional schema language is used to define the structures for encoding the information. For JSON encoded data, such a schema language is JSON Schema. Ideally, the JSON Schema constructs can automatically be derived from a conceptual schema. For that task, a set of encoding rules is needed.</p><p id="_a6faafb0-1d3b-c59f-edd2-0dc8c2cf06f5">Within the OGC, the <a href="https://www.ogc.org/projects/initiatives/ugas-2020">UML-to-GML Application Schema Pilot 2020</a> (UGAS-2020) was the first innovation initiative that produced a comprehensive set of encoding rules, for the conversion of ISO 19109 compliant application schemas in UML to JSON Schema. The <a href="#ref_ugas2020">UGAS-2020 Engineering Report</a> documents the findings of that initiative.</p><p id="_560bb0b7-6ff5-96e5-7122-272485d55800">This document is based on and extends the results of UGAS-2020 regarding JSON Schema encoding rules. It defines the conversion behavior in an implementation agnostic way, adhering to the requirements defined in <a href="#ref_modspec">OGC 08-131r3</a> for writing OGC standards. This document thus represents the next step on the way to standardizing JSON Schema encoding rules in the geospatial domain.</p><p id="_70e57ccb-4bfc-48ac-e0ef-e0ea6b4e8f25"><b>IMPORTANT</b> This working document is developed and maintained by Geonovum. It is intended for presentation to OGC later on, and will potentially be put forward into the OGC process.</p><p id="_f1349e24-df00-bd4c-f382-3685a40a02d9">Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.</p><p id="_1397be25-19cd-13ae-cad4-6336d1352ed3">Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.</p></div><div class="Section3" id="_security_considerations"><h1 class="IntroTitle" id="toc3">IV.  Security Considerations</h1><p id="_6bffb48c-5a4a-c73f-8352-74e8ed0d680a">No security considerations have been made for this document.</p></div><div class="Section3" id="_a0cdb259-c07a-416c-bdf7-97e2fdc0d09e"><h1 class="IntroTitle" id="toc4">V.  Submitting Organizations</h1><p>The following organizations submitted this Document to the
    Open Geospatial Consortium (OGC):</p><ul><li>Geonovum</li>
 <li>interactive instruments GmbH</li></ul></div><p class="zzSTDTitle1">Best Practice for OGC - UML to JSON Encoding Rules</p><div id="_scope"><h1 id="toc5">1.  Scope</h1><p id="_3edbaf69-c208-b518-7bc9-0cd5fc495893">This document defines requirements for encoding application schemas in UML, which conform to the UML profile defined by <a href="#ref_iso19103">ISO 19103:2015</a> and potentially also <a href="#ref_iso19109">ISO 19109:2015</a>, as JSON schemas. The requirements classes cover the creation of JSON schemas for:</p><ul id="_f1934ca1-47cb-5f8c-9ac7-d401da242554"><li><p id="_61b6bcdf-0071-f32d-32bc-1e55cc7c779e">a plain JSON encoding;</p>
 </li>
@@ -2086,15 +2086,18 @@ <h3 class="TermNum" style="text-align:left;" id="term-type-with-identity">4.1.5.
 </li>
 </ul>
 
-<div id="_2ea3c61f-f198-b6ec-d314-13482b18b841" class="Note"><p><span class="note_label">NOTE  3</span>  A feature type that has multiple UML properties with tag “primaryGeometry” = true is not modeled correctly.</p></div>
+<div id="_5ef5d3a4-2fcc-d1d0-a5c9-fd32ba743b06" class="Note"><p><span class="note_label">NOTE  3</span>  A feature type that has multiple UML properties with tag “primaryGeometry” = true is not modeled correctly.</p></div>
+
+<div id="_7eae321d-005d-8540-0800-19792275e009" class="Note"><p><span class="note_label">NOTE  4</span>  Setting tagged value “primaryGeometry” = false can be useful in cases of geometric properties of classes that are (expected to be) subtyped, with the subtypes defining their own primary geometry properties. If the supertype had a geometric property without such a tagged value, the second part of the rule (for determining the primary geometry) would apply, thereby incorrectly identifying the supertype property as primary geometry. That can lead to undesired JSON Schema constraints.</p></div>
 </div>
 
 <div id="jsonschema_req_core_primary_tempinfo"><h3 id="toc44">7.3.9.  Primary temporal information</h3>
 
 <p id="_a93e9e12-b980-c1fd-5265-8e67c0bde7e3"><a href="#ref_ogcapifeatures_part5_schemas">OGC 23-058r1</a> defines the concept of <i>primary temporal information</i>:</p>
 
-<div class="Quote" id="_12226bad-e3a4-3a7f-0d4b-28b20b6433fd"><p id="_f1cbe31f-c814-7883-869a-2394a7ba1da6"><b>primary temporal information</b>
-the time instant or time interval that the publisher considers as the most important temporal characteristic of a <b>feature</b></p>
+<div class="Quote" id="_725c5896-8ec0-5fe2-ae80-57e6320a8e74"><p id="_31eeb56b-1fd7-0308-57c4-0d37cd219230"><b>primary temporal information</b></p>
+
+<p id="_bb59c33d-ef5a-9142-120f-c75e4b453b32">the time instant or time interval that the publisher considers as the most important temporal characteristic of a <b>feature</b></p>
 
 <div id="_f7033a7f-b30c-8ae5-41fa-9c8e31741f1f" class="Note"><p><span class="note_label">NOTE  1</span>  A feature can be described by multiple temporal properties. For example, an event can have a property with an instant or interval when the event occurred or will occur and another property when the event was recorded in the dataset. The primary temporal information can also be built from two properties, e.g., when the feature has two properties describing the start and end instants of an interval.</p></div>
 <p class="QuoteAttribution">— OGC API — Features — Part 5: Schemas, <a href="#ref_ogcapifeatures_part5_schemas">OGC 23-058r1,  Section 4.1</a></p></div>

sections/clause_7_normative_text.adoc

@@ -820,6 +820,8 @@ In order to identify the UML property that represents the primary geometry of a
 
 NOTE: A feature type that has multiple UML properties with tag "primaryGeometry" = true is not modeled correctly.
 
+NOTE: Setting tagged value "primaryGeometry" = false can be useful in cases of geometric properties of classes that are (expected to be) subtyped, with the subtypes defining their own primary geometry properties. If the supertype had a geometric property without such a tagged value, the second part of the rule (for determining the primary geometry) would apply, thereby incorrectly identifying the supertype property as primary geometry. That can lead to undesired JSON Schema constraints. 
+
 
 [[jsonschema_req_core_primary_tempinfo]]
 ==== Primary temporal information
@@ -830,6 +832,7 @@ NOTE: A feature type that has multiple UML properties with tag "primaryGeometry"
 ____
 
 *primary temporal information*
+
 the time instant or time interval that the publisher considers as the most important temporal characteristic of a *feature*
 
 NOTE: A feature can be described by multiple temporal properties. For example, an event can have a property with an instant or interval when the event occurred or will occur and another property when the event was recorded in the dataset. The primary temporal information can also be built from two properties, e.g., when the feature has two properties describing the start and end instants of an interval.