2.1.  Terms and definitions

2.1.1. application schema

conceptual schema (Clause 2.1.3) for data required by one or more applications

[SOURCE: ISO 19101-1:2014, Clause 4.1.2]

2.1.2. conceptual model

CM ADMITTED

model that defines concepts of a universe of discourse

[SOURCE: ISO 19101-1:2014, Clause 4.1.5]

2.1.3. conceptual schema

formal description of a conceptual model (Clause 2.1.2)

[SOURCE: ISO 19101-1:2014, Clause 4.1.6]

2.1.4. model-driven standard

MDS ADMITTED

standard created using a model-driven architecture (Clause 2.1.5)

2.1.5. model-driven architecture

MDA ADMITTED

software design approach for development of software systems centered around data models

[SOURCE: OMG UML 2.5]

2.1.6. model authoring tool

software used for authoring a conceptual model (Clause 2.1.2)

2.1.7. platform-independent model

PIM ADMITTED

conceptual model (Clause 2.1.2) that does not contain platform-specific concerns

2.1.8. platform-specific model

PSM ADMITTED

data model that contains platform-specific concerns

2.1.9. model transformation

model conversion from one form to another which may not preserve all semantics

2.1.10. model conversion

process that converts a data model in one format into another format that preserves all model semantics

2.1.11. stereotype

extension of an existing UML metaclass that enables the use of platform or domain specific terminology or notation in place of, or in addition to, those used for the extended metaclass

[SOURCE: OMG UML 2.5]

2.1.12. tagged value

attribute on a stereotype used to extend a UML model element

[SOURCE: OMG UML 2.5]

2.1.13. UML profile

predefined set of stereotypes, tagged values, constraints, and notation icons that collectively specialize and tailor UML for a specific domain or process

[SOURCE: ISO/IEC 19501]

2.1.14. metaschema

set of information models that are capable of describing other schemas

2.2.  Abbreviated terms

ADE

(CityGML) Application Domain Extension

API

Application Programming Interface

DDL

(SQL) Data Definition Language

DSL

Domain Specific Language

EAP

Enterprise Architect Project

ER

Engineering Report

GFM

General Feature Model

GIS

Geographic Information System

GML

Geography Markup Language

JSON

JavaScript Object Notation

JSON-LD

JSON for Linked Data

MBA

Model-Based Authoring

MDA

Model-Driven Architecture

MDS

Model-Driven Standard

OCL

Object Constraint Language

OWL

Web Ontology Language

PIM

Platform Independent Model

PSM

Platform Specific Model

RDF

Resource Description Framework

SDO

Standards Development Organization

SKOS

Simple Knowledge Organization System

SQL

Structured Query Language

UML

Unified Modeling Language

XSD

XML Schema

3.1.  Problem statement

In recent years the OGC has seen the emergence of new encoding formats, data models, and service architectures. The result has been a proliferation of standards which should form a coherent body of work. The tools required to achieve and guarantee this coherence have been lacking.

This ER, reporting on tasks D022, D143 and D144, investigates the application of MDA tools and techniques to manage the development and maintenance of a portfolio of related standards.

3.2.  Model-driven architecture and its potential benefits

The model-driven architecture (MDA) paradigm (introduced by the Object Management Group (OMG) in 2001) is a design approach for the development of software systems.

One of the most important goals of MDA is to maintain a single source of truth for a system (a standard in this context). In an MDA approach, there is a single standardized definition (truth) from which all other derived standards and specifications are created (derived truth), potentially with additional contributions (augmented truth) by secondary sources of information (supplementary truth) (Figure 1). This approach promises technical interoperability of a synchronized specification stack between information systems.

3.3.  Types of models and their derivatives

Platform Independent Models (PIM) provide the definition of a data and/or computing capability which is independent of the implementing technology.

Example 1

Platform-Specific Models (PSMs) define how the PIM capability is realized using a specific implementing technology (e.g., an XML Schema (XSD) or a relational database schema (SQL DDL)). Common implementing technologies include: XML Schema, JSON Schema, SQL DDL, and RDF.

The PSM may be derived from a PIM through a transformation taking only the PIM as input, with a deterministic mapping from PIM constructs to PSM constructs. In that case, the PSM can be spoken of as pure. The transformation may be enhanced with mapping guidance specific to the target platform (supplementary truth), in which case the PSM can be spoken of as mixed (Figure 2).

Example 2

The PIM can serve as the source of truth for the documentation describing it, as well as for downstream PSMs. Again, the documentation may be derived truth, expressing only information inherent in the PIM; or it may be augmented truth, incorporating supplementary truth outside the PIM proper — such as additional documentation or guidance (Figure 3). The latter is expected for documentation, since documentation has a tutorial and informative function, and is not just a normative description of the model. If the documentation is expressed as a standard, supplementary truth such as term definitions and bibliographic information is required in the document format. Documentation expressed as a standard is expected to have normative effect; the pure model derived from a PIM or PSM may not contain enough guidance or clarifications to have normative effect, and may accordingly be treated only as informative (Figure 4).

A derived truth (e.g. a PSM) can also be used as a source of truth to generate further derived truths (e.g. a more specific PSM). Therefore the “platform” named here can be a floating frame of reference.

Example 3

3.4.  MDA as applied in OGC

The OGC Innovation Program has employed model transformations in various guises as far back as the Critical Infrastructure Protection Initiative (CIPI) in 2002. In particular, the open-source tool ShapeChange has been employed in many OGC Testbed activities starting with Testbed-2 (OGC 04-100).

In the OGC, MDA approach, two types of models are defined to distinguish the cases of a source of truth against derived truths: PIM and PSM.

In OGC PIMs are referred to as “Conceptual Models”. In ISO/TC 211 PIMs are referred to as “Conceptual Schemas”. In this Engineering Report (ER) we follow the OGC terminology except in contexts in which ISO 19100-series content is being referenced.

In OGC, PSM-based standards are often referred to as “Implementation Specifications”.

Table 1 — Mapping of terminology for MDA and formats typically used in OGC contexts

3.5.  Challenges in developing OGC standards

