Primary geometry and place encoding

[jechterhoff]

In requirement “/req/geojson-formats/primary-geometry”, we need to be more clear about how the multiplicity of the mapped UML property is taken into account:

• What about an optional property, i.e., minimum multiplicity = 0? That should be considered (by allowing a null value). Same for a required property, i.e., minimum multiplicity > 0 (do not allow a null value).
• A note should be added about the maximum multiplicity of primary geometry properties. A property with maximum multiplicity > 1 would be a mismatch for the mapping to the top-level "geometry" member.

This is the same for requirement “/req/jsonfg/primary-place”.

[jechterhoff]

We found out that for the JSON-FG encoding, the geometry conversion can be even more complicated. For a detailed explanation, see https://github.com/ShapeChange/ShapeChange/issues/344.

We may want to consider how far the best practice specification should go regarding the case of secondary geometry (currently noted in the specification as primary place - see section 7.7.3). Maybe that should become a future extension. We could then focus on correct conversion of the primary geometry property in the JSON-FG encoding for the case of application schemas that do not have a secondary geometry:

• If the type of the primary geometry property is compatible to one of the GeoJSON geometry types (for example GM_Point, GM_Curve, GM_Surface, GM_MultiPoint, GM_MultiCurve, and GM_MultiSurface; this would need to become a configuration option of the converter implementation), then encode JSON Schema constraints for the primary geometry for both the geometry- and the place-member. Also allow null as value for both members.
• Otherwise: Encode the JSON Schema constraints for the primary geometry only for the place-member. Allow null for the place member only if it is optional or voidable.
  • NOTE: No constraints are defined for the geometry-member, allowing data publishers to encode a value for the geometry-member in any way they deem appropriate (which is out-of-scope for the best practice specification).

We need to be very careful here, though. This approach will only work for application schemas that have no secondary geometry. We must not expect it to work in combination with an extending requirements class that introduces requirements for the encoding of secondary geometries. An extension that introduces support for application schemas with secondary geometries must be a separate requirements class with no dependency on /req/jsonfg (which we may want to rename, to reflect that it is specific to cases of schemas with no secondary geometry). That extension would then have to define new requirements for encoding the primary geometry, taking into account the potential presence of a secondary geometry.

[jechterhoff]

Ideally, the JSON-FG compliant JSON Schema encoding is independent of the application schema having a secondary geometry. The solution should be simple and support all encoding cases. That may lower the level to which primary and secondary geometries can be validated with the resulting JSON Schema. However, it appears to be a useful tradeoff.

In the JSON-FG requirements class, augment the encoding of the primary geometry, i.e., the constraints for the top-level "geometry" member, to always allow null. Furthermore, always allow null for the primary place.

[jechterhoff]

Standardization work within OGC has made significant progress since the UML to JSON Schema encoding rules have been developed. OGC API - Features - Part 5: Schema defines core roles for features, i.e. property roles for feature data. There are roles for:

• primary geometry
• primary temporal information (primary-instant, primary-interval-start, primary-interval-end)
• feature type
• feature references (reference)
• id

There are even keywords to define property sequence, unit of measure (x-ogc-unit, x-ogc-unit-lang), semantic definition (x-ogc-definition), collection ID (x-ogc-collectionId), URI template (x-ogc-uriTemplate).

The Best Practice differentiates primary geometry and primary place. We should revise this, in order to be in synch with the above (at least regarding primary geometry and temporal information) - which JSON-FG 0.2.2 also is. That can actually help simplify the encoding rules, I think.

[jechterhoff]

Having discussed this with @PalmJanssen, we decided to remove the concept of "primary place", and only keep the conept of "primary geometry" (in line with latest developments within OGC). The document will be updated accordingly.