UML-to-GML Application Schema Pilot (UGAS-2020) Engineering Report

During UGAS-2020, several ideas for additional conversion rules, or extensions of existing conversion rules, were discussed. The following sections document these ideas. They may be implemented in the future.

JSON data certainly is of interest to typical web applications. It can also be of interest to the semantic community. With JSON-LD, it is possible to convert JSON data to RDF data. The conversion thereby defines the semantics of the JSON data. The resulting RDF data can be used by semantic applications. The definition of semantics of JSON data through the use of JSON-LD has been investigated in OGC Testbed-14. For further details, also on limitations of that approach, see the OGC Testbed-14: Application Schemas and JSON Technologies Engineering Report.

UGAS-2020 investigated the implications of a few JSON Schema conversion rules regarding the ability for mapping JSON data (that complies to these rules) to RDF using JSON-LD. It is recommended that a thorough analysis of mapping JSON data to RDF using JSON-LD be conducted in a future activity, specifically taking into account the JSON Schema conversion rules developed in UGAS-2020. That activity should investigate how JSON-LD context documents can automatically be derived from an application schema, given a set of ontology and JSON Schema encoding rules that apply to the application schema. The analysis should be accompanied by a prototypical implementation.

The following paragraphs summarize the results of the investigations on JSON-LD that were conducted in UGAS-2020.

The JSON Schema conversion of code lists describes three different ways to encode code lists and thus also code values.

In the first two cases, a code is represented by a simple JSON value, while in the case of a link object, a code is represented by a JSON object.

The cases where a code is represented by anything other than a simple JSON string are problematic when using JSON-LD to map JSON data to RDF. The reason is that, following the ISO 19150-2 conversion rule for code lists (as documented in the [OGC Testbed-12 ShapeChange Engineering Report]), codes are represented in RDF/OWL as individuals - which are directly used as the RDF/OWL property that represents a code list valued UML property.

If the JSON representation of a code is a JSON number, then that number cannot be mapped to RDF using JSON-LD. That is a limitation of JSON-LD, which is documented in more detail in the OGC Testbed-14: Application Schemas and JSON Technologies Engineering Report, section 6.2.2.2.

If the JSON representation of a code is a link object, with one of the members of the (JSON) link object containing the code value, then the link object cannot be mapped to a simple RDF/OWL individual using JSON-LD. Instead, the mapping result would be an RDF resource that represents the link object, with a property that represents the member that contains the code value. Consider the example shown in Listing 2.

A link object always has a specific structure, which in this example is related to the encoding of code values in ISO 19139. As we can see, the code value is encoded within the "codeListValue" member. Running this example in the JSON-LD playground, we get the N-Quads representation shown in Listing 3.

We can see that the code value is encoded as property value of a nested resource (blank node b1), instead of being the actual value of ex:myCodeProperty, which would be expected for the RDF/OWL encoding that is based on the ISO 19150-2 conversion rule for code lists.

This mismatch can be prevented if the code value was a simple JSON string, see Listing 4, and the resulting N-Quads in Listing 5.

With the code value being a uri encoded as a JSON string which is the same IRI as the individual that identifies the code in the ontological representation, the JSON data would be even easier to map to RDF using JSON-LD - see Listing 6, which results in the same RDF data as shown in Listing 5.

The Features Core Profile and its JSON encoding build on the widely used GeoJSON standard and extends it with minimal extensions to support additional concepts that are important for the wider geospatial community and the OGC API standards, including support for solids, coordinate reference systems, and time intervals. A new Standards Working Group for a standard OGC Features and Geometries JSON has been proposed.

The design of the JSON encoding should be:

Three approaches for translating OCL constraints using SHACL have been investigated in UGAS-2020. None of them supports a full translation of all OCL language constructs that were investigated. It would be useful to analyze the frequency of use of non-supported OCL language constructs and/or the significance/impact of avoiding their use in the NAS. The results would help make a decision of which of the three approaches would be best suited for implementation, in support of encoding the knowledge contained in NAS OCL constraints in SHACL.

