Published

OGC Engineering Report

OGC Testbed-17: Model-Driven Standards Engineering Report
Ronald Tse Editor Nick Nicholas Editor
OGC Engineering Report

Published

Document number:21-035r1
Document type:OGC Engineering Report
Document subtype:
Document stage:Published
Document language:English

License Agreement

Permission is hereby granted by the Open Geospatial Consortium, (“Licensor”), free of charge and subject to the terms set forth below, to any person obtaining a copy of this Intellectual Property and any associated documentation, to deal in the Intellectual Property without restriction (except as set forth below), including without limitation the rights to implement, use, copy, modify, merge, publish, distribute, and/or sublicense copies of the Intellectual Property, and to permit persons to whom the Intellectual Property is furnished to do so, provided that all copyright notices on the intellectual property are retained intact and that each person to whom the Intellectual Property is furnished agrees to the terms of this Agreement.

If you modify the Intellectual Property, all copies of the modified Intellectual Property must include, in addition to the above copyright notice, a notice that the Intellectual Property includes modifications that have not been approved or adopted by LICENSOR.

THIS LICENSE IS A COPYRIGHT LICENSE ONLY, AND DOES NOT CONVEY ANY RIGHTS UNDER ANY PATENTS THAT MAY BE IN FORCE ANYWHERE IN THE WORLD. THE INTELLECTUAL PROPERTY IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE DO NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE INTELLECTUAL PROPERTY WILL MEET YOUR REQUIREMENTS OR THAT THE OPERATION OF THE INTELLECTUAL PROPERTY WILL BE UNINTERRUPTED OR ERROR FREE. ANY USE OF THE INTELLECTUAL PROPERTY SHALL BE MADE ENTIRELY AT THE USER’S OWN RISK. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR ANY CONTRIBUTOR OF INTELLECTUAL PROPERTY RIGHTS TO THE INTELLECTUAL PROPERTY BE LIABLE FOR ANY CLAIM, OR ANY DIRECT, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM ANY ALLEGED INFRINGEMENT OR ANY LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR UNDER ANY OTHER LEGAL THEORY, ARISING OUT OF OR IN CONNECTION WITH THE IMPLEMENTATION, USE, COMMERCIALIZATION OR PERFORMANCE OF THIS INTELLECTUAL PROPERTY.

This license is effective until terminated. You may terminate it at any time by destroying the Intellectual Property together with all copies in any form. The license will also terminate if you fail to comply with any term or condition of this Agreement. Except as provided in the following sentence, no such termination of this license shall require the termination of any third party end-user sublicense to the Intellectual Property which is in force as of the date of notice of such termination. In addition, should the Intellectual Property, or the operation of the Intellectual Property, infringe, or in LICENSOR’s sole opinion be likely to infringe, any patent, copyright, trademark or other right of a third party, you agree that LICENSOR, in its sole discretion, may terminate this license without any compensation or liability to you, your licensees or any other party. You agree upon termination of any kind to destroy or cause to be destroyed the Intellectual Property together with all copies in any form, whether held by you or by any third party.

Except as contained in this notice, the name of LICENSOR or of any other holder of a copyright in all or part of the Intellectual Property shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Intellectual Property without prior written authorization of LICENSOR or such copyright holder. LICENSOR is and shall at all times be the sole entity that may authorize you or any third party to use certification marks, trademarks or other special designations to indicate compliance with any LICENSOR standards or specifications. This Agreement is governed by the laws of the Commonwealth of Massachusetts. The application to this Agreement of the United Nations Convention on Contracts for the International Sale of Goods is hereby expressly excluded. In the event any provision of this Agreement shall be deemed unenforceable, void or invalid, such provision shall be modified so as to make it valid and enforceable, and as so modified the entire Agreement shall remain in full force and effect. No decision, action or inaction by LICENSOR shall be construed to be a waiver of any rights or remedies available to it.

None of the Intellectual Property or underlying information or technology may be downloaded or otherwise exported or reexported in violation of U.S. export laws and regulations. In addition, you are responsible for complying with any local laws in your jurisdiction which may impact your right to import, export or use the Intellectual Property, and you represent that you have complied with any regulations or registration procedures required by applicable law to make this license enforceable.



I.  Abstract

This OGC Testbed 17 Engineering Report is deliverable D022 of the OGC Testbed 17 initiative performed under the OGC Innovation Program, incorporating the D022, D143 and D144 tasks that have produced Model Driven Architecture (MDA) tools.

This ER:

  1. details state-of-the-art analyses of existing MDA tools with their capabilities and limits; and

  2. provides clear recommendations on how model-driven design can be fully exploited in the context of rich data model and API design efforts.

II.  Executive Summary

The Model-Driven Architecture (MDA) approach to the generation of Model-Driven Standards (MDS) and Platform-Independent Models (PIM) has been proven to work through Testbed activities (D022, D143, D144) covered by this Engineering Report (ER).

A total of 4 prototype systems were developed under D144:

  1. Converting the CityGML 3.0 conceptual model into an MDS;

  2. Converting the Discrete Global Grid Systems (DGGS) conceptual model into an MDS;

  3. Converting the CityGML 3.0 conceptual model to XML Schema as a PSM;

  4. Converting the CityGML 3.0 conceptual model to JSON Schema as a PSM.

