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.

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

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.

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

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

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

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

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

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

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

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

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

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.

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

  • EXPRESS (ISO 10303-11)

  • OMG UML within OMG XMI (OMG UML 2.5, OMG XMI 2.5) and Enterprise Architect generated XMI

  • XSD (W3C TR xmlschema-1)

• 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

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.

5.5.3.  Specification of ModSpec model instances

[requirement]
====
[%metadata]
label:: /req/core

Requirement text.
====

[recommendation]
[permission]
[requirements_class]
[conformance_test]
[conformance_class]
[abstract_test]
// [abstract_test] is short for [conformance_test,%abstract]

5.5.3.4.  Examples of rendered ModSpec instances

The following examples demonstrate how ModSpec instances are represented in OGC Standards.

Example 1 — ModSpec example: OGC 20-010 (CityGML 3.0) Requirements Class 1

[requirements_class]
====
[%metadata]
label:: http://www.opengis.net/spec/CityGML-1/3.0/req/req-class-core
subject:: Implementation Specification

inherit:[<<iso19103>>]
inherit:[<<iso19107>>]
inherit:[<<iso19109>>]
inherit:[<<iso19111>>]
inherit:[<<iso19123>>]
inherit:[<<xal2,OASIS xAL v3.0>>]
inherit:[req/req-class-core]
====

Example 2 — ModSpec example: OGC 20-010 (CityGML 3.0) Requirement 1

[requirement,type="general",label="/req/core/classes"]
====
For each UML class defined or referenced in the Core Package:

[.component,class=part]
--
The Implementation Specification SHALL contain an element which represents the same concept as that defined for the UML class.
--

[.component,class=part]
--
The Implementation Specification SHALL represent associations with the same source, target, direction, roles, and multiplicities as those of the UML class.
--

[.component,class=part]
--
The implementation Specification SHALL represent the attributes of the UML class including the name, definition, type, and multiplicity.
--

[.component,class=part]
--
The implementation Specification SHALL represent the attributes of all superclasses of the UML class including the name, definition, type, and multiplicity.
--

[.component,class=part]
--
The implementation Specification SHALL represent the associations of all superclasses of the UML class including the source, target, direction, roles, and multiplicity.
--

[.component,class=part]
--
The Implementation Specification SHALL specify how an implementation observes all constraints the Conceptual Model imposes on the UML class.
--
====

Example 3 — ModSpec example: OGC 20-010 (CityGML 3.0) Permission 1

[permission,label="/per/core/classes"]
====
For each UML class defined or referenced in CityGML Conceptual Model:

[.component,class=part]
--
An Implementation Specification MAY represent that class as a null class with no
attributes, associations, or definition.
--

[.component,class=part]
--
An Implementation Specification MAY represent an association of the UML class
with a null association.
--

[.component,class=part]
--
An Implementation Specification MAY represent an attribute of the UML class with
a null attribute.
--

[.component,class=part]
--
Whenever a null element is used to represent a concept from the Conceptual
Model, the Implementation Specification SHOULD document that mapping and provide
an explanation for why that concept was not implemented.
--
====

Example 4 — ModSpec example: OGC 20-010 (CityGML 3.0) Requirement 2

[requirement,type="general",label="/req/core/isorestrictions"]
====
ISO classes used in the CityGML Conceptual Model are subject to the following restrictions:

[.component,class=part]
--
Classes derived from the GM_Solid class (ISO 19107) SHALL only include exterior
boundaries. (The `interior` association on the GM_SolidBoundary shall not be
defined)
--
====

Example 5 — ModSpec example: OGC 20-010 (CityGML 3.0) Abstract Test 2, which corresponds to Requirement 2

[abstract_test]
====
[%metadata]
label:: /ats/core/isorestrictions
subject:: <<req_Core_iso-restrictions,/req/core/isorestrictions>>

[.component,class=test-purpose]
--
To validate that none of the restrictions which the CityGML Conceptual Model
imposes on ISO classes are violated by an Implementation Specification.
--

[.component,class=test method type]
--
Manual Inspection
--

[.component,class=test method]
=====
[.component,class=step]
--
For each instance of the GM_Solid class, validate that there are no interior
boundaries associated with that instance.
--

[.component,class=step]
--
For each instance of a class descended from the GM_Solid class, validate that
there are no interior boundaries associated with that instance.
--
=====
====

5.5.4.  Specification of terminology entries

Metanorma supports the specification of terminology entries (concepts) as instances of the information models described in ISO 10241-1 and ISO 704.

Concepts can be sourced from other standards the OGC definitions server as well as other termbases, such as the IEV.

Example 1 — Concept example: OGC 20-010 (CityGML 3.0) 4.1.6, sourced from ISO 19101-1

==== conceptual model

model that defines concepts of a universe of discourse

[.source]
<<iso19101-1,clause=4.1.5>>

Example 2 — Concept example: OGC 20-010 (CityGML 3.0) 4.1.8, sourced from the OGC Definitions Server

==== Implementation Specification

Specified on the OGC Document Types Register

[.source]
<<OGCDTR,locality:URI="http://www.opengis.net/def/doc-type/is">>