rule-owl-cls-encode-basictypes, an OWL conversion rule for basic types developed in OGC Testbed-12, converts basic types - i.e., classes that inherit (directly or indirectly) from a simple type (e.g., CharacterString) - to OWL classes. That means that a basic type value always needs to be encoded as an instance. However, whenever the supertype of a basic type is mapped to an RDFS/OWL datatype, one would expect that a value of this basic type is encoded as a literal (with the according datatype).

The conversion rule should be revised, and the implementation in the ShapeChange ontology target be updated accordingly.

A basic type with a supertype that maps to an RDFS/OWL datatype should be defined as a custom datatype, which restricts the XSD datatype of the RDFS/OWL datatype using an OWL DatatypeRestriction. That restriction defines the restricting facets (defined for the basic type, typically using tagged values), such as xsd:minInclusive.

A custom datatype can be used in the range declaration of an OWL data property. However, a custom datatype cannot be used within an OWL DatatypeRestriction because "datatypes defined by datatype definition axioms support no facets" (source: https://www.w3.org/TR/owl-syntax/#Datatype_Definitions). That means that a basic type A, which is defined in UML as a subtype of another basic type B, cannot be expressed using B as datatype in the OWL DatatypeRestriction. Instead, basic type A needs to be defined as a datatype with an OWL DatatypeRestriction that combines all restricting facets from its direct and indirect supertypes (here: B) and the restrictions declared for basic type A itself.

Example:

With rule-json-all-documentation, descriptive information of application schema elements (packages, classes, properties, and associations) can be encoded via JSON Schema annotations.

Descriptive information of a model element in ShapeChange, i.e., properties (attributes and association roles), classes, and packages, includes the pieces of information, called descriptors, that are documented in Table 1.

Typically, a community has a preferred way to model and encode this information. For example, one community may want to encode the description of a model element via the "description" annotation (which is one of a set of basic meta-data annotations defined in JSON Schema validation, section 9), while another may prefer to encode the values of multiple descriptors of a model element within a single "description" annotation.

ShapeChange can support this type of diversity through JSON Schema annotation elements, which can be defined in the ShapeChange configuration. An annotation element specifies how the content of a specific JSON Schema annotation (that shall be generated while converting a model element) shall be constructed. The annotation element takes into account that a UML model element may not have an actual value for a descriptor, and that some descriptors can have multiple values, e.g., the descriptor example.

In addition to the well-known descriptors (see previous table), additional descriptive information can be incorporated through UML tagged values from the application schema. For example, the "name" tagged value on classes in the NAS could be used to create a JSON Schema "title" annotation.

Different types of annotation elements are available for configuring a ShapeChange JSON Schema target.

The following two tables document the structure of ShapeChange JSON Schema annotation elements. Listing 7 provides examples.

Schema packages have the stereotype <<applicationSchema>>, <<schema>>, or an alias (e.g., using a specific language, like <<anwendungsschema>>). An <<applicationSchema>> package represents an application schema according to ISO 19109. The stereotype <<schema>> has been introduced for packages that should be treated like application schemas, but do not contain feature types.

A UML property of a class is converted to a member of a JSON object - unless the encoding rule defines a different behavior for the type that owns the property (e.g., for enumerations and code lists).

The default result of converting a UML property, therefore, is a key within the "properties" key of the JSON Schema definition for the type that owns the property, with the key name being the name of the UML property, and the value being a JSON Schema with constraints and annotations that define the property (value type, multiplicity, etc).

The following figure and listing provide an example: Figure 11 shows a feature type with a number of properties. Listing 21 illustrates how the UML properties are represented within the "properties" of the JSON Schema that defines that type.

There is no native represention for association classes in JSON or JSON Schema. For schemas that include association classes, a transformation of association classes as defined by GML 3.3 and implemented by the ShapeChange Association Class Mapper should be used.

OCL constraints can be used to enrich a conceptual model with requirements that cannot be expressed in UML alone. A full analysis of options for converting OCL expressions to something with which JSON data can be checked is out-of-scope for UGAS-2020, and therefore future work.

However, a particular type of OCL constraint defined in the NAS has been identified as critical for achieving a useful JSON Schema encoding of the NAS in UGAS-2020: constraints that disallow related entity types. Figure 14 provides an example.

The value type of property place is the abstract type PlaceSpecification. That type is the root of an inheritance hierarchy, which contains four non-abstract classes. With typical UML semantics, the value of place can thus be any non-abstract subtype of PlaceSpecification. In the given example, that would be one of the types PointPositionSpecification, CurvePositionSpecification, SurfacePositionSpecification, and LocationSpecification. Note that further characteristics of these types, e.g., UML properties, have been omitted for brevity.

Diagram notes attached to the feature types FT1 and FT2 indicate that only a subset of non-abstract PlaceSpecification subtypes are actually allowed as value of property place. The according OCL constraints are defined as follows:

In order to realize the value type restriction defined by such an OCL constraint, a model transformation - described in section Transforming OCL Constraints Defining Value Type Restrictions has been added to ShapeChange. In short, the transformation determines which value types are allowed for a UML property of a class (given that a value type restriction is defined for that property), and adds information about the allowed types to the model using a tagged value. That tagged value is used by rule-json-cls-valueTypeOptions (see section Value Type) to encode the value type restriction in JSON Schema.

Listing 25 shows how the value type restrictions for property place in the example used in this section are encoded in JSON Schema, assuming an inline encoding of place to achieve a more simple JSON Schema example.

The following JSON object is valid against the schema for FT2.

The next JSON object is invalid against the schema for FT2, because the @type of the PlaceSpecification object that is the value of the FeaturePlaceRelationship.place property is LocationSpecification - which is allowed for FT1, but not for FT2.

If rule-json-all-notEncoded applies to an element of the application schema, then that element and all its components are not encoded.

The GeoJSON standard requires that all GeoJSON coordinates use urn:ogc:def:crs:OGC::CRS84 as coordinate reference system (CRS), with optional height in meters above or below the WGS 84 reference ellipsoid. Alternative CRSs are not allowed by this standard.

The OGC API - Features - Part 1: Core standard essentially has the same requirement:

A previous version of the GeoJSON standard did allow alternative CRSs, but that option has been removed "because the use of different coordinate reference systems has proven to have interoperability issues" (GeoJSON standard, chapter 4). However, the GeoJSON standard also states that if all involved parties have a prior arrangement, then alternative CRSs can be used.

The OGC API - Features - Part 1: Core standard also does not preclude the use of additional CRSs, but does not specify how to request features in such reference systems. That is the purpose of OGC API - Features - Part 2: Coordinate Reference Systems by Reference, which is currently under development.

To summarize: Coordinates of GeoJSON compliant data as well as spatial data accessed using the OGC API - Features standard must be given in OGC CRS84 (with optional height). That has implications for data publishers and consumers. A major benefit is increased interoperability, because spatial datasets that use the same CRS can easily be merged. If a use case requires other CRSs, then both GeoJSON and the OGC API - Features standards have options to support that. Data publisher and consumer only need to agree on the CRS in which the coordinates of spatial data, that is being exchanged between the two, is given in.

As mentioned in section Inheritance, JSON Schema does not directly support the concept of inheritance. There are ways to represent inheritance in JSON Schema to a certain extent. Generalization can be represented using an "allOf" that includes the schema of a subtype and the schema(s) of its supertype(s). Specialization can be represented as a relatively complex if-then-else construct, with which JSON objects - that encode types from a type hierarchy) can be validated based upon a property value that declares their type.