While OGC has long utilized MDA for standards development, there is a recognition that gaps exist between the development of data models and the publication of those data models.

Challenges encountered include the following:

1. PIM documentation. A PIM model is often an abstract representation of requirements which require extensive documentation and guidance on the meaning of various components. Such documentation text is often managed outside of the model itself (as supplementary truth), due to tool limitations.

   NOTE 1  PIM documentation is typically published in OGC Conceptual Model standards.

2. Generation of the PSM. The PIM and PSMs may be managed by separate or independent groups. This synchronicity issue between the PIM and its derived PSMs negatively affects interoperability between information systems.

   NOTE 2  PSMs are published as artifacts of OGC Implementation Specifications.

   Example

   An XML encoding (PSM) generated from version 1.0 of the conceptual model (PIM) will be out-of-sync when the conceptual model has advanced to version 1.1.

3. PSM documentation and guidance. The documentation of PIM and that of its PSMs are often managed separately. This leads to misaligned documentation and practices between the PIM and PSMs. The issue is further exacerbated as PSM documentation is meant to contain additional details specific for a platform, which by definition cannot be derived from the PIM directly.

   NOTE 3  PSM documentation is typically published in OGC Implementation Specifications.

4. Different types of deliverable outputs. For example, documentation is meant for human consumption but XML schemas are meant for machine consumption. Yet both of these deliverables may originate wholly or in part from the same model.

This ER reports on the success of addressing the first two challenges, and partially on the third.

These challenges are typically dealt with using one or more of the following strategies:

• Role segregation. For instance, adding control bodies to control and synchronize the flow of information from the PIM to downstream deliverables.

• Additional manual resources. Apply additional manual steps and corresponding resources in order to synchronize deliverables, such as in the generation of model-derived artifacts, synchronization of texts, version checking.

These challenges indicate that the following questions need to be resolved when developing a standard:

1. What is my model specification technology? Is more than one technology being used?

2. Where are the models and their documentation kept?

3. What model artifacts need to be generated?

4. What compromises can be made with regard to adhering to the MDA paradigm?

3.6.  Objective: deterministic generation of PIM-derived artifacts

In this ER we report on the following objectives:

1. Identify and evaluate MDA tools potentially suitable for the generation of PIM-derived artifacts with geospatial standards, and document any gaps not satisfied by these tools.

2. Document capabilities and limits of each identified tool and provide recommendations on the context of OGC usage (don’t use, adopt or extend).

   • Develop prototypes which explore solutions to identified gaps.

3. Document best practices for representing an OGC PIM from experience gained from development of the prototypes. These best practices will provide guidance to the developers of OGC Conceptual Model Standards so that those models can be used to generate valid OGC Implementation Standards using MDA tools.

3.7.  Applying MDA in the authoring of OGC Standards

OGC currently publishes several types of standards that primarily involve information models, including:

• conceptual models (OGC conceptual model standards)

  Example 1

  A standard with conceptual models in the UML (XMI) format.

• encodings (OGC encoding and implementation standards)

  Example 2

  An encoding standard with XML schemas in XSD format, APIs in OpenAPI YAML format.

• ModSpec models (all OGC Standards)

  Example 3

  All OGC Standards utilize ModSpec models for the representation of requirements and conformance tests.

An OGC Standard can be complex in structure when describing complex domains. Inherently, an OGC Standard is composed of potentially 11 different types of models, which vary as to whether they are intended primarily for machine consumption, human consumption, or both (Figure 5).

In order to best facilitate the creation and development of such a complex deliverable, the application of an automated, MDA-backed, generation process is desirable.

Although MDA is typically performed for software systems for the transformation of models, such as from an abstract model to an implementation model, for the testbed activity the MDA approach has been applied further to the development and publication of OGC Standards.

The application of MDA to authoring is described as “model-based authoring” (MBA), which produces a “model-driven standard” (MDS).

There are additional benefits that can be achieved:

• Providing different content to different audiences of a standard, such as:

  • Rendering human-readable standard content intended for human consumption.

  • Producing machine-readable data intended for machine reusability.

• Integration of model documentation, e.g. integrating model annotations and separate associated documentation into a single deliverable.

• Deterministic automated processing of the generation of PIM-downstream deliverables, including PIM standard documentation, PSMs and their documentation, as well as other machine-readable resources.

3.8.  Achieving model-based authoring and model-based standards

Model-based standards are not a new concept. Previous OGC Standards, such as CityGML 2.0 (OGC 12-019) can be considered model-based:

• The standard contains the CityGML 2.0 model

• The standard contains content derived from the CityGML 2.0 model

The process, however, involved multiple manual steps (Figure 6), switching between tools and copy-pasting, which makes it inefficient and labor-intensive. Given that the standards development process is iterative in nature, the effort needed to keep information synchronized to publish the standard is often overwhelming.

One of the great things about model-based authoring is the potential to fully automate the process, without needing to resort to iterative and error-prone copy-pasting (Figure 7).

In order to create a model-based standard in an automated fashion, we recognize that the only way to do so is to treat all components of the standard as models.

As it turns out, text within a standard is inherently organized according to one or more information models. There exists various representations of rich-text models, including Microsoft OOXML (ISO/IEC 29500 (all parts)), OpenOffice OpenDocument (ISO/IEC 26300), as well as the Metanorma StanDoc model (ISO/AWI 36100).

Given that model transformations can be specified as defined, deterministic processes, a process can be compiled to generate a model-based standard with full automation, transforming the following inputs to outputs:

• Inputs:

  • Models to be specified

  • Text as models

• Output:

  • A model-based standard

If we treat all information that is contained in a standard as models, all that is necessary to automate the model-based authoring is to determine the model transformations from the input into a transformed set of models, and then include those transformed models into the standard (Figure 8).

Ultimately, there are multiple conceptual levels of models (Figure 9), expressing different levels of abstraction and interrelation between entities, and any of these can be incorporated or used inside a model-based standard.

3.9.  Benefits of automated generation of PIM downstream artifacts

There are multiple benefits by having a single-step workflow that automatically generates PIM downstream artifacts.

