6.1.  General

The creation of an MDS must be planned. An MDS involves the synthesis of multiple data sources into a single one, therefore the MDS creator must be aware of the integration points and limitations of such synthesis process.

While the MDS process is meant to be a streamlined, automated process, it is nonetheless dependent on the interaction of multiple state-of-the-art technologies and requires the MDS creator to have a thorough understanding of the MDS technologies and techniques involved.

The full process is shown in Figure 3.

6.2.  Data sources

Before embarking on an MBS, it is necessary for the MDS creator to know what kind of components there are.

In OGC, a model-driven standard is typically created with the following components:

• OGC document information in Metanorma AsciiDoc (scope, bibliography, etc.);

• UML model information in OMG XMI format (the EA UML models with annotations); and

• OGC ModSpec information in Metanorma AsciiDoc format (requirements, conformance tests).

These components read into Metanorma using a defined processing configuration, and are then combined in Metanorma to form the MDS.

The resulting MDS represented in the Metanorma format will be expressed in the models provided in Figure 4.

6.3.  Principles

OGC 21-035r1 states that generation of an MDS involves the following steps:

• Export: Making the information model available for processing;

• Authoring: Making the supplementary truth available for processing;

• Data parsing: Parsing the truth of the model into derived truth in the document;

• Integrating: Merging derived and supplementary truth into the target document; and

• Rendering: Generating human-consumable presentations of the target document.

This document provides practices that allow the MDS author to plan out how the MDS automation process looks like across all these stages.

6.4.  Export

Making source data available for the MDS involves exporting the information models in a standardized interoperable format from the model authoring tool.

For an OGC MDS document:

• the primary truth is typically a set of UML models; the initial step in processing is to export these UML models into interoperable XMI files; and

• the secondary set of source data are the UML diagrams accompanying the UML models; these diagrams provide visual representations of UML classes described in the XMI files.

6.5.  Authoring

This information is written in Metanorma, using the OGC flavor of the Metanorma AsciiDoc markup language.

Supplementary information in an MDS normally includes the following.

• Material such as bibliographies, terminological definitions, tutorial guidance, annexes, and prefatory material, which form part of a document presenting and explaining the model.

• Metadata about the document, such as keywords and identifiers.

• Requirements conforming to OGC ModSpec.

Where the supplementary information references specific model artifacts (annotating them), cross-references from Metanorma to the model become necessary; those cross-references are part of the integration of derived and supplementary truth.

6.6.  Data parsing

Processing the XMI file is done under the Metanorma approach to MDA by LutaML. LutaML returns to Metanorma an array of objects, one for each of the objects in the source file parsed by LutaML, with a plugin structure to deal with the range of formats LutaML is called on to process (lutaml-xmi, in this instance).

Metanorma then uses Liquid directives to iterate through those objects, and insert information from them into Metanorma AsciiDoc templates. These templates are how information from the model is incorporated into the MDS as derived truth.

By using LutaML commands inside Metanorma, such as the lutaml_uml_datamodel_description command, UML class information is parsed from a nominated XMI file and transformed into Metanorma AsciiDoc.

Configuration files were used to specify which packages to render for each command call, in which sequence, and how to display them.

For complex documents such as CityGML 3.0 that require a non-default way of rendering, additional configuration can be used to achieve such results.

6.7.  Integrating

A wide range of information is integrated into the target document.

This information is typically organized into separate directories in the source repository.

• The main Metanorma AsciiDoc document (nn-mmm.adoc), containing document metadata and directives to include sections contained in the document.