The 5th prototype system for “Converting the CityGML 3.0 conceptual model to Resource Description Framework (RDF) as a PSM” is still in progress.

Under D143, a theoretical methodology was presented for using RDF as an alternative modelling approach instead of the Unified Modeling Language (UML).

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.

The strong implication for using an MDA approach is that generally, the MDA approach makes any inconsistencies, omissions, or under-specifications in underlying information models much more visible, since they impact the MDA workflow directly.

In particular, the following criteria needs to be met for an MDA approach to be effective (this is duplicated in Clause 4):

  1. The authoritative information model must be fully and accurately specified with regards 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 utilize a proprietary structure and require 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.

This report recommends OGC to perform the following:

The Testbed participants would like to especially thank the project sponsors for their vision and openness, and for making this very important work available.

III.  Keywords

The following are keywords to be used by search engines and document catalogues.

ogcdoc, OGC document, MDA, model-driven


IV.  Preface

This ER is deliverable D022 of OGC Testbed 17.

The focus of this testbed activity was to demonstrate the business value of model-based standards, as an extension from the MDA approach for creating standards.

As literature suggests, the following are the major benefits from developing standards in a model-driven manner:

  1. By maintaining standards content in the model, simplifying and decoupling the model maintenance process is possible.

  2. Storing annotations and guidance about the model together with the actual model enables a single source of truth that can streamline the standards authoring process.

  3. The maintenance of a single Platform Independent Model (PIM) supports automatic generation of one or multiple Platform Specific Models (PSMs), which can be directly used by developers and applications.

  4. PSMs can also be treated as models in the same manner as PIMs. This means that PSMs also receive the same benefits from the model-based standards approach.

The results of the work performed in this testbed activity have confirmed that the above benefits are achievable through a model-driven approach, with the following findings:

  1. A model-driven approach drives quality requirements upstream, and as such the model used as the source for a model-based standard must have dependable quality for downstream artifacts to be created accurately.

  2. Rules and normalization procedures should be applied to a model being used as the basis for a model-based standard to ensure quality of generated downstream artifacts.

  3. “Best practice” templates can be developed for different model types, such as for Sparx Systems Enterprise Architect Projects (EAP), Unified Modeling Language (UML) models, XML Schema Documents (XSDs), etc., enabling consistent presentation and facilitating reuse across the organization.

  4. In certain conditions, when migrating standards that were fully model-based, a “hybrid” mechanism needs to be used, such as when the original standard deviates heavily from a model-driven counterpart or requires certain content hierarchies for backwards compatibility. In these cases, custom templates or templates with the ability to override “best practice” become necessary.

V.  Security considerations

No security considerations have been made for this document.

VI.  Submitting Organizations

The following organizations submitted this Document to the Open Geospatial Consortium (OGC):

VII.  Submitters

All questions regarding this document should be directed to the editor or the contributors:

Name Organization Role
Ronald Tse Ribose Limited Editor
Nick Nicholas Ribose Limited Editor
Chuck Heazel Heazeltech, LLC Contributor
Paul Birkel Geosemantic Resources LLC Contributor
Jeffrey Lau Ribose Limited Contributor
Nicholas Car SURROUND Australia Pty Ltd Contributor

OGC Testbed-17: Model-Driven Standards Engineering Report

1.  Scope

This Engineering Report is a deliverable of the OGC Testbed 17 initiative. The objective of the ER is to demonstrate the business value of model-driven standards, as an extension of the model-driven architecture approach for creating standards.

This document describes several proofs-of-concept developed under deliverables D143 and D144 to demonstrate the authoring of model-based standards.

2.  Terms, definitions and abbreviated terms

This document uses the terms defined in OGC Policy Directive 49, which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this document and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2.

This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the ‘ModSpec’. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec.

For the purposes of this document, the following additional terms and definitions apply.

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.  Introduction

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.

Figure 1 — Conceptual derivation of direct and augmented truths from a single source of truth

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

A Conceptual Model can be a PIM, being technology-independent by definition. Conceptual Models are commonly specified using UML Class diagrams.

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

A pure mapping from a UML Class diagram to XSD will map all UML class attributes consistently, e.g. as XML elements. If the mapping is instead to choose between XML elements and XML attributes for its rendering of UML class attributes, following user configuration, the PSM is mixed: the guidance as to which class attributes to render as XML elements and which as XML attributes is supplementary truth, as it is information extraneous to the PIM, the UML Class model.

Figure 2 — Conceptual derivation of PSMs from a PIM with supplementary platform-specific information

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).

Figure 3 — Process in creating PSMs from a PIM with PSM-specific information

Figure 4 — PIM-derived artifacts

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

An API model (PSM) generated from a conceptual model (PIM) can further generate XML encodings (PSM) using the API model as its own starting source of truth.

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

MDAOGC and ISOModel Formats
Platform Independent Model (PIM)Conceptual Model/SchemaUML
Platform-Specific Model (PSM)Implementation SpecificationXML Schema, JSON Schema, SQL DDL, OWL/RDF

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).

Figure 5 — Components of an OGC Standard

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.

Figure 6 — Authoring model-based standards, the old way

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).