• Enables modern software development practices, such as:

  • Integration with change management systems (like Git) that allow distributed development

  • Usage of automated tests that ensure correctness of downstream artifacts

• Facilitates modern DevOps practices, including:

  • ability to automatically generate and distribute PIM downstream artifacts on individual changes, which can be combined with tests to ensure correctness of generated output

• Provides confidence in the correctness of PIM-derived artifacts due to them being synchronized with the input PIM.

• Reduction in the human effort necessary in validating the correctness of PIM downstream artifacts.

Ultimately, this approach “lets the computer do what a computer does best” — by elevating human effort to validate the generation process of PIM-derived artifacts instead of the validation of the artifacts themselves.

3.10.  Previous Work

3.11.  Developed PIM-derivation methodology and prototypes

In this work item the following PIM-to-PSM transformation prototypes were developed using MDA and MBA technologies.

In particular, the D144 task (Clause 10) explored the space of MDA PIM-to-PSM transformations based on two recent OGC Standards that were accompanied by formal UML-based conceptual models:

• OGC 20-010 (dated 2021-09-13)

• ISO 19170-1:2021 (dated 2021-05-11)

Table 2 — D144 PIM-to-PSM transformation prototypes and links

Four target PSM environments were explored:

• Metanorma AsciiDoc (Metanorma)

• XML Schema (W3C TR xmlschema-1)

• JSON Schema (JSON Schema)

• Resource Description Framework (W3C RDF) extended by:

  • Web Ontology Language (W3C OWL), and

  • Simple Knowledge Organization System (SKOS: W3C TR skos-reference)

3.12.  Semantic Web PIM-derivation methodology

The D143 task (Clause 9) explored using Semantic Web ontologies, rather than UML, as the underlying model for a PIM (W3C RDF, W3C OWL, W3C TR skos-reference). It explored how extant ontologies and vocabularies, including document ontologies, could be used to generate an MDS at the PIM level. The task did not provide an implemented prototype.

4.1.  General

This section provides key findings from the prototypes developed.

It is determined that an MDA approach, possibly an organizational-wide one, would streamline the downstream creation of MDSes and PSMs, and greatly benefit all stakeholders of the model-driven process — authors of information models, standards, and the users of those models and standards.

Specifically, the usage of a single source of truth across these deliverables will guarantee a certain consistency in the deliverables, and also provide upstream feedback to conceptual model authors on potential impact of seemingly inconsequential changes.

In general, the MDA approach makes any inconsistencies, omissions, or under-specifications in underlying information models much more visible, since they impact the MDA workflow directly.

This report recommends the enactment of best practices, requirements and policies for wider adoption of MDA in OGC.

As the task of generating Model-Driven Standards (MDS) covering both PIM and PSMs is extensive by itself, the reporting for derivation of MDS from each of PIM in scope for PSMs in OGC are reported on separately.

This report is specific to considerations around PIM-driven MDS and PIM-driven PSM, where a UML model is used as the PIM.

The use of each of XML Schemas, JSON Schemas, and RDF as PSMs for PSM-Driven Standards is considered in separate forthcoming reports (Figure 10).

4.2.  Recommended MDA tools

Metanorma and ShapeChange were determined to be the best readily-available open-source tools to address the task objectives of generating MDA documents and PSMs, respectively. When used together, they form a full MDA toolchain for incorporating UML (from Sparx Systems Enterprise Architect) for OGC deliverables.

Metanorma has been demonstrated to support AsciiDoc as the input documentation format and specification of certain information models such as ModSpec. It has been successfully integrated into OGC workflows and is also used by ISO/TC 211 standards developers for creating model-based standards. Metanorma depends on Ribose LutaML, a data model accessor that supports multiple data model types, to navigate data models within the Metanorma structure.

ShapeChange has been employed by OGC and ISO/TC 211 standards developers. It has been repeatedly demonstrated to successfully employ ISO/TC 211 Harmonized Model Maintenance Group (HMMG) conceptual schemas as input. ShapeChange support generation of PSMs as XML Schema, JSON Schema, and RDF outputs (among others).

4.3.  Prototype capabilities

4.4.  Criteria for adopting MDA

The following criteria are deemed necessary in using a model-driven architecture:

1. The authoritative information model must be fully and accurately specified with regard to details that appear in the output model-driven standard.

2. The authoritative information model must be exportable to a format useable by the MDA tools. For instance, XMI output from most UML tools utilizes a proprietary structure and requires MDA tools to provide vendor-specific support.

3. Supplementary information to the information model, such as additional information models, guidance information for MDS output, or platform-specific configuration for PSM output, must be available in a form useable by the MDA tools.

A model-driven architecture approach to creation of MDS and PSMs should only be adopted if the above criteria are met.

4.5.  Considerations for generating MDS

There are three approaches to developing model-driven standards directly from an information model.

• Automatic inclusion. This is the recommended approach that requires minimal intervention of the MDS author in the generation of the MDS from the information model. In this approach, the model content order is inherited from the model authoring tool and fully reflected as shown in the table of contents in the MDS.

• Manual inclusion. This is an advanced approach, where the MDS author wishes to manually specify content from the information model to include in the MDS.

• Hybrid inclusion. This is an advanced approach that blends automatic and manual inclusion. In this approach, the MDS author specifies portions to include information model content automatically, while being able to manually insert particular content within the automatically generated MDS hierarchy. This approach also allows for tailoring of the order of content as generated in the MDS.

The choice of approaches depends on the difference in organization between the information model and the desired MDS structure.

In this Testbed task:

• The CityGML MDS prototype (Clause 10.4) generally adopts the “automatic inclusion” approach

• The DGGS MDS prototype (Clause 10.5) adopts the “hybrid inclusion” approach.

4.6.  Cross-referencing functionality needs in PIM-MDS interactions

4.7.  Basic and expert features required for MDS generation tool

An extensive set of functionality in the MDS generation tool is required to support direct generation of an MDS.

These functionalities can be categorized into “basic” and “expert” needs:

Basic features include:

• Machine-readable information models. The ability to encode machine-readable requirements, ModSpec models and other encodings.