OGC Standards often have an informative “Glossary” that presents definitions of terms. An example of term definition within the “Glossary” is given here.

Example 3 — Concept example: OGC 20-010 (CityGML 3.0) C.1.2.3, sourced from ISO 19111

=== CC_CoordinateOperation

A mathematical operation on coordinates that transforms or converts coordinates
to another coordinate reference system.

[.source]
<<iso19111>>

5.5.5.  Specification of bibliographic references

Metanorma supports the specification of bibliographic entries as instances of the information models described in ISO 690.

Example 1 — Bibliographic item example from OGC 20-010 (CityGML 3.0) of “OGC 15-001r4”

[bibliography]
== Bibliography

* [[[three-dps_citation,OGC 15-001r4]]], Hagedorn, B., Thum, S., Reitz, T.,
Coors, V., Gutbell, R.: _OGC® 3D Portrayal Service 1.0_, Open Geospatial
Consortium, Available from
https://docs.opengeospatial.org/is/15-001r4/15-001r4.html[OGC Doc. 15-001r4].

Metanorma provides auto-fetch functionality for a number of publications from Standards Development Organizations (SDO), including OGC.

The above example will be still rendered identically given the following information, as the relevant metadata about the publication identified is retrieved automatically.

Example 2 — Bibliographic item example from OGC 20-010 (CityGML 3.0) of “OGC 15-001r4” with auto-fetch

[bibliography]
== Bibliography

* [[[three-dps_citation,OGC 15-001r4]]]

7.1.1.  General

ShapeChange is a powerful, extensible capability with many configuration choice-points involved in designing a set of Conceptual Model transformations and technology targets. It is used by OGC to generate PSMs from PIMs. While individual choice-points and their controls are generally well-documented, ShapeChange has a steep learning curve for the novice. In this ER we provide some “cookbook” recipes to assist new users for specific use-cases.