Figure 7 — New generation flow using automated processes

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).

Figure 8 — Generating a model-based standard from a series of model transformations

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.

Figure 9 — Conceptual levels of information models

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.10.1.  ISO/TC 211 Standards

Technical Committee 211 of the International Organization for Standardization (ISO/TC 211) manages a set of ISO standards for geographic information.

3.10.2.  ISO 19109

ISO 19109:2015 defines a Unified Modeling Language (UML) metaschema for feature-based data. That General Feature Model (GFM) serves as the key underpinning for a family of ISO standards employed by members of the OGC community.

These standards define the structure and content of geospatial data in a family of “conceptual schemas” that employ the UML Class diagram methodology. These standards are regularly employed by members of the OGC community.

3.10.3.  ISO 19136

ISO 19136:2007 Annex E “UML-to-GML application schema encoding rules” defines a set of encoding rules that may be used to transform a GFM-conformant UML conceptual schema to a corresponding XML Schema (XSD) based on the structure and requirements of the Geography Markup Language (GML).

The resulting XSD file(s) may be used to define the structure of, and validate the content of, XML instance documents used in geospatial data exchange.

This methodology for deriving technology-specific encodings of GFM-conformant UML conceptual schemas, based on formalized sets of encoding rules, has been successfully applied in other contexts than GML (e.g., technologies based on Resource Description Framework (RDF) encodings), and has come to be known generically as “UGAS”. UGAS is an example of the Model Driven Architecture (MDA) paradigm introduced by the Object Management Group (OMG) in 2001.

3.10.4.  ShapeChange

ShapeChange is an open-source implementation of the UGAS methodology that has emerged as a key technological underpinning in many environments where platform-specific data exchange requirements have been separated from platform-independent domain (content) modeling requirements.

MDA techniques have been used sporadically to develop OGC and ISO/TC 211 standards; ShapeChange has been instrumental in many of those efforts, although effort-specific documentation has been generally sparse.

Engineering Reports documenting OGC-related ShapeChange initiatives can be found at https://shapechange.net/about/background-documents/

3.10.5.  Metanorma

Metanorma is the leading open-source standards development and publishing suite.

Metanorma enables creation of semantic-aware standard documents in an end-to-end, author-to-publish workflow, based on the notion that standard documents from different standards-setting bodies rely on common requirements. It was named “Best New Semantic Technology Platform, Tools and Applications” and “Best New Scholarly Publishing Information Solution” by the International Business Awards.

Metanorma technology consists of three parts:

  • a unified document model for standard documents, based on ISO/AWI 36100,

  • a serialization format for standard documents into semantic and presentational formats, and

  • a toolchain for authors to directly publish standard documents in the correct structure and appearance without the need for post-processing.

Metanorma is used by over 15 standards organizations, including OGC itself.

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:

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

PIMPSM

CityGML 3.0 CM

OGC Standard

CityGML 3.0 CM

XML schema

CityGML 3.0 CM

JSON schema

CityGML 3.0 CM

OWL/RDF

DGGS CM

OGC and ISO standard

Four target PSM environments were explored:

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.  Key findings

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).

Figure 10 — Current and future OGC Engineering Reports for PSM documentation standards

4.3.  Prototype capabilities

4.3.1.  PIM-to-MDS prototypes

In the case of the PIM-to-MDS prototypes, both the PIMs (the UML classes, as expressed in XMI) and the document authoring environment (Metanorma) were stable at the time of implementation.

Metanorma is used to manage and perform the core PIM-to-MDS transformation. Metanorma is the established authoring toolchain tailored for creating OGC Standards.

Several types of information were involved in the PIM-to-MDS transformations:

  • PIM and the annotations stored within it, managed in Sparx Systems Enterprise Architect

  • ModSpec models, managed in Metanorma

  • Supplementary text and additional diagrams, managed in Metanorma

The PIMs are exported as EA-proprietary XMI v2.5 files and EMF diagrams, as input for the Metanorma transformation process.

LutaML (Clause 7.2) and the Metanorma-LutaML plugin are used to mediate between the model authoring tool (EA) and the MDS tool (Metanorma). LutaML is a universal data accessor implemented to facilitate MDA, and has an extensible structure that allows it to read in models expressed in a range of formats, including EA-proprietary XMI.

The prototypes (Clause 10.4, Clause 10.5) have been proven successful, and the approach has been flexible enough to be useful for MDS from a range of models, not limited to the OGC, as demonstrated by the ability to generate the ISO-version of DGGS, ISO 19170.

4.3.2.  PIM-to-PSM prototypes

In the case of the PIM-to-PSM prototypes, while the selected PIM (CityGML 3.0 conceptual model) was stable, the PSMs of it were not set in stone.

Given that the project sponsor encouraged experimentation, the development of the prototypes demonstrated the possibility and highlighted issues that should be addressed in order to make PIM-generated PSMs useful.

ShapeChange was used to perform the transformation from PIM to PSM. The PIM was authored in Sparx Systems Enterprise Architect.

The PIM was exported into the EA-proprietary profile of the XMI format, then processed by ShapeChange, as documented in Clause 7.1. ShapeChange is long-established as a PSM generation tool for OGC, and it supports the requisite range of capabilities to deliver the PSMs needed by OGC.