If a community does not want to apply these solutions for representing inheritance in JSON Schema, but still wants to use inheritance in their concpetual model and derive a JSON Schema encoding from it, then inheritance needs to be transformed on the conceptual level. Generalization (in the sense of Class Generalization and Property Inheritance) would be transformed by copying all properties of a supertype down to direct and indirect subtypes. For each supertype, a union of the non-abstract types in the hierarchy of that supertype (including the supertype itself) would be created, and the value type of each property that is that supertype would be switched to the union. That would allow the encoding of subtypes, instead of the supertype, as property value - and thus support specialization (in the sense of Class Specialization and Property Ranges).

The transformation of inheritance is implemented by the ShapeChange Flattener transformer, in rule-trf-cls-flatten-inheritance. The documentation of the rule provides further details.

Simple JSON formats may not support properties with a maximum multiplicity greater than 1. If the conceptual model contains such properties, they can be transformed to a set of properties, each with maximum multiplicity = 1.

This kind of model transformation is implemented in ShapeChange by rule-trf-prop-flatten-multiplicity of the Flattener transformer.

A community may want to keep their JSON formats simple by not allowing nested objects within a JSON object, or only a bare minimum (e.g., when their JSON shall be GeoJSON compliant). In such a case, nested objects that represent data types and unions from the conceptual model must be avoided. At the same time, the JSON formats used by the community must still be able to represent the information items that would usually be encoded via these complex types.

