JSON Schema target - enhance support for JSON-FG geometry/place encoding

[jechterhoff]

In JSON-FG, the geometry of an object is encoded in the geometry and / or the place member of a JSON-FG feature. The geometry encoding depends upon the geometry type, the spatial reference system, and the media type. For further details, see https://docs.ogc.org/DRAFTS/21-045.html#_use_of_geometry_andor_place.

The ShapeChange JSON Schema target is able to identify the primary geometry (sometimes also called default geometry) of a feature type, as well as the secondary geometry. The secondary geometry would always be encoded in the place-member of a JSON-FG feature. The differentiation between primary and secondary geometry is only relevant for application schemas which define multiple geometric properties for at least one feature type, and where different geometric properties shall be encoded in the geometry and place members.

NOTE: This issue was created to document and keep track of the encoding issue and potential solution for geometries in a JSON-FG JSON Schema encoding. The potential solution takes into account application schemas that can define a secondary geometry. A first implementation step could be to just implement parts of the proposed solution, in order to solve the encoding issue for application schemas that do not define a secondary geometry.

For historic reasons, the primary and secondary geometry are identified by the JSON Schema target as follows:

• The primary geometry is determined using different conversion rules (of which only a single one should be used per encoding rule):
  • rule-json-cls-defaultGeometry-singleGeometryProperty: For application schemas with at most a single geometric property per feature type. That property will automatically be recognized as the primary geometry.
  • rule-json-cls-defaultGeometry-multipleGeometryProperties: For application schemas where one or more feature types have multiple geometric properties. The primary geometry is defined by explicitly setting tagged value defaultGeometry=true on the property.
  • rule-json-cls-primaryGeometry: For any kind of application schema; the property that contains the primary geometry of a feature type is explicitly defined by setting tagged value jsonPrimaryGeometry=true.
• The secondary geometry is determined by setting tagged value jsonPrimaryPlace=true and adding rule-json-cls-primaryPlace to the encoding rule of the class that owns the property.

Currently, The JSON Schema target converts the property that represents the primary geometry only to JSON Schema constraints for the top-level geometry-member. The case where no secondary geometry is encoded and thus the actual JSON-FG data could contain the value of the primary geometry in the geometry-member and / or the place-member is not considered. That can lead to unjustified validation errors: for example, if JSON-FG data would contain the primary geometry value in the place-member, and null as value for the geometry-member, but the JSON Schema constraints created by the JSON Schema target do not allow null for the geometry-member (then the null value for the geometry-member would be reported as invalid). In that example, the value of the place-member would also not be restricted via JSON Schema constraints, so it might contain a geometry type that is different to the one defined by the primary geometry property in the application schema.

A solution could be to enhance the JSON Schema target as follows:

• Add new target parameter geoJsonCompatibleGeometryTypes: (comma-separated) list of types (typically from ISO 19107), that are defined as being compatible with GeoJSON geometry types. Geometric properties that have one of these types can be encoded as JSON Schema constraints for the geometry-member. The default value of the parameter would be: GM_Point, GM_Curve, GM_Surface, GM_MultiPoint, GM_MultiCurve, GM_MultiSurface.
• Extend rule-json-cls-primaryGeometry, rule-json-cls-defaultGeometry-multipleGeometryProperties, and rule-json-cls-defaultGeometry-singleGeometryProperty to recognize the new parameter geoJsonCompatibleGeometryTypes. If the geometry type of the primary geometry property is compatible, JSON Schema constraints for the geometry member will be encoded. Otherwise, an error is logged - unless the constraints can be encoded in the place-member (see next bullet item).
• Add a new conversion rule (rule-json-cls-jsonFgGeometry), which takes into account the different options for encoding geometry values in JSON-FG features. The primary geometry property (identified via rule-json-cls-primaryGeometry, rule-json-cls-defaultGeometry-multipleGeometryProperties, or rule-json-cls-defaultGeometry-singleGeometryProperty) is encoded as JSON Schema constraints for the geometry and / or place members as follows:
  • If no secondary geometry is defined for a feature type, and all its subtypes:
    • NOTE: The secondary geometry of a feature type is identified by a geometric property (potentially inherited) with tagged value jsonPrimaryPlace=true, with the encoding rule of the owning class containing rule-json-cls-primaryPlace. However, subtypes need to be taken into account as well. Otherwise, if the JSON Schema constraints for the primary geometry would be encoded for both the geometry- and the place-member, there would be the chance of creating an inconsistent JSON Schema definition for a subtype, if that subtype defined a secondary geometry that has a different geometry type than the primary geometry. A new mechanism is introduced, to define if a feature type can have a secondary geometry:
      • For a given feature type, the value of a variable noSecondaryGeometry is determined. If the value of that variable is true, then it means that the class itself and all its subtypes (which may be defined in external application schemas not contained in the processed UML model) will not define a secondary geometry. The first step in the determination of the variable value is to get the value of a new target parameter noSecondaryGeometry (default value: true). The second step would be to see if the feature type has tagged value noSecondaryGeometry with a value equal to (ignoring case) true or false. If so, then the tagged value would override the value from the target parameter.
      • For application schemas with at most one geometric property per feature type, or where it is known that no secondary geometries exist, the default value of target parameter noSecondaryGeometry suffices. It does not need to be explicitly configured, and the tagged value noSecondaryGeometry also does not need to be added in the model.
      • If, however, secondary geometries can occur, or should be allowed in general (e.g. for a standard schema that anyone is allowed to extend with a custom schema), then the target parameter should be set to false. If it is known for some feature types that they - or their subtypes - do not have a secondary geometry, then tag noSecondaryGeometry should be set to true for these feature types. That way, at least for cases of feature types without secondary geometry, JSON Schema constraints can be created for both the geometry and the place members. For all other cases, where a feature type (or one of its subtypes) can have a secondary geometry, JSON Schema constraints would only be created for the geometry-member.
    • If the geometry type of the primary geometry is listed in the value of the new target parameter geoJsonCompatibleGeometryTypes: The JSON Schema constraints for the geometry type are encoded for both the geometry- and the place-members. Value null will be allowed for both members (to allow the encoding of the geometry value in either member, and the omission of a value in the other member).
    • Otherwise: The JSON Schema constraints for the geometry type of the primary geometry are only encoded for the place-member. The value null is only allowed for the place-member, if the primary geometry property is optional or voidable/nillable.
      • NOTE: No specific constraints are created for the geometry-member. That is done on purpose, to allow a data publisher to assign a geometry value for the geometry-member which is derived in some way - which is defined by the data publisher - from the geometry value of the place-member.
  • Otherwise, i.e., a secondary geometry is defined for the feature type (or one of its subtypes):
    • If the geometry type of the primary geometry is listed in the value of the new target parameter geoJsonCompatibleGeometryTypes: The JSON Schema constraints for the geometry type of the primary geometry are only encoded for the geometry-member. The value null is only allowed for the geometry-member, if the primary geometry property is optional or voidable/nillable.
    • Otherwise: An error is logged, and no particular JSON Schema constraints are encoded for the primary geometry. The reason is that the primary geometry cannot be encoded in the geometry-member, and there is a separate definition - the secondary geometry - for the place-member (either in the feature type itself, or in one of its subtypes).

[jechterhoff]

In (the next) release v2.14, the following additions will become available:

• Target parameter geoJsonCompatibleGeometryTypes
• rule-json-cls-primaryGeometry, rule-json-cls-defaultGeometry-multipleGeometryProperties, and rule-json-cls-defaultGeometry-singleGeometryProperty recognize the new target parameter geoJsonCompatibleGeometryTypes
• rule-json-cls-jsonFgGeometry is added, with the limitation that it is only applicable for application schemas that do not define a secondary geometry