The prototypes (Clause 10.6, Clause 10.7, Clause 10.8) have been shown to be successful and demonstrates that it is indeed possible to generate a PSM that is succinct and specified to a sufficient level for application purposes.

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.6.1.  General

There are additional needs for cross-referencing when performing a PIM-to-MDS conversion, categorized in four (4) types: A, B, C and D shown in Figure 11.

Figure 11 — Cross-references supported between PIM-MDS

4.6.2.  Type A: Cross-reference model-generated document elements from the information model

This type cross-references document elements generated from the information model, from textual elements within the information model. The intricacies of this mechanism are shown in Figure 12.

Figure 12 — Converting information model cross-references into document cross-references

In the model authoring environment, there are often textual elements of a UML model (such as the description field) that cross-reference another UML model in the same information model context (e.g. an Sparx Systems Enterprise Architect file). However, model authoring tools do not typically provide a formal and structured manner for specifying these cross-references.

The MDS tool must be able to recognize these internal cross-references through a standardized convention.

Example

In the OGC CityGML 3.0 conceptual model, there are cross-references in the description of UML classes and attributes that point to other UML classes or attributes inside the same context.

4.6.3.  Type B: Cross-reference document elements from the information model

This type represents the ability to cross-reference static document elements from textual elements from within the information model.

In the model authoring environment, there are textual elements of a UML model that contain cross-references to document elements external to the information model, such as to ModSpec requirements. The MDS tool must provide a mechanism for defining referential identifiers and allowing cross-references that utilize identifiers to be encoded through the model authoring tool, and ultimately creating the MDS with those cross-references realized.

4.6.4.  Type C: Cross-reference model-imported elements from the document

In an MDS authoring environment, an expert MDS author may want to cross-reference elements that were made available through the information-model-to-MDS transformation process.

Example

In the MDS portions of the OGC DGGS standard, there are cross-references to particular UML diagrams (through the lutaml_figure command in the MDS) that were provided from within the Sparx Systems Enterprise Architect file.

4.6.5.  Type D: Cross-reference model-generated document elements from the document

In the MDS authoring environment, an expert MDS author may want to cross-reference elements that were generated by the information-model-to-MDS transformation process.

Example

In the MDS portions of the OGC CityGML 3.0 standard, there are cross-references to particular UML package and class descriptions (through the lutaml_table command in the MDS) that were document elements generated from information within the Sparx Systems Enterprise Architect file.

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

In the DGGS conceptual model, some packages were found not to be present in the ISO/TC 211 Harmonized Model.

Example 2

Similar issues with incomplete conceptual model dependencies were encountered repeatedly for CityGML (Clause 8.2.4, Clause 8.2.5, Clause 8.2.6), and point to past lax management of the information model.

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.

NOTE  It is said that Sparx Systems Enterprise Architect supports custom ordering of UML packages. If so, it is possible to have the MDS tool (Metanorma) support that encoded ordering if desired.

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

CityGML 3.0DGGS

Document structure

Does not align with package hierarchy

  • Requires backwards compatibility to CityGML 2.0 standard document structure

  • Requires manual references to generated package/class/figure document artifacts

Identical to package hierarchy

  • Including packages, classes, figures

Model representation structure

Flat

Hierarchical

Model rendering style

Multiple styles on the same content: entity list vs data dictionary

Single

4.14.  Challenges with coordinating derived and supplementary truth

4.14.1.  General

Supplementary truth applied to an MDS or a PSM is extraneous to the primary source information model, by definition, so it has to be planned as a separate activity outside the generation of the augmented truth.

4.14.2.  Challenges for MDS authors

In fact, MDS authors are required to fill in the gaps in guidance that are not apparent from inspection of the model in isolation. This implies that authoring happens in passes, rather than authoring both model definitions and commentary in a single go:

  • the author first generates the derived truth: an MDS presenting the PIM

  • then works out what additional information needs to bind to the derived truth, and where to do so.

The MDA approach to MDS implies that authoring is a non-linear process. Authors will need to refer back to notes and comments to explain design decisions and constraints. Authors that are not familiar with the primary source information model (the PIM) may be uncomfortable with writing guidance for it.

On the other hand, given that the model is documented automatically out of machine-readable artifacts, which have typically already been used in production in an automated, well-engineered software process, means that details will not be missed, and that the completeness of documentation is guaranteed.

Authors used to working with linearly-authored documentation may resist the constraints of embedding documentation into unfamiliar model authoring tools, especially if they are not fully integrated with their authoring environment.

It may prove necessary to make future information model integration into documentation configurable, so as to skip specific annotations, which will be addressed in supplementary truth instead.

An MDS author intending to create OGC deliverables is naturally required to work natively with information models and cannot shy away from the following repertoire:

  • PIM model in UML

  • ModSpec models in Metanorma or YAML format

  • Text markup in Metanorma format

4.14.3.  Challenges with collaboration of MDS content

In the MDS prototypes for CityGML 3.0 and DGGS, the supplementary truth for the documents has been written as Metanorma text, and managed through Git in order to enable collaborative authoring and review of that text.