rule-trf-prop-flatten-types, implemented by the ShapeChange Flattener transformer, "flattens" these complex types by copying their properties to the types that use the complex types. The names of the property copies are modified to reflect which information items they represent.

JSON Schema cannot directly represent association classes. An association class therefore needs to be transformed into a structure that can be represented with JSON Schema. The transformation of association classes defined by GML 3.3 is a suitable solution.

The ShapeChange Association Class Mapper implements the transformation defined by GML 3.3.

In the UGAS-2019 OGC Pilot, the <<propertyMetadata>> stereotype was developed. When assigned to a property, it indicates that the property can be associated with metadata. The metadata would provide additional information on the property value or values. Tagged value metadataType is defined for the stereotype, and used to identify the actual type that the property references as metadata.

The Property Stereotype for Metadata document describes how the stereotype is encoded in XML Schema. Basically, a "metadata" XML attribute is added on the XML element that represent the property. The XML attribute can be used to reference the metadata object, much like an "xlink:href" XML attribute would be used to reference a "normal" object.

Some encodings - like JSON - do not have anything similar to XML attributes. Section 2.3.2 of the Property Stereotype for Metadata document describes how the <<propertyMetadata>> stereotype can be handled in such an encoding. In essence, the stereotype is transformed to an additional property, with the type identified by tagged value metadataType as value type.

The transformation is implemented by the ShapeChange Type Converter transformer in rule-trf-propertyMetadata-stereotype-to-metadata-property.

A UML property that is defined for a feature, object, data, or union type within an application schema, by default cannot have a null value. In order to model that a property can have a null value (instead of actual value(s)), stereotype <<voidable>> must be added to the property, or tagged value nillable with value 'true'. Such a property is called a nillable property.

The recommendation from the UGAS-2019 OGC Pilot for NAS modelling of nillable properties (for further details, see the Property Stereotype for Metadata document, section 2.2) is to use the <<voidable>> stereotype, and to also set tagged value voidReasonType on the property, in order to define the enumeration that defines the reasons for a null value.

In the XML Schema encoding, nillable properties are represented by XML elements for which the XML attribute "nilReason" can be set. As also mentioned in section Transforming Stereotype <<propertyMetadata>>, some encodings - like JSON - do not have anything similar to XML attributes. In order to encode the reason why a nillable property has a null value in such an encoding, the application schema can be transformed, adding a new property for each nillable property (to the class that owns the nillable property), with the new property having the void reason type as value type.

The according transformation is implemented by the ShapeChange Type Converter transformer in rule-trf-nilReason-property-for-nillable-property.

An OCL constraint such as inv: place→forAll(p|not(p.oclIsKindOf(CurvePositionSpecification) or p.oclIsKindOf(SurfacePositionSpecification))), and - for the sake of the example used in this section - name "Value Type Representations Disallowed", restricts the set of allowed value types for a property. In the example, property place must not have a value of type CurvePositionSpecification or SurfacePositionSpecification. The example is described in more detail in section Constraints.

With rule-trf-cls-constraints-valueTypeRestrictionToTV-exclusion - defined for the ShapeChange ConstraintConverter transformation, the value type restrictions defined by OCL constraints can be extracted from the OCL expression, and converted into a tagged value, to be used by subsequent transformation and conversion processes.

Configuration parameter valueTypeRepresentationConstraintRegex is used to identify the relevant OCL constraints. The parameter value contains a regular expression - for example .*Value Type Representations Disallowed.*, which matches the names of OCL constraints that define value type restrictions. The according OCL expressions must thereby be structured as in the example (with oclIsTypeOf(..) also being supported).

The name of the property that is restricted is parsed from the begin of the OCL expression: inv: {propertyName}->forAll…​ The property name may thereby be preceded by self., i.e., inv: self.{propertyName}->forAll…​ is a valid alternative way to structure the value type restricting OCL expression.