ShapeChange automatically validates the specified configuration on startup (see: https://shapechange.net/get-started/config/validation-of-the-configuration/). This prevents configuration mistakes that would otherwise only be noticed during or after processing a model.

ShapeChange includes a powerful logging capability that records both Warnings and Errors associated with each rule application. Errors require corrections to the input model, or possibly the processing configuration; Warnings may be either in the nature of advice, or an issue that ShapeChange may attempt to resolve by introducing a model assumption and then proceeding. In many cases that assumption is best avoided by improving the model so that it is unambiguous.

As a deterministic rule-based system ShapeChange requires significant internal consistency in an input Conceptual Model for best outcome; the quality of the resulting PSM is directly determined by the quality and completeness of the PIM – particularly the proper application of UML Stereotypes and Tagged Values. Such consistencies may not be present in existing models that were developed for the sole purpose of diagrammatic presentation in standards documents; such models may require enhancement in order to be useful for deriving corresponding PSMs.

ShapeChange includes the ability to verify the correctness of a Conceptual Model with respect to the requirements of UML (https://www.omg.org/spec/UML/2.5.1/About-UML/), ISO 19103:2015 (Conceptual schema language), and ISO/IEC 19507:2012 (OCL); it is thus useful as a PIM validation tool even in circumstances in which derivation of technology-specific implementation specifications is not intended.

7.1.2.  Usage

ShapeChange is an open-source implementation of the MDA methodology that has emerged as a key technological underpinning in many geospatial data modeling 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 ShapeChange initiatives going back to OGC Testbed-2 (OGC 04-100) can be found at https://shapechange.net/about/background-documents/

ShapeChange is a portable Java-based application. It has no native graphical interface. All control of ShapeChange processing is achieved through the use of configuration files that are XML Instance documents. The location of the key configuration file is the only ShapeChange-specific command-line parameter. Log files are also XML instance documents (and, for convenience, corresponding HTML files are generated for ready use in a browser where they enable presentation-filtering).

ShapeChange is documented at https://shapechange.net/. Its source code repository is established at https://github.com/ShapeChange/ShapeChange. It may be extended: https://shapechange.net/get-started/how-to-extend-shapechange/

A typical ShapeChange use-case begins with opening and reading a UML model from a Sparx Systems Enterprise Architect (EA) repository. In order to do so, EA must be installed on the computer that executes ShapeChange.

Each EA installation comes with an SSJavaCOM.dll and/or SSJavaCOM64.dll, which must be installed correctly in order for ShapeChange to access local EA repositories. For further installation details, see: http://shapechange.net/get-started/

In the case that ShapeChange is intended to be executed other than under Microsoft Windows with an EA repository, there are means to losslessly convert a Conceptual Model stored in an EA repository to the portable ShapeChange XML (SCXML) format for use in other environments (e.g., MacOS or Linux). There are also means to losslessly convert a Conceptual Model stored in an SCXML file into the EA repository format (under Microsoft Windows with an EA installation present).

7.1.3.  UML profiles

ShapeChange supports the ISO 19100-series of UML Profiles as well as additional package, class, and property stereotypes; see: https://shapechange.net/app-schemas/uml-profile/#Stereotypes

ShapeChange supports an extensive range of tagged values, well beyond the base set specified in ISO 19109:2015 and ISO 19136-1:2020; see: https://shapechange.net/app-schemas/uml-profile/#Tagged_Values

OCL Constraints (a restricted subset of the full language) are parsed and used for the purpose of generating Schematron (ISO/IEC 19757-3 “Information technology — Document Schema Definition Languages (DSDL) — Part 3: Rule-based validation using Schematron”) assertions; see: https://shapechange.net/targets/xsd/extensions/ocl/

7.1.4.  Descriptors

It is common practice to include a variety of descriptive information about elements in a UML model, e.g., aliases, codes, definitions, or descriptions. In order for ShapeChange transformations or targets to process each of these types of information distinctly they must be individually documented. UML tagged values are an ideal mechanism for documenting such information, however their application and use in UML modeling tools tends to be inconveniently supported and erratically employed by modelers.

UML modeling tools typically provide a single “notes” field whose value is prominently displayed and easily edited. Sparx Systems Enterprise Architect (EA) includes both a “notes” field and a separate “alias” field. A panel displaying the “notes” field can be pinned to the EA user interface for ready access whenever a model element is selected. In consequence of this field ubiquity, it is common practice in some modeling communities to populate the “notes” field using fixed separators in order to distinguish the different descriptors that have been combined into a single structured string for documenting descriptive information about an element.

The ISO/TC 211 Harmonized Model Maintenance Group (HMMG: https://github.com/ISO-TC211/HMMG) uses the all-in-one approach based on the “notes” field rather than discrete tagged values. In some cases (e.g., package “ISO 19170 Discrete global grid systems”) text styling/formatting is introduced in order to improve the presentation within the EA element editor.

To support both tagged value and structured “notes” approaches, ShapeChange implements a set of descriptors for commonly types of element information (e.g., “alias”, “definition”, “description”, “documentation”, “example” and “primaryCode”); see: https://shapechange.net/get-started/config/input/#Descriptor_sources

ShapeChange provides mechanisms to parse the EA element “notes” into descriptors as well as to load descriptors from user-specified tagged values. A ShapeChange transformer (https://shapechange.net/transformations/descriptor-transformer/) may be used to manipulate descriptors during model processing. Target processors employ these descriptors in encoding-specific manners.

A simple ShapeChange configuration to load descriptors from an EA project file would include the following lines:

<descriptorSources>
  <DescriptorSource descriptor="documentation" source="ea:notes"/>
  <DescriptorSource descriptor="alias" source="ea:alias"/>
</descriptorSources>

Figure 21 — ShapeChange configuration to load descriptors from an EA project file

7.1.5.  Rules

ShapeChange is a rule-based tool that manipulates an in-memory representation of a UML (class diagram) model. A rule specifies an action to be taken when matching a pattern in a Concept Model. Sets of rules are used either to transform one UML model to another (see: https://shapechange.net/transformations/#Rules), or, given a UML model, to generate a target encoding (in general see: https://shapechange.net/targets/#Encoding_Rules; for the XML Schema target in particular, see: https://shapechange.net/targets/xsd/#Specifying_Encoding_Rules and https://shapechange.net/targets/xsd/extensions/#Using_the_non-standard_conversion_rules).

For example, in support of the platform-specific GML 3.2 encoding ShapeChange specifies twenty encoding rules based on the encoding requirements of ISO 19136-1:2020. Those encoding requirements are summarized in Annex A: UML-to-GML application schema encoding rules. These encoding rules are collectively referenced within ShapeChange as “iso19136_2007”. ShapeChange can be configured to include additional rules (e.g., rule-xsd-cls-basictype-list was added when processing the revised CityGML 3.0 Conceptual Model) as well as, in some cases, controlling the behavior of individual rules using configuration parameters.

Table 4 — Rules used to encode GML 3.2

The ShapeChange XML Schema target natively supports four sets of encoding rules (for GML 3.2, GML 3.3, ISO 19115 metadata and ISO 19110 feature catalogues, and Sensor Web Enablement (SWE) Common Data Model 2.0); see: https://shapechange.net/targets/xsd/#Encoding_Rules .

Additional well-known sets of encoding rules are documented in https://shapechange.net/resources/config/StandardRules.xml .

The set of encoding rules to apply in a model conversion may be provided in two ways: as a conversion-wide default (specified in the project configuration file), or as tagged values on individual model elements to control the conversion of those specific elements. To identify the applicable set of encoding rules for a model element (package, class, or property), a tagged value xsdEncodingRule may be specified on that element. The application of the specified set of encoding rules follows the usual containment rules of UML where, e.g., a specification applied to a package also applies to its contained classes and their properties, unless overridden by a different value assigned to one of those elements.

If the tagged value xsdEncodingRule is not specified anywhere in the UML model, then the ShapeChange defaultEncodingRule parameter specified for the target encoding in the project configuration file is applied. In many cases a single set of encoding rules will apply throughout a model; however complex models incorporating components from external sources may need to assign different sets of encoding rules to those externally-defined model components.

7.1.5.1.  Processing

ShapeChange supports a simple, yet powerful, data-flow processing model in which operations on UML models are chained starting from the input model and ending with one or more target encodings. As illustrated in Figure 22, ShapeChange can apply a number of transformations to an input model, before generating target representations for it.

ShapeChange validates the loaded Conceptual Model with respect to the requirements of UML (https://www.omg.org/spec/UML/2.5.1/About-UML/), ISO 19103:2015 (Conceptual schema language), and ISO/IEC 19507:2012 (OCL); it is thus useful as a model validation tool even in circumstances in which derivation of technology-specific implementation specifications is not intended. In such a configuration no transformers or targets are required or used.

Figure 22 — ShapeChange processing model

Transformations (see: https://shapechange.net/transformations/) are applied to a given base model. This can be the input model (e.g., from an EA project file) or the result of another transformation. It is thus possible to create a chain or tree of model transformations. ShapeChange includes a wide variety of model transformations; particularly powerful is the Flattener (see: https://shapechange.net/transformations/flattener/) which may be used to simplify a model, e.g. up to the point where all complex data structures have been resolved to feature type properties whose range type is either a simple type (like Integer, Boolean or CharacterString), a code list, or an enumeration. An example use of the Flattener transformation with ArcGIS geodatabase models is documented at: https://shapechange.net/targets/arcgis-workspace/pre-processing-flattening/

Another commonly employed transformation is the Association Class Mapper (see: https://shapechange.net/transformations/association-class-mapper/) which maps a UML association class into a semantically equivalent UML class and pair of associations, as defined by ISO 19136-2:2015.

A given target configuration may be (re)used to process the output models from multiple transformers. Originally the only target of ShapeChange was the GML-based application schema, represented as a set of XML Schema documents. Currently there are many other targets that ShapeChange may be configured to produce — including non-GML XML Schema documents (e.g., the encoding of ISO 19115-1:2014 “Geographic information — Metadata — Part 1: Fundamentals”; see: https://shapechange.net/targets/xsd/iso19139/). Additional targets include, e.g., the ArcGIS Workspace, JSON Schema, Model Export (portable SCXML format), ontology (based on ISO 19150-2), SQL DDL, and UML Model (EA project file).

7.1.6.  Configuration

The primary mechanism for providing arguments to ShapeChange is the project configuration file. A ShapeChange project configuration file is an XML Instance document which conforms to a custom XML Schema (https://shapechange.net/resources/schema/ShapeChangeConfiguration.xsd).

The root element of the configuration file is the <sc:ShapeChangeConfiguration> element. The file is then divided into various “functional elements”; key elements are:

• The <sc:input> element (https://shapechange.net/get-started/config/input/) defines the source of the model and some parameters controlling its interpretation.

• The <sc:log> element (https://shapechange.net/get-started/config/log/) defines logging parameters.

• The optional <sc:transformers> element (https://shapechange.net/get-started/config/transformers/) defines which transformations shall be applied to an input model, including their chaining, each in accordance with a specified set of parameters and/or rules.

• The optional <sc:targets> element (https://shapechange.net/targets/) specifies the configuration for each target format, e.g., XML Schema.

A project configuration file to load an EA project, create a processing log, and generate a ShapeChange XML (SCXML) file would be specified as in Figure 23:

<?xml version="1.0" encoding="UTF-8"?>
<ShapeChangeConfiguration
  xmlns="http://www.interactive-instruments.de/ShapeChange/Configuration/1.1"
  xmlns:sc="http://www.interactive-instruments.de/ShapeChange/Configuration/1.1"
  xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.interactive-instruments.de/ShapeChange/Configuration/1.1
https://shapechange.net/resources/schema/ShapeChangeConfiguration.xsd">

  <input id="INPUT">
    <parameter name="inputModelType" value="EA7" />
    <parameter name="inputFile" value="CityGML_3.0_TB17_0712.eap" />

    <parameter name="constraintLoading" value="enabled" />
    <parameter name="appSchemaNameRegex" value=".*" />

    <xi:include href="http://shapechange.net/resources/config/StandardAliases.xml"/>
    <xi:include href="http://shapechange.net/resources/config/StandardTagAliases.xml"/>
  </input>

  <log>
    <parameter name="reportLevel" value="INFO" />
    <parameter name="logFile" value="generateSCXML_log.xml" />
  </log>

  <targets>
    <Target inputs="INPUT" mode="enabled"
class="de.interactive_instruments.ShapeChange.Target.ModelExport.ModelExport">
      <targetParameter name="outputFilename" value="CityGML_3.0_TB17_0712"/>
      <targetParameter name="schemaLocation" value="."/>
      <targetParameter name="sortedOutput" value="true"/>
      <targetParameter name="defaultEncodingRule" value="export"/>
      <xi:include href=" http://shapechange.net/resources/StandardRules.xml" />
    </Target>
  </targets>
</ShapeChangeConfiguration>

Figure 23 — Project configuration file to generate a ShapeChange XML (SCXML) file

The ShapeChange Model Export target is documented at: https://shapechange.net/targets/model-export/

The ShapeChange source tree includes an extensive set of unit tests (see: https://shapechange.net/get-started/examples/) that include ShapeChange configurations for loading a model, transforming it, and deriving target representations. They also include sample UML models, principally as EA project files but sometimes also as portable SCXML files.

7.1.7.  Configuration resources

ShapeChange supports the use of <xi:include> in project configuration files, allowing for decomposition and modularization of configuration parameters. There are numerous pre-defined ShapeChange-associated resources for use in preparing ShapeChange configuration files published at: https://shapechange.net/resources/config/

The intended use of each resource file is described at: https://shapechange.net/get-started/contents/

Five of these resource files are either included by reference into typical ShapeChange project configurations, or serve as the basis for customized replacements:

• <xi:include href="http://shapechange.net/resources/config/StandardAliases.xml"/>: Defines mappings from domain-specific stereotypes of packages, classes, and properties to well-known stereotypes recognized by ShapeChange. For example, mapping from «applicationSchema» to «Application Schema», and from «interface» to «Type».

  NOTE 1  See: https://shapechange.net/get-started/config/input/#Stereotype_aliases

• <xi:include href="http://shapechange.net/resources/config/StandardTagAliases.xml"/>: Defines mappings from domain-specific tagged values of packages, classes, and properties to well-known tagged values recognized by ShapeChange. For example, from alphaCode to primaryCode, or from characterLength to length.

  NOTE 2  See: https://shapechange.net/get-started/config/input/#Tag_aliases

• <xi:include href="http://shapechange.net/resources/config/StandardRules.xml"/>: Defines sets of rules intended to be used together for a common purpose, e.g., a set of rules for encoding CityGML Application Domain Extensions (ADE):

  
  
  <EncodingRule name="citygml-ade" extends="iso19136_2007">
    <rule name="req-xsd-cls-suppress-supertype"/>
    <rule name="req-xsd-cls-suppress-subtype"/>
    <rule name="req-xsd-cls-suppress-no-properties"/>
    <rule name="rule-xsd-cls-suppress"/>
    <rule name="rule-xsd-cls-adeelement"/>
    <rule name="rule-xsd-cls-mixin-classes"/>
    <rule name="rule-xsd-prop-initialValue"/>
  </EncodingRule>

  Figure 24 — Rules for encoding CityGML Application Domain Extensions (ADE) as an example of StandardRules.xml

  NOTE 3  See https://shapechange.net/targets/xsd/#Specifying_Encoding_Rules

• <xi:include href="http://shapechange.net/resources/config/StandardNamespaces.xml"/>: Defines XML namespaces commonly imported by GML 3.2/3.3 application schemas, e.g., gco, gml, xlink, and xsi. See: https://shapechange.net/targets/xsd/#Namespace_Identifiers

• <xi:include href="http://shapechange.net/resources/config/StandardMapEntries.xml"/>: Specifies map entry files for use in target encodings; individual entries express how to encode a key (usually primitive) UML model element using a “native” encoding type. The default resource specifies a list of map entry files for GML 3.2 (and above) schema encoding:

  
  
  <xi:include href="StandardMapEntries_iso19136_2007.xml"/>
  <xi:include href="StandardMapEntries_iso19139_2007.xml"/>
  <xi:include href="StandardMapEntries_sweCommon.xml"/>
  <xi:include href="StandardMapEntries_iso19107.xml"/>
  <xi:include href="StandardMapEntries_iso19108.xml"/>
  <xi:include href="StandardMapEntries_iso19111.xml"/>
  <xi:include href="StandardMapEntries_iso19115.xml"/>
  <xi:include href="StandardMapEntries_iso19123.xml"/>
  <xi:include href="StandardMapEntries_iso19156.xml"/>
  <xi:include href="StandardMapEntries_gmlcov.xml"/>

  Figure 25 — Listing of map entry files for GML 3.2 schema encoding

  Individual map entry files in this list specify standard XML Schema implementations for many types from ISO/TC 211 and OGC Standards that are used in application schemas, e.g., CharacterString, CV_RectifiedGrid, DateTime, Length, and TM_Position.

  Example

  <XsdMapEntry type="Real" xsdEncodingRules="iso19136_2007 gml33"
                            xmlPropertyType="double" xmlType="double"
                            xmlTypeType="simple" xmlTypeContent="simple"/>

  The format and use of <sc:XsdMapEntry> is documented at: https://shapechange.net/targets/xsd/#XSD_Map_Entries

  The resource StandardJsonMapEntries.xml serves a similar purpose. Its format and use is documented at: https://shapechange.net/targets/json-schema/#Map_Entries

Additional mappings, rule sets, and XML namespaces may be defined in project configurations — or added to local copies of these resource files.

7.2.1.  General

Metanorma is an open-source, model-based documentation system that supports the MDA approach.

It relies on LutaML, a universal information model parser, to allow navigating information models right from within the document model.

As part of the Metanorma suite, LutaML and the Metanorma-LutaML plugin have been developed iteratively to deal with the novel workflow of incorporating information model content into a target human-readable MDS document as described in this ER.

The model transformation results in a series of document elements incorporated in the MDS, including diagram rendering and tabular presentations.

7.2.2.  LutaML

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:

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

7.2.3.  LutaML for XMI

LutaML-XMI is the LutaML extension that parses OMG XMI 2.5 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 Clause 7.2.

7.2.4.  Metanorma LutaML plugin

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

It 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;

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

7.2.5.  Usage example

LutaML within Metanorma is used in the following manner.

Figure 26 shows an instance of the [lutaml] command in Metanorma, which instructs LutaML to process the file in path/to/filelocation, and pass the results of the parse into the object package. The body of the command then iterates through the contents of package, and generates Metanorma AsciiDoc using values from the variable.

[‌lutaml,path/to/filelocation,package]
--
{% for diagram in package.diagrams %}
[[figure-{{ diagram.xmi_id }}]]
.{{ diagram.name }}
image::{{ base_path }}/{{ diagram.xmi_id }}.{{ format | default: 'png' }}[]

{% if diagram.definition %}
{{ diagram.definition | html2adoc }}
{% endif %}
{% endfor %}
--

Figure 26 — Rendering of a UML package under LutaML

• The directives in {% …​ %} are Liquid processing directives, including loops and conditionals.

• The variables referenced in the directives, and invoked through {‌{ …​ }}, are attributes parsed by LutaML from the given source files. For example, package.diagrams is the list of all diagrams under the current package, and diagram is a loop variable containing the parsed information for one such diagram.

• The variable diagram contains attributes of its own which LutaML has parsed; the XMI ID attribute for the diagram,

  • {‌{ diagram.xmi_id }} is used in conjunction with the LutaML parameter {‌{ image_base_path }} in order to define the file location of the associated image file.

  • {‌{ diagram.xmi_id }} is also used with the prefix figure- to define the anchor for the image ([[…​]]), to be used in cross-references.

  • The markup .{‌{ diagram.name }} is used to insert the name attribute of the diagram as the image caption.

While the [lutaml] command can be used individually to build up an MDS, its use would be highly repetitive, as an MDS will render each UML class and package it is applied to in the same way.

For that reason, Metanorma defines the command [lutaml_uml_datamodel_description] to iterate through a sequence of UML packages, rendering each in a consistent way. The template that would be used for each class is predefined, and users do not have to supply their own Liquid template text.

The general format for the [lutaml_uml_datamodel_description] command is given in Figure 27. This command generates a Metanorma representation of the UML class diagram contained in the XMI file path/to/example.xmi.

[lutaml_uml_datamodel_description, path/to/example.xmi,config.yaml]
--
[.before]
....
my text
....

[.diagram_include_block, base_path="requirements/", format="emf"]
....
Diagram text
....

[.include_block, package="Another", base_path="spec/fixtures"]
....
my text
....

[.include_block, base_path="spec/fixtures"]
....
my text
....

[.before, package="Another"]
....
text before Another package
....

[.after, package="Another"]
....
text after Another package
....

[.after, package="CityGML"]
....
text after CityGML package
....

[.after]
....
footer text
....
--

Figure 27 — lutaml_uml_datamodel_description command

Within the lutaml_uml_datamodel_description command, there is a placeholder for UML content, [.diagram_include_block] which automatically invokes Figure 26, the predefined Liquid template specifying how UML information is included for each package within the command.

The [.diagram_include_block] block includes:

• base_path, a required attribute for path prefixes to supply for diagram image;

• format, an optional attribute that tells what file extension to use when including diagram a file.

The remaining blocks specified within the command give text to interpolate:

• before or after each package in the loop ([.before, package="Another"], [.after, package="CityGML"]); or

• before or after all packages have been iterated through ([.before], [.after]).

There is also provision for text to be interpolated in predefined positions within each package ([.package_text, position="after", package="Another"]).

Last but not least, there is provision for one or more files matching a base path specification to be invoked for inclusion in the command ([.include_block, position="before", base_path="requirements/requirements_class_"]).

The config.yaml parameter of the command is optional. The nominated YAML file specifies which packages to process in the command, in which order; rendering style instructions; and the location of the root package. An example of the YAML file is provided at Figure 28.

---
packages:
  # includes these packages
  - "Package *"
  - two*
  - three
  # skips these packages
  - skip: four
render_style: data_dictionary
section_depth: 2

Figure 28 — YAML configuration for lutaml_uml_datamodel_description command

The example configuration in Figure 28 indicates that packages matching the regexp Package , the regexp two, and the name three are to be processed, in that order, while four is to be skipped.

It indicates the rendering style, which can be one of entity_list, data_dictionary, or default.

Finally, it indicates the limit if any to how deep the recursive iteration of packages can go.

8.2.1.  Annotation format in model editing tool

Clause 4.14 noted the challenge in coordinating supplementary truth in a standards document, authored in an environment like Metanorma, against annotations included in the derived truth in a standards document, and authored in the model authoring tool.

Sparx Systems Enterprise Architect is the modelling tool used for the CityGML 3.0 conceptual model, and allows for the annotation of UML objects as description, notes, using a rich-text editor. Sparx Systems Enterprise Architect encodes these rich text boxes with either the Microsoft RTF format or in HTML.

The challenges of including such content inside an MDS include:

• The content of these fields is generally inconsistent. Some fields are encoded in HTML, some in RTF.

• Some authors embed lightweight markup languages such as AsciiDoc or Markdown syntax, but encoded in HTML or RTF format instead of plain text.

The annotations in CityGML reflected a drive to format text in annotations without coordination or planning.

For the downstream processing of annotations, it is important to both identify the formatting scheme used for annotations within the model, and then convert it into the same markup scheme as that used in the target document.

Given that Metanorma AsciiDoc is the official markup language used by OGC for its standards documents, all annotations authored within model authoring tools must be marked up using the same markup language in order to allow MDS generation.

8.2.2.  Presentation styles of UML model-based standards

8.2.2.2.  Entity list style

In the entity list style, each class and data type in a package is presented in tables, with one row per class and data type, giving an identifier for the entity and a paragraph description. No further detail of the classes was provided.

7.6.1. Requirements
7.6.2. Class definitions
7.6.3. Additional Information

Figure 29 — Order of subsections per UML package in the entity list style

A sample of the “Class definitions” table is shown in Figure 30.

Figure 30 — Sample "Class definitions" table from 20-010, 7.6.2

8.2.2.3.  Data dictionary style

In the data dictionary style, each class and data type in a package is presented in a separate subclause, with tables presenting not only the identifier and a paragraph description, but also superclasses, stereotypes, and in the case of classes, all class attributes with their cardinalities and (hyperlinked) types. Any applicable basic types, unions, and code lists are also enumerated.

8.6. Dynamizer
8.6.1. Classes
8.6.2. Basic types
8.6.3. Unions
8.6.4. Code lists
8.6.5. Data types
8.6.6. Enumerations

Figure 31 — Order of subsections per UML package in the data dictionary style

The first section extracted from the PIM is the “metadata”. A sample is shown at Figure 32.

Figure 32 — Sample "metadata" block, 20-010, 8.3

The second section extracted provides the classes. LutaML will iterate through all classes in the UML package generating one table each. A sample is shown at Figure 33.

Figure 33 — Sample "metadata" block, 20-010, 8.3.2

The third section extracted provides the “Basic types” (stereotype BasicType). LutaML will iterate through all basic types in the UML package generating one table each. A sample is shown at Figure 34.

Figure 34 — Sample "Basic types" block, 20-010, 8.6.1

The next section extracted provides the unions. The CityGML 3.0 document does not define Unions.

Then the code lists are extracted. Similar to above, LutaML will iterate through all code lists in the UML package generating one table each. A sample is shown at Figure 35.

Figure 35 — Sample "Code lists" block, 20-010, 8.6.4

Second to last the “data types” are extracted. LutaML will iterate through all data types in the UML package generating one table each. A sample is shown at Figure 36.

Figure 36 — Sample "Data types" block, 20-010, 8.6.5

The last section extracted provides the enumerations. LutaML will iterate through all enumeration objects in the UML package generating one table each. A sample is shown at Figure 37.

Figure 37 — Sample "Enumerations" block, 20-010, 8.6.6

8.2.3.  Multiplicity notation

The CityGML 3.0 Conceptual Model employs an uncommon UML notation for specifying the multiplicity of an association role (technically the MultiplicityElement of an Association end).

In Figure 38, the notations * and 1 (red dashed boxes) are alternatives to the complete specifications of 0..* and 1..1, respectively. In comparison 0..1 (green dashed box) is a complete specification.

Figure 38 — CityGML 3.0 Conceptual Model Multiplicity Notation

This alternative notation is used inconsistently throughout the standard (both the document and EAP) — in particular it is the case that * is used with association roles while 0..* is used with attributes. The alternative notation and its use are not documented in the standard itself and may be either confusing or ambiguous to some users of the standard. It is also inconsistent with the requirements of OMG UML 2.5.

OMG Unified Modeling Language (UML) (https://www.omg.org/spec/UML/2.5.1/About-UML/) specifies the notation for “Multiplicity Elements” in Clause 7.5.4.1 as follows:

<lower-bound> .. <upper-bound>

An example of the use of alternative notation in class diagrams as presented in OMG UML 2.5, Figure 8.2 is given in Figure 39; note that the use of alternative notation is consistent for all properties in the diagram.

Figure 39 — UML 2.5.1 Multiplicity Element Notation Examples

ISO 19103:2015, Clause G.8.2 (Informative) states:

ISO 19103:2015, Clause H.13 “Former assumptions”, states:

Although ISO 19103:2015 does not mention the use of alternative notation, it does sanction the use of 1 rather than 1..1.

Use of the alternative notation in the case of 0.. may be unclear to the editors and users of conceptual models, particularly as this alternative notation is not identified in ISO 19103:2015 as suitable for use in ISO/TC 211 developed standards. For example, ISO 19170-1:2021 consistently uses 1 and 0.., as appears to be the case for most, and possibly all, other HMMG conceptual schemas.

The CityGML 3.0 Conceptual Model potentially further confuses matters by using the standard notation for attribute multiplicity but the alternative notation for association role multiplicity.

8.2.4.  Conceptual model dependencies

OGC 20-010, Clause 8.2 documents requirements class http://www.opengis.net/spec/CityGML-1/3.0/req/req-class-core wherein dependencies are asserted with respect to six external standards: ISO 19103:2015, ISO 19107:2003, ISO 19109:2015, ISO 19111:2019, ISO 19123:2005, and OASIS xAL v3.0 (OASIS CIQ v3.0). As documented in the CityGML 3.0 Conceptual Model EAP these direct dependencies are illustrated in Figure 40.

Figure 40 — CityGML 3.0 Part 1 — Conceptual Model UML Package Primary Dependencies

Requirements class http://www.opengis.net/spec/CityGML-1/3.0/req/req-class-core is incorrect when stating a dependency only on ISO 19111:2019. There is a dependency on the «type» SC_CRS class, which is no longer present (and has no direct correspondence) in ISO 19111:2019; in this case the dependency is on ISO 19111:2007. However «FeatureType» CityModel, attribute engineeringCRS specifies a range of “EngineeringCRS”, which is not a class in ISO 19111:2007; it is only present in Edition 3. As class “EngineeringCRS” has a direct correspondence to the «type» SC_EngineeringCRS class in ISO 19111:2007 consistent adoption of a dependency on, and classes from, ISO 19111:2007 is the most appropriate resolution to these inconsistencies.

Requirements class http://www.opengis.net/spec/CityGML-1/3.0/req/req-class-core is incorrect when failing to identify a dependency on ISO 19108:2002. CityGML 3.0 Table 5 and Section 9.1.14 specify the use of the «Union» TM_Position class which in turn depends on the use of TM_TemporalPosition with many subclasses and related types. «Union» TM_Position is the range of attributes startTime and endTime of the «FeatureType» Dynamizer class.

Requirements class http://www.opengis.net/spec/CityGML-1/3.0/req/req-class-core states a dependency on ISO 19103:2015; e.g., the range of attribute value of the «DataType» DateAttribute class in the CityGML 3.0 Conceptual Model is specified as «interface» Date from ISO 19103:2015. There are, however, indirect dependencies on ISO/TS 19103:2005 (the earlier edition as a Technical Specification) through the other standards dependencies. Mixing dependencies on different editions of the same standard may result in unexpected outcomes in the integrated conceptual model. It also adds complexity in the derivation of platform-specific models where distinct authoritative target implementations may exist for each edition of the external standard (as is typically the case for XML Schema), thus complicating (and possibly precluding) the use of a “mix and match” technique when deriving an Implementation Specification for that technology target.

As the ISO/TC 211 Harmonized Model conceptual schemas include all editions of each standard developed by ISO/TC 211 within a single EAP file, it is helpful to trim the assemblage by eliminating all but one edition of each standard upon which a dependency is to be asserted.

Eliminating excessive content from the EAP improves performance while ensuring that there is no possibility of confusion among same-named classes or inadvertently using a class that does not exist in the intended standard (or version of that standard).

In the present analysis, ISO/TS 19103:2005 was adopted (rather than ISO 19103:2015) in order to ensure consistency in both direct and indirect dependencies.

8.2.5.  Conceptual Model Completeness

OGC 20-010, Clause 8.2 documents requirements class http://www.opengis.net/spec/CityGML-1/3.0/req/req-class-core which states a dependency on OASIS xAL v3.0 (OASIS CIQ v3.0). In particular, the range of association role xalAddress of the «FeatureType» Address class in the CityGML 3.0 Conceptual Model is specified as a property-free «DataType» XALAddress, as shown in Figure 41.

Figure 41 — CityGML 3.0 Part 1 — «FeatureType» Address

According to its textual definition, XALAddress is intended to operate as a surrogate for “address details” from the OASIS xAL standard. The “OASIS xAL v3.0” UML package in the CityGML 3.0 Conceptual Model is empty. In consequence it is not possible to derive any complete platform-specific models from the CityGML 3.0 Conceptual Model. While in the case of XML Schema there exists an authoritative Implementation Specification (http://docs.oasis-open.org/ciq/v3.0/cs02/xsd/default/xsd/xAL.xsd), there is no corresponding authoritative Implementation Specification for other technologies, e.g. JSON Schema.

Preparation of a derived target-specific Implementation Specification may be dependent on target-related conceptual models/schemas. For example, in the case of implementations based on JSON, the well-known GeoJSON format for encoding geographic data structures may be employed. While there is published an overall JSON-based schema (https://geojson.org/schema/GeoJSON.json) as well as GeoJSON type-specific schemas (e.g., https://geojson.org/schema/Point.json), there exists no corresponding conceptual model that might be used in either documenting an Implementation Specification model in UML, or as an adjunct to the PIM for use in deriving alternative technology-specific Implementation Specifications.

8.2.6.  External Conceptual Model Readiness

Developing a technology-specific Implementation Standard based on the CityGML 3.0 Conceptual Model requires determining encodings corresponding to UML classes defined in external conceptual models. When there exist suitable authoritative encodings then UML classes in the external conceptual models can be mapped to individual corresponding encoding representations in XML Schema. As it happens, all external conceptual models upon which the CityGML 3.0 Conceptual Model is dependent have authoritative XML Schemas — published by either ISO or OASIS. This is not the case for other technology-specific encodings, e.g., JSON Schema.

When there do not exist suitable authoritative encodings, it becomes necessary to develop those encodings in addition to developing the CityGML 3.0 Conceptua