As with any collaboratively authored text, a certain amount of discipline is required around authoring, particularly as the structure of the supplementary truth is dependent on the given information model: the editor needs to ensure that the connection between supplementary truth and the information model is maintained.

There is an added coordination challenge where ideas need to be generalized across different component implementation teams for the same standard, working from the same information model.

4.14.4.  Challenge to coordinate PIM annotations and supplementary truth to MDS

A further challenge is that some textual content of the MDS is not extraneous to the information model, but is included in the model as annotation.

The division between the two kinds of content needs to be planned for, to prevent confusion and duplication of effort, especially if the annotations and the supplementary truth are managed by separate teams, and risk either contradicting each other, or presenting information redundantly.

Coordination was proved necessary in the prototype: there needed to be guidance offered on what information to enter in Notes, and what syntax it should be expressed in (which has implications for the integration process).

It may be necessary to constrain the kind of content that can appear in either derived or supplementary truth, to prevent conflict and confusion.

In the MDS prototypes, LutaML iterates through objects from the information model as a block. So it presents each UML class derived from the PIM as a complete entity in the target Metanorma document; it would do the same for an object definition in XSD.

However, it is not currently possible for LutaML to interleave supplementary truth authored outside the model authoring tool with the presentation of an information model object: any commentary or annotation on a model object needs to be added after the object is presented in full. So authoring an MDS is somewhat inflexible: objects from the derived truth (including annotations out of the model management system) are presented as a block, and any commentary or discussion of the object need to occur as a block after the object. There is no current mechanism, for instance, to annotate particular parts of the object with comments as callouts, written in Metanorma.

Example

A note on a UML attribute cannot be interpolated from Metanorma into the PIM-derived tabular presentation of the class: it can only be added before or after the object rendering (provided for in LutaML as [.before] vs [.after] blocks).

This limitation leads to a division of labor in the current tooling: annotations within an object have to be added in the model authoring tool, and cannot include supplementary truth.

This challenge is an instance of the question of how to annotate externally sourced online content. That has been a longstanding concern with hypertext, and approaches have been devised to tackle it (e.g. W3C TR annotation-model). If interleaving supplementary and derived truth more fluidly in MDA proves desirable, LutaML can be expanded to support it better, harnessing such approaches to annotation.

That said, whether interpolating supplementary truth into model-derived artifacts is even desirable is unclear: it makes for more flexible authoring, but it can also lead to more difficulty in coordinating authoring, and it can make the document harder to read.

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

4.17.1.  General

This section describes possible work to be done in the future. These are in addition to the findings and recommendations discussed above, which should all be addressed.

4.17.2.  SMART standards and models

Because the subject matter of MDS is modelled in information models, MBA makes it possible for documentation to be oriented to both human audiences and machine audiences, as human-readable or machine-readable artifacts.

As described in this document, standards documents themselves are represented as and governed by information models. This means that the supplementary truth in those standards — the guidance and normative content itself — can be made machine-readable and machine-addressable.

The BR SMART initiative (see Annex C) currently underway harnesses this approach to make standard documents themselves fully machine-readable, including granular semantic modelling of normative statements and requirements.

This granular modelling also enables for the exportation to a semantic web-based information representation like W3C RDF.

The benefits of this initiative can be harnessed by OGC to derive greater benefit from its standards, for example in automated testing.

4.17.3.  Cross-reference integration between PIM and MDS

References to bibliography and terminological entry, as supplementary truth, are managed in the Metanorma environment, as is appropriate for an authoring environment.

This poses a challenge when cross-references to those entries, or to document content (supplementary truth), need to be made as part of the derived truth, i.e. the content authored within the model management tool, in such places as annotations.

In the case of UML Class diagrams, that arises in case the classes incorporate commentary and annotations with cross-references, as human-readable content.

Because the references the annotations cross-reference are defined externally, in Metanorma, there is a risk that the cross-references and the references will fall out of sync during authoring: if a reference is updated in Metanorma, the author may not find it is disrupting a reference from the PIM until much later. This makes managing cross-references more laborious than if both the supplementary and the derived truth were managed in the same authoring environment.

NOTE  Model-internal cross-references to other components of the same PIM, e.g. from one UML class to other UML classes, are much more likely to be well-defined through the tools used to manage the PIM itself, so they do not present the same level of challenge.

To manage external cross-references out of the PIM requires one of the following approaches:

  • Use a PIM tool that supports external definitions of cross-references.

    Example 1

    Sparx Systems Enterprise Architect UML class annotations can include Metanorma-formatted references to anchors that are defined in the Metanorma target document (e.g. as defined in <‌<ISO-639>>).

    • While this works, it tethers the PIM to a particular combination of authoring environment and definitions of anchors. This makes it more difficult to reuse PIM annotations in different documents, which might apply different anchor identifiers.

    • Reuse becomes even more difficult if the reference is to a clause in the target document: a naive document-internal reference may need to be changed to a bibliographic citation.

    • It also means that bibliography and terminology references need to be maintained separately in Metanorma and the UML authoring tool.

  • Cross-references are not made machine-readable in the UML authoring tool at all, and are left as pure text.

    Example 2

    In the PIM authoring tool, spell out references to standards documents as document titles. This approach was used during this prototype task.

    • While this avoids the problem, it also means that the document is semantically impoverished, and there is inconsistent presentation of cross-referenceable information between the derived truth and the supplementary truth in a standards document.