• Ability to distinguish from information models the in-scope and out-of-scope objects. Treatment of classes described in document (in-scope) vs classes not described in document (out-of-scope) (e.g. skipping, alternative references, external references).

• Ability to transform standardized and proprietary formats generated by the model authoring tool into formats desired in the MDS deliverable output.

  Example 1

  When using Sparx Systems Enterprise Architect for UML diagramming, diagrams have to be exported from Sparx Systems Enterprise Architect. However, Sparx Systems Enterprise Architect is unable to generate platform-independent vector graphics (W3C SVG), but only Microsoft EMF (EA-EMF is also incompatible with standard EMF). As OGC requires vector graphics to be rendered in platform-independent formats for HTML, PDF and Word outputs, the MDS tool must handle conversions from EMF to SVG.

Expert features include:

• Ability to configure presentation styles of classes. For users of the “automatic inclusion” approach, an OGC-predefined display template is used to transform a UML model in into textual elements (e.g., a UML class uses a display template for showing a UML class in textual elements). An expert MDS author may want to customize how a UML class is represented.

  Example 2

  In the CityGML 3.0 standard, Clause 7 and Clause 8 use different presentational structures on the same set of UML models: Clause 7 uses the data_dictionary template, while Clause 8 uses the entity_list template.

• Ability to filter and order UML packages and classes. For users of the “automatic inclusion” approach, the content order of UML packages and UML classes is inherited from the input information model. An expert MDS author may want to use a different order in the MDS from that of the original information model due to other considerations.

  Example 3

  In the CityGML 3.0 standard, the content order in the MDS differs from that of the CityGML conceptual model in order to match and align the clause numbers with the CityGML 2.0 standard to allow comparisons between two standards.

• Ability to insert document elements before and after each UML package / class presentation. In OGC conceptual models, ModSpec requirements and conformance tests are generally defined outside of the conceptual model itself. When using the automatic inclusion approach, an expert MDS may want to place ModSpec requirements and conformance tests right after the description of a particular package or class.

  Example 4

  In the OGC DGGS standard, ModSpec requirements and conformance tests are encoded in the Metanorma ModSpec format. These ModSpec models are inserted into the “automatic inclusion” process through conditional insertion procedures provided by Metanorma’s LutaML plugin.

• Ability to distinguish model elements that exist within the current PIM or are external to the current PIM. A UML conceptual model may refer to externally-defined UML packages and models that do not exist within the currently loaded package. The MDS tool must distinguish whether a referenced model contains such reference, and create that cross-reference accordingly. There are two possibilities:

  • A referenced model is not available in the current package. The cross-reference will have to be made to either the specification of the referenced model, to an alternative provided by the user, or omitted completely.

  • A referenced model is within the current package but is not documented in the MDS, intentionally or not. In this case the cross-reference can only be made if the referenced model exist in the MDS, or if an alternative link was provided by the user.

  Example 5

  In the CityGML 3.0 conceptual model, there are multiple ISO-related UML classes referenced within the models but the classes are actually located outside of the CityGML 3.0 conceptual model. These external models instead are represented within the MDS as terminology entries in the Glossary, and hence cross-references need to be made from the PIM-generated document elements to those Glossary entries where appropriate.

• Ability to provide a dynamic context for programmatic document elements. In the MDS authoring environment, an expert MDS author may want to provide a template for generating document elements to be inserted right after the description of every UML package, but the content generated is context-dependent.

  Example 6

  In the OGC CityGML 3.0 standard, every Clause 8 subsection represents a UML package. At the end of each of these subsections, a section is inserted to provide a link to that particular package’s documentation in the OGC CityGML 3.0 User Guide. This link depends on the package name of the UML package. With Metanorma providing the dynamic context through the Liquid template language, it is possible to encode this insertion with a single block instead of one block per subsection.

The need for such functionalities is discussed further in Clause 7.2, Clause 10.4 and Clause 10.6.

4.8.  PIM-to-PSM transformations rely on supplementary truths

With the CityGML 3.0 conceptual model, the developed prototypes documented in Clause 10.7 and Clause 10.8 demonstrated that the generation of PSMs from PIMs are both feasible and practical.

However, the following considerations must be taken into account:

• PIM-to-PSM transformations are, at their core, model conversions. Different information modelling languages present different semantics, and the source semantics may not be fully expressible in the target modelling language. On the other hand, a semantically lossless representation in the target modelling language may be too convoluted to be useable in the target use case.

  Example 1

  UML is not trivially converted into W3C RDF given the different contextual assumptions of those languages. A full UML representation in RDF requires an implementation of UML metamodels in W3C RDF, of which the result would not be useable in traditional RDF scenarios.

• There are multiple methodologies for converting a PIM to PSM, and there is not necessarily an “absolutely correct” methodology. The choice of methodology will likely depend on the target usage case that dictates the usage of the target information modelling language. An organization-wide approach, for consistency reasons, should take into account what conversion methodology should be allowed.

• Programmatic guidance for the PSM-generation process, as specific to a PSM, is necessary. These are considered “supplementary truths” necessary for creation of the PSMs. There are two places where such conversion guidance (or “hints”) can be located:

  • Within the conceptual model

    Example 2

    In the DGGS conceptual model, XML schema generation hints are provided within the UML models.

  • In configuration input for the PIM-to-PSM generation tool

    Example 3

    In the case of the CityGML 3.0, the XML schema generation configuration is placed external to the conceptual model as a separate ShapeChange configuration file.

The management of this PSM-specific information and configuration should be considered part of any MDA approach.

4.9.  Considerations when using UML models as PIM

The goal of using MDA is to derive output without relying on additional sources if the necessary information already exists in the authoritative model.

The following findings have been made with regards to PIM-to-MDS and PIM-to-PSM transformations:

1. UML models exported into XMI from one model authoring tool are typically not interoperable with another tool unless vendor-specific support is implemented. The MDS tool must provide vendor-specific support for the model authoring tool used.

   • While the machine-readable form of UML is specified in the XMI standard (OMG XMI 2.5), the XMI profiles of nearly every UML authoring tool differs — only the most basic core UML models are interoperable. Only some UML authoring tools implement compatibility features to support the import and export of UML XMI files in order to support XMIs from different vendors.

   • Both conceptual models used in this Testbed activity, CityGML and DGGS, are authored in the Sparx Systems Enterprise Architect EAP format. A machine-readable UML export file from Sparx Systems Enterprise Architect, in form of XMI v2.5, consists of two separate XML portions. The first portion is the XMI-standard conforming portion, which allows for interoperation between tools. However, this portion omits critical information of UML models needed for documentation, such as the description of models, stereotypes, and diagrams. The second portion is proprietary XML content, which provides most necessary information supported by the Sparx Systems Enterprise Architect GUI for the documentation of UML models.

   • In the MDS prototypes, the LutaML-XMI plugin had to be extended to support Sparx Systems Enterprise Architect specific XMI parsing in order to retrieve the necessary information for the documentation of the CityGML and DGGS conceptual models.

2. The authoritative model must be fully specified for an MDS approach. To enable automated tools to utilize information from a model, the model must provide its information in a machine-interpretable manner and allow distinction between specific types of information. In a PIM-generated MDS or PIM, any under-specification or aberration in specification practice will cause unintended failures downstream. It is therefore important to only standardize a conceptual model after its MDS is generated.

   • To support PIM-to-PSM XML Schema transformation, the CityGML 3.0 Conceptual Model (OGC CityGML 3.0 Conceptual Model) was developed in conjunction with software modifications to a non-current ShapeChange baseline, in order to treat CityGML-specific “core” «BasicType» DoubleBetween0and1List and DoubleList generalization classes on a special-case basis.

     To remove this dependency, the current ShapeChange software baseline was extended with one new XML Schema-related rule (rule-xsd-cls-basictype-list), and the CityGML 3.0 Conceptual Model revised accordingly. This rule is independent of the CityGML 3.0 Conceptual Model, addressing the more general topic of the modeling of lists of basic types in Application Schemas for use in developing a corresponding XML Schema-based PSM.

     NOTE  If the CityGML Standards Working Group (SWG) chooses to adopt these minor enhancements to the CityGML 3.0 Conceptual Model and XSD-based encoding then CityGML Application Domain Extension (ADE) developers will be able to use the ShapeChange capability to generate their community-specific XSD-based encodings.

   • The DGGS conceptual model was used without revision for PIM-to-MDS generation.

