Published

OGC Discussion Paper

OGC Guidance for the Development of Model-Driven Standards
OGC Discussion Paper

Published

Document number:23-040
Document type:OGC Discussion Paper
Document subtype:General
Document stage:Published
Document language:English

License Agreement

Use of this document is subject to the license agreement at https://www.ogc.org/license




I.  Abstract

This OGC Discussion Paper provides guidelines on how to create a specification of a conceptual model through use of a Unified Modeling Language (UML) editor and an AsciiDoc compiler. This document references Sparx Systems Enterprise Architect and the Metanorma AsciiDoc toolchain in examples that implement the OGC model-driven standards process, described in OGC 21-035r1.

II.  Keywords

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

ogcdoc, OGC document, MDA, model-driven


III.  Preface

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

IV.  Security considerations

No security considerations have been made for this document.

V.  Submitters

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

NameOrganizationRole
Ronald TseRibose LimitedEditor
Carsten RoensdorfOrdnance SurveyEditor
Allan JamiesonOrdnance SurveyEditor
Gobe HobonaOpen Geospatial Consortium (OGC)Contributor
Josh LiebermanOpen Geospatial Consortium (OGC)Contributor
Nick NicholasRibose LimitedEditor
Jeffrey LauRibose LimitedEditor

The editors also wish to acknowledge the support of the MUDDI (Model for Underground Data Definition and Integration) Standards Working Group and the feedback from the Conceptual Modeling Subgroup of the Architecture Domain Working Group.

1.  Scope

This Discussion Paper focuses on the development of Model-Driven Standards (MDS) using Sparx Systems Enterprise Architect and the Metanorma AsciiDoc toolchain. However, the guidelines could also be adapted for use with other UML and Asciidoc tools.

Development of this document was led by the MUDDI Standards Working Group, with the support of an Ordnance Survey-funded project in which this document served as Deliverable D1. The Scope of the guidelines, however, is not limited to underground data as many of the guidelines have been previously applied to other OGC Standards (e.g., CityGML).

2.  Conformance

Conformance with this document shall be checked using all of the tests specified in Annex A of this document.

3.  Normative references

The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

Policy SWG: OGC 08-131r3, The Specification Model — Standard for Modular specifications. Open Geospatial Consortium (2009).

Ronald Tse, Nick Nicholas: OGC 21-035r1, OGC Testbed-17: Model-Driven Standards Engineering Report. Open Geospatial Consortium (2022). http://www.opengis.net/doc/PER/t17-D022.

OMG UML 2.5, Unified Modeling Language. (2015). https://www.omg.org/spec/UML/2.5/About-UML.

OMG XMI 2.5.1, XML Metadata Interchange. (2015). https://www.omg.org/spec/XMI/2.5.1/About-XMI.

OMG OCL 2.4, Object Constraint Language. (2014). https://www.omg.org/spec/OCL/2.4/About-OCL.

4.  Terms and definitions

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.

4.1. conceptual model

CM ALTERNATIVE

model that defines concepts of a universe of discourse

[SOURCE: ISO 19101-1, Clause 4.1.5]

4.2. conceptual schema

formal description of a conceptual model (Clause 4.1)

[SOURCE: ISO 19101-1, Clause 4.1.6]

4.3. model-driven standard

MDS ALTERNATIVE

standard created using a model-driven architecture

[SOURCE: OGC 21-035r1, Clause 2.1.4]

4.4. model-driven architecture

MDA ALTERNATIVE

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

[SOURCE: OMG UML 2.5]

4.5. model authoring tool

software used for authoring a conceptual model (Clause 4.1)

[SOURCE: OGC 21-035r1]

4.6. platform-independent model

PIM ALTERNATIVE

data model that does not contain platform-specific concerns

[SOURCE: OGC 21-035r1]

4.7. platform-specific model

PSM ALTERNATIVE

data model that contains platform-specific concerns

[SOURCE: OGC 21-035r1]

4.8. logical model

implementation of one or more conceptual models (Clause 4.1) intended for a logical domain

4.9. model transformation

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

[SOURCE: OGC 21-035r1]

4.10. model conversion

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

[SOURCE: OGC 21-035r1]

4.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]

4.12. tagged value

attribute on a stereotype used to extend a UML model element

[SOURCE: OMG UML 2.5]

4.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]

5.  Introduction

The MDS process described in OGC 21-035r1 enables standardized documentation of conceptual models in UML, which could be platform-independent models (PIMs) or platform-specific models (PSMs).

In the past, UML modeling activity and the OGC authoring process used disparate tools, causing OGC authors and editors much difficulty in the synchronization of changes originating from either activity, as illustrated in Figure 1.