The proper solution to this challenge is tighter integration between Metanorma and PIM authoring tools.

Example 3

The PIM authoring tool and Metanorma could potentially share a bibliography plugin, or that Metanorma can import bibliographic information from the PIM (via LutaML) using a map that translates cross-references in PIM annotations into Metanorma cross-references.

4.17.4.  ModSpec as PIM and ModSpec validation

Currently, ModSpec instances constitute supplementary truth in an MDS, as separately authored Metanorma content outside of the PIM. ModSpec instances can be encoded in Metanorma AsciiDoc or in the Metanorma-specific ModSpec-YAML format.

The Metanorma ModSpec authoring process today already provides some validation of ModSpec instances, such as:

  • providing a fixed structure for entering of ModSpec model attributes

  • warning if mandatory ModSpec model attributes are left empty

  • confirming that conformance tests have matching requirements, and vice versa

Even so, during the development of the prototypes, challenges were encountered as detailed in Clause 4.11 due to inconsistencies found, including:

  • inconsistent treatment of Conformance Test parts and Conformance Test steps (normative description differs from UML specification).

  • additional unsanctioned ModSpec attributes presented in some OGC Standards that requires adaptation of MDS tool.

  • usage of parameterization and conditionals in existing OGC Standards can differ from the ModSpec specification.

  • lack of testable formal requirements for ModSpec compliance.

It is recommended to:

  • Revise the ModSpec specification to resolve inconsistencies.

  • Create a dedicated ModSpec authoring and validation tool for ModSpec instances to be used in a modular fashion and shared between standards, as originally intended. Validation of ModSpec instances will improve the quality of requirements and their adoption.

  • Consider the possibility of machine-encoding of ModSpec for the purpose of automated testing and ModSpec validation, such as to ensure that conformance tests are satisfied by the model through automated testing.

In fact, Metanorma already provides a good basis of such implementation, by:

  • fully implementing the ModSpec information model.

  • accepting Metanorma AsciiDoc and YAML as input.

  • providing some ModSpec validation.

  • allowing the conversion of ModSpec into XML.

It would be possible for the Metanorma team to provide an open-source implementation for this purpose.

Once such a tool is developed, the ModSpec instances would be managed as an additional source of PIM primary truth (in addition to the original PIM), and integrated into the MDS transformation process just as is done with the PIM-to-PSM processes.

The resulting workflow would be automatic, and would not require manual input or adjustments.

5.  Model specification technologies

5.1.  General

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

5.2.  Unified Modeling Language (UML)

5.2.1.  General

ISO/IEC 19501 specifies the UML modelling language, a graphical language for visualizing, specifying, constructing, and documenting the artifacts of a software-intensive system.

UML specifies a set of methodologies for developing technical artifacts used in the design of a software system, ranging from business processes and system functions to programming language statements, database schemas, and reusable software components. UML is often used to develop domain-specific models (e.g., geospatial information) used in system development.

In this Testbed task, the use of UML in documenting a PIM relies on the following functionality defined in UML:

  • For model definition, the definition of information models and their relationships, that contain human- and machine-readable components, and

  • For class diagrams, the visual arrangement of UML class relationships intended for human consumption only.

5.2.2.  Modelling capability

5.2.2.1.  Basic modelling elements

UML provides three (3) basic modeling elements:

  • Package

  • Class, and

  • Property

The usage of UML can extend beyond these modelling elements for these purposes:

  • System developers may sometimes require additional modeling capabilities beyond those defined in the UML standard.

  • System developers may need to attach a variety of types of information to models

    Example

    To guide the derivation of technology-specific implementations.

5.2.2.2.  Extensions

UML provides three (3) built-in extension mechanisms that enable new kinds of modeling elements to be added to the modeler’s repertoire, as well as to attach “free-form” information to modeling elements. The extension mechanisms can be used separately or in combination to define new modeling elements that can have distinct semantics, characteristics, and notation relative to the built-in modeling elements specified by the UML metamodel.

These extension mechanisms are:

  • Stereotype,

  • Tagged Value, and

  • Constraint.

5.2.2.3.  Stereotype

A stereotype is an extension mechanism that is used to extend a UML metaclass by enabling the use of platform- or domain-specific terminology or notation in place of, or in addition to, the ones used for the extended metaclass.

More than one stereotype may be simultaneously used to extend a UML metaclass.

Example 1

The «FeatureType» stereotype applied to a UML Classifier (class) might indicate that in an implementation a spatial representation will be assigned and spatial indexing should be implemented.

Example 2

The «identifier» stereotype applied to a UML Attribute property might indicate that the property value may be used as the Primary Key in a relational implementation.

5.2.2.4.  Tagged value

A tagged value is an extension mechanism that is used to define (as a “tag definition”) a stereotype-specific characteristic that extends a UML model element (package, class, property) with additional information (as a “tagged value”).

Different stereotypes for a given UML metaclass may specify different sets of tag definitions. A given tag definition may be associated with more than one stereotype.

Example 1

A definition tagged value may be assigned to a model element in order to store a “concise definition of the element”

Example 2