3. Data elements within a model that have to be documented in the MDS must be specified in a standardized manner and in the correct format. There are potentially multiple ways of achieving similar results with a UML tool like Sparx Systems Enterprise Architect, especially when model authors focus on the diagramming (drawing) functionality and are unaware of best practices on how and where to specify information.

   • The DGGS conceptual model utilized practices that were problematic in information extraction due to the lack of support of those model elements in the modelling language or the model authoring tool.

     • Sparx Systems Enterprise Architect does not allow specifying “inactive” or “outdated” elements inside a an Sparx Systems Enterprise Architect project file (it does allow for specifying “draft status”). In the DGGS conceptual model, there were several types of “inactive” elements that are not supposed to be included in the MDS, including:

       1. Spare model elements that were stowed for reference purposes. These were kept in a UML package called “Spare”.

       2. Outdated model elements in various UML packages for reference purposes. These packages, classes, interfaces had names prefixed with the phrase “old:”.

       3. Non-normative diagrams for reference purposes. These diagrams are prefixed with the phrase “fyi:”.

     • OMG UML XMI does not provide a mechanism for specifying the “dimension” of a UML operation. The DGGS conceptual model relied on differentiating the “dimension values” of UML operations encoded in the “Notes” field, but this information is clearly not machine-readable. (https://github.com/metanorma/ogc-dggs-xmi/issues/21)

     • The DGGS conceptual model also depended heavily on OCL, but Sparx Systems Enterprise Architect does not support validation of OCL. In the conceptual model, there are OCL entries that used idiosyncratic identifiers and content that are invalid in OCL grammar.

       Example 1

       In the DGGS conceptual model, the usage of <‌<query>> (1D), to indicate that the data type of a relative position should be one-dimensional, conflicts with <‌<query>> that is supposed to mean a two-dimensional relative position. It also used a parenthetical qualifier to restrict the type of the UML attribute.

4. Naming of diagrams within the model authoring tool should be consistent.

   • The DGGS conceptual model utilized a prefix of “Fig:” for the names of all diagrams encoded in the UML packages. In the MDS, such prefixes have to be removed as they would pollute the actual name when represented in a figure.

5. Naming of UML packages within the information model should be easily referable and unique.

   • In the DGGS conceptual model, most UML packages utilize long names that include spaces and punctuation characters, such as “Common Spatio-Temporal Classes”. While these names prioritizes human-readablity, they present a challenge to machine-referencing.

     The useability challenge of these long names is compounded when accompanied by a hierarchical UML package structure. When using UML models with MDA, the models need to be referred to via fully qualified names given the possibility of conflicting model names across UML packages. These fully qualified references are not only cumbersome for MDS and PSM authors, but are also uncomfortably long for any human audience.

     Example 2

     In the DGGS conceptual model, a unique reference to a particular UML class can look like “Common Spatio-Temporal Classes > Temporal and Zonal Geometry > Temporal Geometry and Topology > EdgeT”,

   • While model authoring tools such as Sparx Systems Enterprise Architect provides a unique reference per model element and diagram, these unique IDs are long and very difficult to reuse without automated help from the MDS tool, e.g. the CityObjectGroup diagram in the CityGML 3.0 model has the EA GUID of {CCE69980-0DDD-4975-9104-054B018BAA96}.

Generally, as demonstrated by the issues under Clause 8.2, it is essential that the information model being used as input for MDA rigorously follows the model specification that MDA tools expect to see.

Lax usage of UML, while may only have minimal consequences so long as the UML only output diagrams or OGC-tailored PSM conversions, will frustrate MDA tools that are aligned with standard representations of UML.

The stakes are higher in MDA, and the processes far less forgiving of eccentricities, such as non-standard multiplicity notation (Clause 8.2.3), ad hoc usage of novel stereotypes (Clause 8.2.7), under-specified modelling of schema reuse (Clause 8.2.8), and so on.

Standards and requirements on PIM information models need to be set in order to align expectations amongst the three stakeholders in MDA usage:

• model authors

• model authoring tools

• MDA tools

4.10.  Level of specification of input models (PIM and others)

As information models are being called upon in MDA to generate complete documentation, any past under-specification or omission of model components for expediency will be correspondingly reflected in the output.

Example 1

Example 2

Various strategies can be used to remedy insufficient specification:

• Merge multiple pre-existing models together, or use those models separately, for a single MDS. The MDS could iterate through multiple source information models, if they cannot conveniently be merged into a single source of truth.

• Treat extraneous information models as external bibliographical references, without resolving them in the MDS. However, any external models in a PIM still need to be resolved when generating a PSM, as inclusions.

• Omit problematic objects from the PIM in the MDS.

4.11.  Improvements required in ModSpec for specification as PIM

OGC ModSpec (Clause 5.4) provides a set of information models for defining requirements and their conformance tests, and its usage is mandatory within OGC Standards.

ModSpec was originally designed to apply to UML and UML diagrams. In this Testbed activity, it is used as a PIM specification mechanism, which is then transformed into a PSM. Specifically, a ModSpec model instance is specified in the Metanorma ModSpec language (the PIM), which is then transformed into a Metanorma Requirement model in XML (the PSM).

A number of issues were discovered in the rigorous usage of ModSpec in the PIM-to-MDS prototypes (Clause 10.4 and Clause 10.6), that require additional specification and clarification in the ModSpec specification.

These issues are documented in detail at Annex D and summarized below:

• Clarification between the meaning of Conformance Test Step and Conformance Test Part, and the relationships between them. (Annex D.1)

• Clarification and specification of Conformance Tests and Test Steps that apply under a certain condition. (Annex D.2)

• Review and update OGC-wide guidance on usage of ModSpec terminology in OGC documents. (Annex D.3)

• Review and update the OGC ModSpec specification to address inconsistencies in its UML diagrams, UML model definitions and textual descriptions. (Annex D.4)

4.12.  Administrative controls needed for adopting MDA organization-wide

If the MDA approach is applied organization-wide, administrative controls should be implemented (policies and procedures) to streamline development of PIM-generated output, namely the MDS and PSMs.

Mandatory practices (best practices for MDA) should be established and documented that covers the following MDA activities:

• PIM model requirements. Specifically, requirements for a UML model being used as a PIM model. This covers the correctness, accuracy and level of specificity of the UML model when used as a PIM.

• PIM to MDS specification best practices. When using a PIM to generate MDS, it is important to have all information intended in the MDS available in the PIM. In addition, since the MDS contains detailed specifications of the PIM, the PIM must make available its information in correctly specified semantics.

• PIM to PSM specification best practices. The generation of PSMs depend on the general health of both the PIM and PSM-generation configuration or guidance. An incorrectly-specified (or under-specified) PIM or an incorrectly configured PIM-to-PSM process will not generate the desired PSM results.

• PIM to PSM to MDS best practices. This topic will be addressed in forthcoming reports (Figure 10). Simply put, the transformation to PIM to PSM to MDS involves both passing through truths generated from the PIM-to-PSM steps to the PIM-to-MDS step (where the PIM is the PSM output of the former step).

4.13.  Sequence of content in MDS

In this Testbed activity, both PIMs (CityGML 3.0, DGGS) are implemented with a hierarchy of UML packages.

The information in the source information model may be presented in different sequences in the MDS according to external requirements. The sequence of content impacts how the integration of data from the model will be done, and needs to be planned for.

Take UML, as it was used in this Testbed activity, as an example. UML allows for the creation of package hierarchies, where a UML package can have sub-packages, and so on. This allows for a compartmentalized approach that promotes separation of concerns, potentially preventing confusion in its audience if the models were numerous.

In UML, UML objects within a UML package can be given a particular “sorting order”. Similarly, UML packages themselves, being UML objects, also belong to the same sorting order. The sorting order may or may not be alphabetic.

An MDS document, being a document, naturally provides a sequential sequence of content. When transforming a PIM into an MDS, the author must consider whether the UML object sorting order and the UML package hierarchy are to be reflected in the generated MDS.

It may therefore be necessary to indicate the ordering of model objects in the MDS through a declaration overriding the ordering of objects within the model; the ordering is specific to the target document, and not to the model.

The decision on whether to adopt the UML object sorting order and package hierarchy may be based on the following considerations:

• Backwards compatibility to a previous edition of the standard. If there is a previous edition of the MDS, an author may wish to retain clause numbering to match the previous edition, and have new UML elements appear after the last clause (or subclause) of the previous edition.

  Example 1

  The CityGML 3.0 MDS opted to use a “hybrid inclusion” approach with a fixed content sequence in order to retain clause numbering of the previous edition (CityGML 2.0 standard). Description of new model elements were appended after the last subclauses of the previous edition.

• Conventions. In some OGC conceptual model standards, a convention is used for describing a UML package that first provides overview diagrams of the involved models, then tables and text that describe the details of those models. Each detailed section of models starts with the corresponding ModSpec requirement instance.

  Example 2

  The DGGS MDS uses the “automatic inclusion” approach, which implements a default order of first showing information of the UML package, then the diagrams it contains, then UML classes, then UML relationships.

• Specific ordering needs. For a PIM based on UML, for example, classes may be presented aggregated by package, by diagram, or by model, and they may be sorted alphabetically or through dependency ordering.

• Hierarchy presentation or flattening. UML packages can be nested multiple levels, and having a deeply nested document hierarchy makes the standard hard to read, and there is a possibility of running into governance issues (ISO only allows a maximum of 5 clause levels). An author may wish to free the document clause hierarchy from the UML package hierarchy.

In the prototypes (Clause 10.4, Clause 10.5), the following approaches were used:

• In the DGGS prototype, the UML classes of the DGGS were presented in the same order as they were expressed in the source PIM, so the LutaML integration merely iterated through the UML classes in a single loop.

• In the case of CityGML, the UML classes were presented in two clauses, one providing an overview of the models (20-010, Clause 7 “CityGML UML Model”), and one providing attribute detail (20-010, Clause 8 “CityGML Data Dictionary”)

  • This meant that the UML classes were iterated through in two separate loops, each extracting and presenting a different level of detail.

  • The order of presentation of the CityGML UML classes was also different from that in the PIM, with the classes already present in the previous version of CityGML presented first.

The differences in how the two documents presented their information may be summarized in Table 3.

Table 3 — Comparison of LutaML approaches between CityGML and DGGS

4.14.  Challenges with coordinating derived and supplementary truth

4.15.  Tool experience and limitations

In the development of prototypes for the PIM-to-MDS and PIM-to-PSM activities where the PIM is a UML model, multiple compatibility gaps were discovered in the usage of selected tools for the MDA approach.

While all compatibility gaps have been closed as a consequence of this Testbed activity, mainly through the efforts of the Metanorma and to some extent the ShapeChange development teams, certain gaps that arise due to limitations of tool choices remain to be resolved.

Sparx Systems Enterprise Architect while being a popular tool for authoring UML models, provides generally a large amount of freedom to the model author to create UML models that are not conducive to the machine-interpretation functionality needed for a successful MDS approach:

• EA provides a rich-text content area for annotations and notes for UML models and diagrams. However, this rich-text content area uses an outdated format (RTF) and is entirely independent from other UML models defined in the same model package. This means that content within a note in a UML model is unable to specify cross-references to another UML model in the same EA project.

• EA allows entering OCL, which is commonly used with UML models, in specifying interfaces and machine logic. EA however does not implement any validation of OCL, which means that a downstream application using EA output can encounter erroneous OCL.

• EA provides export capability for its diagrams. Typically, UML diagrams are best rendered in vector formats since they contain heavy use of shapes. However, EA can only export in the outdated, obsolete and proprietary Microsoft EMF format, which cannot be used in applications outside Microsoft Windows, as described in Clause 10.4.3. The EA implementation of EMF is even worse — it does not even conform to the Microsoft EMF specification — a correct implementation of EMF will display some objects in the EMF in a vertically flipped manner.

• EA itself is not a cross-platform application. EA only works on Microsoft Windows. Moreover, EA itself is still currently a 32-bit Windows application despite 64-bit Windows being available as mainstay for years (EA Release 16, which is 64-bit, is in Beta as of January 2022). In OGC, many users utilize macOS and Linux systems, and in order to use EA they are forced to install the free and open source Wine software product, or the commercial flavor of CrossOver (the latter requiring an annual subscription). Note that EA has been proven to work on Ubuntu 20.04 LTS through version 7.0 of Wine.

• EA itself is not suitable for usage in cloud systems, continuous integration and automatic generation of downstream model artifacts due to licensing limitations and the delivery model as a Windows application.

4.16.  Suitability for cloud deployment, automated CI/CD workflows

The software engineering world has gradually adopted open-source software due to the ease and possibility of integrating those tools in cloud systems and the ability of those tools to be incorporated on continuous integration and continuous delivery workflows which are typically run on cloud systems.

Given that both Metanorma and ShapeChange are open-source applications, both tools can easily be incorporated into continuous cloud workflows as demonstrated in the prototypes.

• In the case of PIM-to-MDS prototypes, the only manual step is the generation of the XMI export from EA for Metanorma consumption. Metanorma uses LutaML which directly parses the EA-proprietary profile of the XMI standard of the Object Management Group (OMG).

• In the case of PIM-to-PSM prototypes, the only manual step is the copying of the EA JAR file from EA to ShapeChange, in order to allow ShapeChange to access the EA-proprietary project (EAP) format.

The limitation of these manual steps presented by EA prevents the PIM being cloud-managed and used in dynamic generation of MDSes and PSMs.

Given that the choice of model authoring tool may be constrained, the non-standard formats used by those tools will force additional labor in establishing workflows, and need to be considered as part of tool evaluation when pursuing MDA.

4.17.  Future work

5.1.  General

Models are specified according to potentially one or more different technologies.

5.2.  Unified Modeling Language (UML)

5.2.3.  Application to geospatial standards (ISO 19100-series UML Profile)

5.2.3.1.  ISO 19103:2015 Geographic information — Conceptual schema language

ISO 19103:2015 provides rules and guidelines for the use of a conceptual schema language to model geographic information, and specifies a profile of UML.

That profile includes six stereotypes:

• «Interface» (formerly «Type») is an abstract classifier with operations, attributes and associations, which can only inherit from or be inherited by other interfaces (or types).

• «DataType» is a set of properties that lack identity (independent existence and the possibility of side effects). A data type is a classifier with no operations, whose primary purpose is to hold information.

• «Union» is a type consisting of one and only one of several alternative datatypes (listed as member attributes); this is similar to a discriminated union in many programming languages.

• «Enumeration» is a fixed list of valid identifiers of named literal values. Attributes whose range type is an enumeration may only take values from the fixed list.

• «CodeList» is a flexible enumeration that uses string values for expressing a list of potential values. The allowed values are often held and managed using an online register.

• «Leaf» is a package that contains only classes (packages are disallowed).

The names of stereotypes are not case-sensitive. Stereotypes are essential in the derivation of PSMs from PIMs. Generally speaking, stereotypes can act as flags to determine how to create implementation models from abstract models.

The ISO 19103:2015 profile of UML also includes one tagged value:

• codeList, applies to stereotype «CodeList»: Code lists managed by a single external authority may carry a tagged value “codeList” whose value references the actual external code list. If the tagged value is set, only values from the referenced code list are valid.

The ISO 19103:2015 profile of UML is summarized in Figure 13.

Figure 13 — ISO 19103:2015 stereotypes and keywords

5.2.3.2.  ISO 19109:2015 Geographic information — Rules for application schema

ISO 19109:2015 defines rules for creating and documenting application schemas (conceptual schemas for data required by one or more applications), including principles for the definition of features, a fundamental unit of geographic information. As part of the general rules for application schemas it specifies the “General Feature Model” (GFM), the meta-model for application schemas.

The ISO 19109:2015 profile of UML that is used as the conceptual schema language for application schemas adds the critical «ApplicationSchema» (package) and «FeatureType» (class) stereotypes as well as three important tagged values that apply to both of these stereotypes:

designation

Natural language designator for the element to complement the name. Optional, with multiple designations allowed in order to support different languages.

definition

Concise definition of the element. One definition is mandatory. Additional definitions can be provided in multiple languages if required.

description

Description of the element, including information beyond that required for concise definition but which may assist in understanding its scope and application. Optional, with multiple descriptions allowed in order to support different languages.

The ISO 19109:2015 profile of UML is summarized in Figure 14:

Figure 14 — Summary of ISO 19109:2015 profile of UML

5.2.4.  ISO 19118:2011 Geographic information — Encoding

ISO 19118:2011 specifies the requirements for defining encoding rules for use for the interchange of data that conform to the geographic information in the set of International Standards known as the “ISO 19100 series”. It specifies requirements for creating encoding rules based on UML schemas, requirements for creating encoding services, and requirements for XML-based encoding rules for neutral interchange of data. It specifies a profile of UML that includes eight stereotypes, two of which are not previously defined similarly by either ISO 19103:2015 or ISO 19109:2015.

These are:

• «BasicType» is defined in ISO 19118:2011, Clause C.2.1.2:

  “Defines a basic data type that has defined a canonical encoding.” Additionally stated is that: “This canonical encoding may define how to represent values of the type as bits in a memory location or as characters in a textual encoding. Examples of simple types are integer, float and string.”

  Also from ISO 19118:2011, Clause C.5.2.1.1:

“A class stereotyped «BasicType» shall be converted to a simpleType declaration in XML Schema. Any of the data types defined in XML Schema can be used as building blocks to define user-defined basic types. The encoding of the basic types shall follow the canonical representation defined in XML Schema Part 2: Datatypes.” (W3C TR xmlschema-2)

+ NOTE: The different types are not clearly defined in ISO/TS 19103:2005 and neither is the «BasicType» stereotype used. The following declarations, therefore, follow a subset of the data type definitions in W3C TR xmlschema-2. Declared are the types: Number, Integer, Decimal, Real, Vector, Character, CharacterString, Date, Time, DateTime, Boolean, Logical, Probability, Binary, and UnlimitedInteger (where the symbol “*” is used to represent the infinite value).

• «Interface» From ISO 19118:2011, Clause C.2.1.2:

  “Defines a service interface and shall not be encoded.”

  This definition is inconsistent with that of the subsequently published ISO 19103:2015. While this inconsistency may be useful in contexts where it is clear which definition applies, in general it is undesirable to overload the meanings of stereotypes within the OGC community, and in particular thereby coming into conflict with a stereotype specified in ISO 19103:2015.

  While the stereotype «Interface» as defined in ISO 19118:2011 can be (and is here) subsequently ignored, the stereotype «BasicType» is used in the CityGML 3.0 Conceptual Model where it results in difficulties given its tie to a specific encoding technology — XML Schema — and thus lack of true platform independence. The CityGML 3.0 Conceptual Model redefines the stereotype «BasicType» to mean “defines a basic data type”, which is both circular and differs from that of ISO 19118:2011.

ShapeChange adopts a somewhat different definition for stereotype «BasicType» than either ISO 19118:2011 or the CityGML 3.0 Conceptual Model: (https://shapechange.net/app-schemas/uml-profile/#Stereotypes_of_classes)

Marks a so-called basic type, which can have a simple representation in one or more target encodings. It usually is a restriction of CharacterString or Number - or a structured version thereof (e.g., “one two three four” — or any other meaningful combination of such types that is supported by a given encoding).

5.2.4.1.  ISO 19136-1:2020 Geographic information — Geography Markup Language (GML) — Part 1: Fundamentals

ISO 19136-1:2020 specifies an XML-based encoding (consistent with ISO 19118:2011) for the transport and storage of geographic information modelled in accordance with the conceptual modelling framework used in the ISO 19100 series of International Standards, including both the spatial and non-spatial properties of geographic features. It specifies normative rules for the mapping of ISO 19109-conformant UML application schemas to corresponding GML application schemas based on XML Schema.

The ISO 19136-1:2020 profile of UML follows that of ISO 19109:2015 (and thus ISO 19103:2015) while adding numerous tagged values to packages, classes, and properties (Figure 15).

Figure 15 — Tagged values in the ISO 19136-1:2020 profile of UML

A valid UML Application Schema conforms to the conceptual schema rules specified in ISO 19103:2015 and the application schema rules specified in ISO 19109:2015.

A GML-ready UML Application Schema also conforms to the general encoding requirements of ISO 19136-1:2020. Those encoding requirements are summarized in Annex A. They identify required patterns and uses of UML elements, stereotypes, and tagged values based on the ISO 19109:2015 General Feature Model and the necessity of ensuring consistent application of the ISO 19136-1:2020 encoding rules.

5.3.  Resource Description Framework (RDF)

W3C RDF is a standard for representing graph data in terms of the Semantic Web, with Linked Data used to define subjects of description, as well as vocabularies for predicates, expressing attributes of entities and relations between entities, and predicate values, where these can be formally defined as discrete enumerations. It is widely used in semantically-informed description of data. RDF in MDA is extended through two common profiles in the Semantic Web domain:

• Web Ontology Language (W3C OWL, used to define ontologies and data domains and ranges; and

• Simple Knowledge Organization System (SKOS: W3C TR skos-reference), used to define hierarchical controlled vocabularies.

RDF can be used, like UML, to express PIMs which rely on notions of entities, inheritance, and attributes. The enhancement of RDF through OWL makes it more straightforward for RDF to model inheritance, while SKOS is used to model the constrained enumerations essential to MDA. Clause 9 reports on the testbed sub-task D143, where the use of RDF and OWL was investigated as an alternative to UML for driving MDA within OGC.

5.4.  OGC Standard for Modular specifications

5.5.  Metanorma