• The Metanorma AsciiDoc documents for each section in the standard (sections/*.adoc).

• Generic ModSpec requirements (not specific to the information models), each expressed as a separate file of Metanorma AsciiDoc, are included into the section documents at the appropriate point (abstract_test, recommendations, requirements).

• Non-model-generated images (images) and figures (figures) are included in the document as supplementary truths, as distinct from the UML diagrams exported into /xmi-full/Images as derived truths.

Supplementary truth is incorporated into the target document through standard AsciiDoc commands:

• image:: for images and figures

• include:: for content.

6.8.  Rendering

Once the Metanorma AsciiDoc source is assembled out of its component truths, it can then be rendered using Metanorma into a number of output formats.

• Metanorma Semantic XML, capturing the structure and meaning of the standards document, and following the document model in ISO/AWI 36100.

• Metanorma Presentation XML, denormalizing the structure of the standards document in preparation for rendering, including resolving cross-references and generating auto-numbering.

• HTML

• PDF

• Microsoft Word

7.1.  General

Practices described in this document are meant for OGC working group participants fluent in the development of:

• Conceptual models described using UML Class Diagrams; and

• OGC authoring practices.

This document does not delve into details of those areas — readers may wish to consult other literature for the full understanding of the practices described.

7.2.  Conceptual models described using UML Class Diagrams

7.3.  UML profiles for geospatial models

7.3.4.  ISO 19100-series profile: Conceptual schema language (ISO 19103:2015)

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.

It includes 6 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 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 5.

Figure 5 — ISO 19103:2015 stereotypes and keywords

7.3.5.  ISO 19100-series profile: Rules for application schema (ISO 19109:2015)

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 2 stereotypes and 3 tagged values.

«ApplicationSchema»

(package) stereotype

«FeatureType»

(class) stereotype

The following 3 tagged values 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 6:

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

7.4.  Sparx Systems Enterprise Architect

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

EA Version 16 is a Windows application, it can be run in 32-bit or 64-bit mode on Windows, and can be run on other platforms using CrossOver (which is based on WINE technology) with 32-bit emulation.

7.5.  Metanorma for OGC

Metanorma is an open-source framework for creating and publishing standardization artifacts with the focus on semantic authoring and flexible output support.

“Metanorma for OGC” is an OGC-specific implementation that has been approved as an official way to publish new OGC Standard documents since 2021-09-17. Metanorma-based document templates have been 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.

At its core, Metanorma provides a model-based documentation system and prioritizes automation, through the following features:

• a set of standard document metamodels (according to ISO/AWI 36100) that allows different standardization bodies to create their own standardized deliverable model, which in turn relies on the following standardized models:

  • ISO/PWI 36200 standards metadata specification metamodels;

  • ISO 690 bibliographic and citation item models;

  • ISO 10241-1 and ISO 704 concept organization and terminology models;

• a standard XML serialization (ISO/PWI 36300) for machine-readable standardization documents; and

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

For OGC usage, it provides the following additional features:

• Rendering outputs in PDF, HTML, Microsoft Word, and ISO/AWI 36100 XML formats;

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

• Support for specification of OGC ModSpec (OGC 08-131r3) model instances through a specialized syntax; and

• For OGC MDS usage, Metanorma supports navigation for information models in the OMG UML/XMI format (OMG UML within OMG XMI in XML format, OMG UML 2.5, OMG XMI 2.5.1) generated from Enterprise Architect, through the LutaML information model parser.

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

7.6.  LutaML information model interface

LutaML is an initiative grown out of Metanorma that allows parsing various machine-interpretable information models. LutaML adopts an extensible processing architecture to allow parsing different information model languages, through LutaML extensions.

Supported LutaML extensions include the following.

• EXPRESS, as specified in ISO 10303-11, is used heavily in smart manufacturing, Industry 4.0 use cases and in BIM, where EXPRESS itself served as the foundation of the IFC classes. The LutaML EXPRESS extension is available at: https://github.com/lutaml/lutaml-express.

• OMG UML in OMG XMI, which is the canonical format of representing UML models within XMI, an XML language defined by OMG OMG XMI 2.5.1. The LutaML XMI extension is available at: https://github.com/lutaml/lutaml-xmi.

• Sparx Systems Enterprise Architect XMI, the proprietary extension of Sparx Systems Enterprise Architect for the representation of UML. The LutaML Enterprise Architect-specific XMI extension is implemented within the LutaML XMI extension.

• LutaML UML, which is an ASCII syntax used to author OMG UML-compliant UML models with the possibility to be exported into OMG XMI format. The LutaML UML extension is available at: https://github.com/lutaml/lutaml-uml.

  NOTE:    The LutaML UML language is documented at https://github.com/lutaml/lutaml-uml/blob/master/LUTAML.adoc

LutaML supports the dynamic referencing of elements from within a UML model. For example, individual UML classes, attributes, stereotypes, Enterprise Architect diagrams, can all be referenced through the unified interface provided by LutaML.

Collection filtering, such as to find UML classes that match certain UML stereotype, is also supported.

LutaML-XMI is the LutaML extension that parses OMG XMI 2.5.1 into a LutaML-UML model.

Of course, each format that it reads in requires a separate plug-in to be written to process it, and the processing of different formats can be highly specialized work. That makes it important for MDA to coalesce around standard ways of expressing models as much as possible, to minimize the up-front effort of developing a new plug-in to read a new model format.

The LutaML-XMI plug-in supports parsing the proprietary XMI files generated by Sparx Systems Enterprise Architect, incorporating details only available in the vendor proprietary XML portion of the XMI file.

This plug-in has been successful in recognizing the classes it expresses, their attributes, and the relations between classes, as documented in OGC 21-035r1.

7.7.  Metanorma LutaML plugin

Metanorma interfaces with information models through the Metanorma LutaML plugin (https://github.com/metanorma/metanorma-plugin-lutaml). This plugin is used to render information models in human-readable formatting for MDS.

The plugin provides a set of commands to be used within a Metanorma authoring context that invokes LutaML processing of a specified file, which generates a representation of that data usable within Metanorma.

Model navigation, dynamic referencing and collection filtering capabilities to UML models are accessible within a Metanorma document through the corresponding LutaML commands.

By default, LutaML is invoked to parse an external information model through a Metanorma AsciiDoc block command, which requires the input of the following information:

• as an argument, name of the source information model file;

• as an argument, the named context, which is the object variable name into which the data file contents are parsed, as object attributes, recursively; and

• as the contents of the block, a template, in Metanorma AsciiDoc format with the Liquid template language (https://shopify.github.io/liquid/).

In effect, this provides a “meta-authoring” environment from within Metanorma. In particular, the template language allows the attributes parsed by LutaML to be incorporated in the block under the command.

8.1.  Launch screen

Once the EA application is launched with a model file, the screen is shown as in Figure 8.