A version tagged value may be assigned to store configuration management information for that element.

5.2.2.5.  Constraints and Object Constraint Language (OCL)

A constraint is an extension mechanism that is used to express characteristics of a model that cannot be expressed in the UML class diagram notation. For example, a validation constraint that the allowed values of two properties interact and only certain patterns of values are allowed.

Constraints are usually expressed using the formal notation of ISO/IEC 19507:2012.

5.2.2.6.  UML Profile

A collection of coordinated UML extensions may be documented in the form of a UML Profile. A UML Profile consists of a well-specified set of stereotypes, tagged values, and constraints that collectively specialize and tailor the UML for a specific domain (e.g., geospatial information modeling) or process.

A profile does not extend UML by revising the UML metamodel. Instead, it provides conventions for applying and specializing standard UML metamodel concepts to a particular environment or domain.

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.2.5.  Tools

In order to develop UML models for PIM-to-PSM and PIM-to-MDS purposes, it is necessary to define a toolchain that can interoperate from PIM to PSM and MDS stages for model transformation and downstream representations.

Various software tools exist to author UML models, and also to read such models.

5.2.5.1.  Sparx Systems Enterprise Architect (EA)

Sparx Systems Enterprise Architect is widely used in OGC and ISO/TC 211 for the authoring and management of UML models.

Sparx Systems Enterprise Architect is historically a 32-bit Windows application:

  • With the release of EA Version 15 a 64-bit Windows application may access an EA project file.

  • With the upcoming release of Version 16 (in Beta mode as of January 2022), EA will be a 64-bit Windows application.

The UML artifacts it generates are the input to both ShapeChange, for generating PSMs (Clause 7.1), and to Metanorma and LutaML (Clause 7.2), for generating MDS.

5.2.5.2.  ShapeChange

ShapeChange is an open-source tool for model conversions. It can read Sparx Systems Enterprise Architect project files using code provided by the Sparx Systems Enterprise Architect JAR file.

It is used to generate PSM outputs such as XML Schema, JSON Schema and RDF outputs from PIMs in the Sparx Systems Enterprise Architect format.

Through integration with EA, ShapeChange can access native EA artifacts directly, and then export the native EA project file into the XMI format (OMG XMI 2.5), then convert the exported XMI into the ShapeChange XML (SCXML) format.

5.2.5.3.  LutaML and Metanorma

LutaML is a universal data model accessor that supports both UML and XMI, and is part of the Metanorma software suite which facilitates the generation of MDS documents.

Metanorma provides a LutaML plugin that allows Metanorma authors to access information models from various modelling languages, including UML and EXPRESS. Specifically, it supports parsing and accessing UML written in the XMI format, including the Sparx Systems Enterprise Architect profile of the XMI format.

LutaML can access UML packages stored in Sparx Systems Enterprise Architect project files by first exporting the UML package into the XMI format, of which the LutaML-XMI plugin can consume.

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.4.1.  General

OGC 08-131r3 “The Specification Model — A Standard for Modular specifications”, also known as the ModSpec, contains requirements and conformance classes for writing standards to be used for any document whose eventual purpose is the specification of requirements for software, services or data structures.

OGC 08-131r3, Introduction helpfully uses an example from Thomas the Tank Engine, who strives to be a “really useful engine”, to explain its motivation in making standards useful.

A standard’s usefulness and hence worth can be measured by:

  • The ease with which it can be implemented.

  • The number of times it has been implemented.

  • The number of times those implementations are used.

  • The ease with which those implementations interact.

  • The number of times it has been extended through inclusion in other useful standards.

The intention of ModSpec is to enable interoperability of implementations, and the standard concludes that in order to validate requirements across implementations, it is necessary for conformance tests to be re-useable and organized in an effective manner. It achieves that by providing a standardized set of information models for these requirements and tests.

5.4.2.  ModSpec models

ModSpec provides a set of information models towards this goal, as defined in OGC 08-131r3, Clause C.2, in UML, described below.