OGC 21-041r2 also discusses a number of challenges involved in UML modeling.

Figure 1 — Manual process for iterating a model-driven standard

As studied in OGC Testbed-17, OGC 21-035r1 has investigated several options in model-driven authoring, in which the OGC MUDDI SWG has decided to adopt and sponsor development of a particular approach that utilizes the following combination of tools:

This combination of tools can provide a streamlined development environment for OGC working groups developing conceptual model standards.

This document is meant to describe best practices that enable achievement of these benefits.

By utilizing described practices of this document, the streamlined automated MDS process can be achieved as shown in Figure 2.

Figure 2 — One-step automated process for iterating a model-driven standard

6.  Developing an MDS

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.

Figure 3 — Model-driven standard detailed publication flow

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.

Figure 4 — Model-driven standard information components

Requirements class 1: Identification of source components of the model-driven standard

Identifier/req/core
Target typeModel-driven standard
Conformance classConformance class A.1: /conf/core
Description

The source components of the model-driven standard has to be identified and understood.

Normative statementRequirement 1: /req/core/document

Requirement 1: Readiness of OGC document information used by the model-driven standard

Identifier/req/core/document
Included inRequirements class 1: /req/core
Statement

The OGC document information used in the model-driven standard is completed and made available to the model-driven standard in the Metanorma AsciiDoc format.

Requirement 2: Readiness of UML model information used by the model-driven standard

Identifier/req/core/uml
Statement

The UML model used in the model-driven standard is completed and made available to the model-driven standard in the OMG XMI format.

Requirement 3: Readiness of OGC document metadata information used by the model-driven standard

Identifier/req/core/metadata
Statement

The OGC document metadata used in the model-driven standard is completed and made available to the model-driven standard in the Metanorma AsciiDoc format.

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.  Technology and tools

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

The usage of UML in MDS lies with two aspects:

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

7.2.2.  Modeling elements

A detailed description of UML modelling capabilities can be found in OGC 21-035r1, Clause 5.1.

UML provides 3 basic modeling elements.

Package

A package is a defined collection of interrelated classes.

Class

A class is an abstract representation of a real-world object, which contains properties.

Property

A property represents an aspect of a class.

UML allows additional modeling extensions in the following 3 ways:

Stereotype

A defined set of properties that a Class can adopt as a whole, commonly representing a platform-specific or domain-specific concern. More than one stereotype can be adopted by a single Class.

Tagged Value

A structured key-value pair defined for a UML element, allowing the attachment of additional (custom) information to the UML element.

Constraint

A string that limits possible value assignments to the property.

The UML “Profile” is another mechanism that allows for the easy application of stereotypes.

Profile

A profile contains multiple UML stereotypes that a UML model can adopt.

7.3.  UML profiles for geospatial models

7.3.1.  General

A number of common UML profiles are used for geospatial UML modeling.

7.3.2.  UML Standard Profile

The UML Standard Profile is provided by the UML standard (OMG UML 2.5).

It provides the following stereotypes for Classes.

«Auxiliary»

A class that supports another class.

«Focus»

A class that specifies core logic or control with auxiliary classes that provide subordinate mechanisms.

«ImplementationClass»

An implementation class of a class.

«Metaclass»

A UML element that is meant to be extended.

«Realization»

A realization of an abstract UML element.

«Specification»

A specialization of a UML element.

«Type»

A data type.

«Utility»

A class that supports functionality of more than one class.

7.3.3.  GML

In the geospatial domain, stereotypes from the Geography Markup Language (GML) standard (OGC 07-036r1) are often applied to geospatial UML elements.

The GML standard provides the following Stereotypes that apply to Classes.

«CodeList»

A list of enumerated codes. Practically an enumeration.

«DataType»

A basic type of information.

«FeatureType»

A type of feature.

«Type»

A type of information.

«Union»

A union of two classes.

The GML standard provides the following Stereotypes that apply to Properties:

«property»

A basic property.

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.3.6.  ISO 19118:2011 Geographic information — Encoding

ISO 19118:2011 specifies the requirements for defining encoding rules for use in 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.

The profile provides the following stereotypes for Classes.

«BasicType»

“Defines a basic data type that has defined a canonical encoding.” (ISO 19118:2011, Clause C.2.1.2)

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

NOTE 1:    For translation into XML, ISO 19118:2011, Clause C.5.2.1.1 states: “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 xmlschema-2).”

NOTE 2:    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 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»

“Defines a service interface and shall not be encoded.” (ISO 19118:2011, Clause C.2.1.2)

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.

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:

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

Figure 7 — Models used in Metanorma

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.

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.  Basics of Enterprise Architect

8.1.  Launch screen

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