Required configuration parameter valueTypeRepresentationTypes specifies the types that are used as value type by the UML properties identified in the value type restricting OCL constraints. For each such type, a list of names of the generally allowed types within the inheritance hierarchy of that type must be provided, which may include the type itself and abstract types. For example, for the value type PlaceSpecification of property place shown in Figure 14, the value of the configuration parameter could be: PlaceSpecification{PointPositionSpecification, CurvePositionSpecification, SurfacePositionSpecification, LocationSpecification}. The transformation will automatically add all subtypes of generally allowed types to the set of generally allowed types. That is important for creating a tagged value that explicitly lists the types that are allowed for a property, regardless of inheritance structures, because the OCL constraint may exclude a specific subtype of a generally allowed supertype.

The transformation will parse a value type restricting OCL constraint in order to determine the (potentially inherited) UML property to which the constraint applies. The OCL expression is structured so that any type mentioned in the expression is disallowed/excluded. The transformation can therefore determine the value types that are disallowed - also taking into account all subtypes of a type that is mentioned within an oclIsKindOf(..). The set of disallowed types will then be subtracted from the set of generally allowed types, resulting in the set of types that are allowed as value types of the property.

The allowed types for the property are documented in the model by adding (also: overwriting, if it already exists) tagged value valueTypeOptions to the class on which the UML property is defined. The tagged value is structured as follows:

{propertyName}(\(associationClassRole\))?={allowedTypeName}(,{allowedTypeName})(;{propertyName}(\(associationClassRole\))?={allowedTypeName}(,{allowedTypeName}))*

For the example OCL constraint, that would result in: place(associationClassRole)=PointPositionSpecification,LocationSpecification.

In order to achieve a GeoJSON compliant encoding using ShapeChange, set "defaultGeoJson" as the default encoding rule for the JSON Schema target (using the target parameter defaultEncodingRule).

This encoding rule consists of the following conversion rules:

Furthermore, the following parameters need to be added to the configuration of the ShapeChange JSON Schema target:

Geometry types used in the conceptual model (e.g., types from ISO 19107) must be mapped to one of the GeoJSON geometry types (see Table 5).

The feature type illustrated in Figure 15 is used as example for a GeoJSON based encoding, which is shown in Listing 26.

This JSON object is valid against the schema from Listing 26:

This JSON object is invalid against the schema from Listing 26 (because the JSON value of "geometry" is not valid according to the JSON Schema of a GeoJSON point):

Some communities have schemas where "geospatial" plays a minor or no role at all. For such cases, the use of GeoJSON features is not relevant. The property nesting and the restrictions of the "type" and "geometry" members defined by the GeoJSON schema could even be a hindrance.

In order to achieve a plain JSON Schema encoding using ShapeChange, set "defaultPlainJson" as the default encoding rule for the JSON Schema target (using the target parameter defaultEncodingRule).

This encoding rule consists of the following conversion rules:

The geometry types used in the conceptual model should be mapped to the JSON Schema implementations defined by the Features Core Profile.

A plain JSON Schema encoding of the feature type that was used as example for the GeoJSON based encoding in the previous section (see Figure 15) is shown in Listing 27.

This JSON object is valid against the schema from Listing 27:

Table 6 provides an overview of the types from the ISO/TC 211 Harmonized Model included in the Features Core Profile.

While the table uses the types from the ISO/TC 211 harmonized model, this is not meant to imply that any valid instance of these types are covered by the profile.

For the purposes of defining a Features Core Profile of spatial types, the representations of all spatial 1d, 2d, and 3d geometric primitives in ISO 19107 and all temporal geometric primitives in ISO 19108 are restricted to the simple representations that are widely supported in software tools and libraries.

The following constraints apply for the spatial geometric primitive types.

These constraints apply to all instances including geometric primitives that are part of a geometric aggregate.

For ISO 19107:2019, any Collection is constrained to be homogenuous, i.e., it is a collection of geometric primitives of the same dimension.

The following constraints apply for the temporal geometric primitive types:

This section lists the types from ISO 19103 that belong to the Features Core Profile and documents their JSON Schema definition. The following sections provide more detail and specify the JSON encoding.

The Features Core Profile includes:

Overview lists these types (for both ISO 19107:2003 and ISO 19107:2019) and documents the constraints on these types.