NOTE 1  The order of these described models differ from the ModSpec standard for clarity of conceptual coherence.

  • Container:

    • Specification (OGC 08-131r3, Clause C.3). A specification is a container, a namespace for a set of ModSpec model instances. It represents a “standard”, such as an OGC or ISO standard.

  • Related to specification:

    • Normative statement (OGC 08-131r3, Clause C.8). A normative statement.

    • Requirement (OGC 08-131r3, Clause C.9). A requirement is a normative statement that is required in an implementation. It links to at least one conformance test which, when passed, confirms the satisfaction of the requirement.

    • Recommendation (OGC 08-131r3, Clause C.10). A recommendation is a normative statement that presents optional but recommended functionality. There may or may not be a conformance test associated with it.

    • Permission (OGC 08-131r3, Clause 4.20). A permission is a normative statement that is entirely optional. While this model type is not directly defined in the ModSpec standard, it is described at OGC 08-131r3, Clause 4.20. There may or may not be a conformance test associated.

    • Requirements class (OGC 08-131r3, Clause C.6). A requirements class represents a coherent feature set. A requirements class can depend on other requirements classes and requirements modules, and applies to a standardization target type.

    • Requirements module (OGC 08-131r3, Clause C.7). A requirements module represents a coherent set of requirements needed by a feature. It is composed of a set of requirements.

  • Related to verification:

    • Conformance suite (OGC 08-131r3, Clause C.4). A conformance suite is a set of conformance classes. It is intended to represent a set of conformance classes that represent a “feature set” intended to test an implementation.

    • Conformance class (OGC 08-131r3, Clause C.5). A conformance class is a set of conformance tests, and links to at least one requirements class. Conceptually it represents a “feature” of an implementation. Implementations may claim conformance to a “conformance class” for a feature that was validated.

    • Conformance test (OGC 08-131r3, Clause C.11). A conformance test represents a functional test intended to validate an implementation function. A conformance test is allowed to have separate parts and hierarchical steps (OGC 08-131r3, Clause C.11). A conformance test can be abstract, i.e. requires additional information to be executable.

      NOTE 2  See Annex D.1 for a discussion of the validity of test parts and test steps.

    • Abstract test. An abstract test is simply a conformance test that is abstract. While the term “abstract test” is not formally defined by ModSpec, it is heavily used in OGC Standards (and to that extent, standards published by ISO/TC 211).

    • Abstract test class. An abstract test class is a conformance class that only contains abstract tests. It is not formally defined by ModSpec but is used widely in OGC Standards.

    • Abstract test suite. An abstract test suite is a conformance suite that only contains abstract tests. It is not formally defined by ModSpec but is used widely in OGC Standards.

  • Role:

    • Standardization target (OGC 08-131r3, Clause C.12). An entity to which some requirements of a standard apply.

    • Standardization target type (OGC 08-131r3, Clause C.13). The type of entity or set of entities to which the requirements of a standard apply.

5.4.3.  Usage of ModSpec in OGC

According to the OGC Policy Directives, OGC Standards that contain requirements must have those requirements conform to OGC 08-131r3. Therefore, all OGC Standards are required to utilize ModSpec defined models in the representation of specification and verification mechanisms.

By using these information models, requirements from different OGC Standards can in effect be considered “modular”, i.e. these requirements can coexist in the same standard without being in conflict.

The ModSpec models themselves are abstract information models, and in order to use them, OGC Standards are closely gated by the OGC Standards team to have “instantiated” ModSpec models with the following requirements:

  1. Each ModSpec model instance has a unique identifier in form of an OGC-wide unique URI

  2. The linkages between the defined ModSpec model instances are validated to be correct and consistent.

  3. The ModSpec model instances are published in the OGC Definitions Server.

Prior to this Testbed deliverable, the above steps and validation are often performed manually, which presents a heavy burden on both the standardization project team and the OGC editorial team.

In the course of this Testbed, we have found certain issues in the ModSpec standard that were resolved. Details are documented in Annex D.

5.5.  Metanorma

5.5.1.  General

As described in Clause 3.10.5, Metanorma is an open-source framework for creating and publishing standardization artifacts with the focus on semantic authoring and flexible output support.

Metanorma provides a model-based documentation system and prioritizes automation.

Overall, Metanorma provides the following items:

  • a set of standard document metamodels (ISO/AWI 36100), called “Metanorma StanDoc”, that allows different standardization bodies to create their own standardized document model for their standard documents;

  • a standard XML schema (ISO 36300), as machine-readable standardization documents, that is the serialized form of the document models mentioned above; and

  • a publishing toolchain that enables authors of standard documents to handle their documents from authoring to publishing in an end-to-end, “author-to-publish” fashion.

The canonical output of Metanorma is an XML file that represents an ISO/AWI 36100 model tree.

In addition, the Metanorma technology suite also provides:

  • standards metadata specification capability, based on ISO 36200, a set of metamodels for the development of organization-specific bibliographic item models from ISO 690, the international standard for citations and references

  • ability to encode concepts (and terms and definitions) in interoperable formats in accordance with the ISO 10241-1 and ISO 704 standards

  • ability to directly access certain information models types through the Ribose LutaML model parsing engine, including:

  • ability to author UML models through open-source model specification tools including Ribose LutaML or PlantUML.

With the above functionality, Metanorma is often used as an annotation system on information models.

Example

ISO/TC 184/SC 4/TF 1 uses Metanorma to annotate EXPRESS schemas resulting in model-derived documentation of EXPRESS schemas.

5.5.2.  Usage in OGC

“Metanorma for OGC” is the implementation of Metanorma for OGC. It has been approved as an official way to publish new OGC Standard documents since 2021-09-17, with Metanorma-based document templates subsequently approved by the OGC Document SubCommittee on 2022-02-25.

Metanorma for OGC documents are created in the Metanorma AsciiDoc format. Metanorma AsciiDoc is a textual syntax for preparing a ISO/AWI 36100 compliant document model tree which can be rendered in a variety of presentation formats. In OGC, the supported rendering formats are PDF, HTML, Microsoft Word, and ISO/AWI 36100 XML.

Metanorma for OGC differs from typical Metanorma in the following critical ways:

  • supports specification of OGC Standards metadata, including document types, stages, identifiers and authorship;

  • supports specification of OGC ModSpec (OGC 08-131r3) model instances through a specialized syntax.

Figure 16 shows the range of models used in Metanorma, including the OGC-specific use of OGC ModSpec.