I. Abstract
This OGC Testbed 17 Engineering Report is deliverable D022 of the OGC Testbed 17 initiative performed under the OGC Innovation Program, incorporating the D022, D143 and D144 tasks that have produced Model Driven Architecture (MDA) tools.
This ER:
details state-of-the-art analyses of existing MDA tools with their capabilities and limits; and
provides clear recommendations on how model-driven design can be fully exploited in the context of rich data model and API design efforts.
II. Executive Summary
The Model-Driven Architecture (MDA) approach to the generation of Model-Driven Standards (MDS) and Platform-Independent Models (PIM) has been proven to work through Testbed activities (D022, D143, D144) covered by this Engineering Report (ER).
A total of 4 prototype systems were developed under D144:
Converting the CityGML 3.0 conceptual model into an MDS;
Converting the Discrete Global Grid Systems (DGGS) conceptual model into an MDS;
Converting the CityGML 3.0 conceptual model to XML Schema as a PSM;
Converting the CityGML 3.0 conceptual model to JSON Schema as a PSM.
The 5th prototype system for “Converting the CityGML 3.0 conceptual model to Resource Description Framework (RDF) as a PSM” is still in progress.
Under D143, a theoretical methodology was presented for using RDF as an alternative modelling approach instead of the Unified Modeling Language (UML).
It is determined that an MDA approach, possibly an organizational-wide one, would streamline the downstream creation of MDSes and PSMs, and greatly benefit all stakeholders of the model-driven process — authors of information models, standards, and the users of those models and standards.
Specifically, the usage of a single source of truth across these deliverables will guarantee a certain consistency in the deliverables, and also provide upstream feedback to conceptual model authors on potential impact of seemingly inconsequential changes.
The strong implication for using an MDA approach is that generally, the MDA approach makes any inconsistencies, omissions, or under-specifications in underlying information models much more visible, since they impact the MDA workflow directly.
In particular, the following criteria needs to be met for an MDA approach to be effective (this is duplicated in Clause 4):
The authoritative information model must be fully and accurately specified with regards to details that appear in the output model-driven standard.
The authoritative information model must be exportable to a format useable by the MDA tools. For instance, XMI output from most UML tools utilize a proprietary structure and require MDA tools to provide vendor-specific support.
Supplementary information to the information model, such as additional information models, guidance information for MDS output, or platform-specific configuration for PSM output, must be available in a form useable by the MDA tools.
This report recommends OGC to perform the following:
develop and enact best practices, requirements and policies for wider adoption of MDA in OGC
adopt the recommended open-source MDA tools to facilitate the OGC MDA approach (Metanorma and ShapeChange)
formalize the MDA approach described in this ER to PIM-to-MDS and PIM-to-PSM generation, then making this approach available to other OGC authors
implement documented recommendations within this ER (see at the table of contents: List of Recommendations)
develop and deliver training on the specific topics of PIM-to-MDS and PIM-to-PSM as they are likely be used often in OGC
facilitate development of features needed for the OGC MDA approach as described in Clause 4 through arrangements with the community, vendors or sponsors
set standards and requirements on source information models, in order to enable the MDA approach to work effectively
promote the adoption of cloud deployment and automated CI/CD for the PIM-to-MDS and PIM-to-PSM workflows to assist the model and standard development process
revise and clarify the ModSpec specification, consider ModSpec as machine-readable models, creating a validation tool to validate ModSpec instances (see Clause 4.17.4)
find ways to improve the integration between the model authoring tool and the standards authoring tools to support better cross-references (see Clause 4.17.3 and Annex C)
investigate how OGC could benefit from existing SMART efforts such as BR|SMART in automated testing (CITE) and in the representation of standards. At least, there should be an ability for OGC standards to be incorporated into the SMART structure. (see Clause 4.17.2)
investigate how the MDA approach can benefit to the development of OGC API and API standards
potentially contribute the MDA approach and workflows with partner SDOs that OGC works closely with, such as ISO/TC 211
The Testbed participants would like to especially thank the project sponsors for their vision and openness, and for making this very important work available.
III. Keywords
The following are keywords to be used by search engines and document catalogues.
ogcdoc, OGC document, MDA, model-driven
IV. Preface
This ER is deliverable D022 of OGC Testbed 17.
The focus of this testbed activity was to demonstrate the business value of model-based standards, as an extension from the MDA approach for creating standards.
As literature suggests, the following are the major benefits from developing standards in a model-driven manner:
By maintaining standards content in the model, simplifying and decoupling the model maintenance process is possible.
Storing annotations and guidance about the model together with the actual model enables a single source of truth that can streamline the standards authoring process.
The maintenance of a single Platform Independent Model (PIM) supports automatic generation of one or multiple Platform Specific Models (PSMs), which can be directly used by developers and applications.
PSMs can also be treated as models in the same manner as PIMs. This means that PSMs also receive the same benefits from the model-based standards approach.
The results of the work performed in this testbed activity have confirmed that the above benefits are achievable through a model-driven approach, with the following findings:
A model-driven approach drives quality requirements upstream, and as such the model used as the source for a model-based standard must have dependable quality for downstream artifacts to be created accurately.
Rules and normalization procedures should be applied to a model being used as the basis for a model-based standard to ensure quality of generated downstream artifacts.
“Best practice” templates can be developed for different model types, such as for Sparx Systems Enterprise Architect Projects (EAP), Unified Modeling Language (UML) models, XML Schema Documents (XSDs), etc., enabling consistent presentation and facilitating reuse across the organization.
In certain conditions, when migrating standards that were fully model-based, a “hybrid” mechanism needs to be used, such as when the original standard deviates heavily from a model-driven counterpart or requires certain content hierarchies for backwards compatibility. In these cases, custom templates or templates with the ability to override “best practice” become necessary.
V. Security considerations
No security considerations have been made for this document.
VI. Submitting Organizations
The following organizations submitted this Document to the Open Geospatial Consortium (OGC):
- Ribose Limited
VII. Submitters
All questions regarding this document should be directed to the editor or the contributors:
Name | Organization | Role |
---|---|---|
Ronald Tse | Ribose Limited | Editor |
Nick Nicholas | Ribose Limited | Editor |
Chuck Heazel | Heazeltech, LLC | Contributor |
Paul Birkel | Geosemantic Resources LLC | Contributor |
Jeffrey Lau | Ribose Limited | Contributor |
Nicholas Car | SURROUND Australia Pty Ltd | Contributor |
OGC Testbed-17: Model-Driven Standards Engineering Report
1. Scope
This Engineering Report is a deliverable of the OGC Testbed 17 initiative. The objective of the ER is to demonstrate the business value of model-driven standards, as an extension of the model-driven architecture approach for creating standards.
This document describes several proofs-of-concept developed under deliverables D143 and D144 to demonstrate the authoring of model-based standards.
2. Terms, definitions and abbreviated terms
This document uses the terms defined in OGC Policy Directive 49, which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this document and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2.
This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the ‘ModSpec’. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec.
For the purposes of this document, the following additional terms and definitions apply.
2.1. Terms and definitions
2.1.1. application schema
conceptual schema (Clause 2.1.3) for data required by one or more applications
[SOURCE: ISO 19101-1:2014, Clause 4.1.2]
2.1.2. conceptual model
CM ADMITTED
model that defines concepts of a universe of discourse
[SOURCE: ISO 19101-1:2014, Clause 4.1.5]
2.1.3. conceptual schema
formal description of a conceptual model (Clause 2.1.2)
[SOURCE: ISO 19101-1:2014, Clause 4.1.6]
2.1.4. model-driven standard
MDS ADMITTED
standard created using a model-driven architecture (Clause 2.1.5)
2.1.5. model-driven architecture
MDA ADMITTED
software design approach for development of software systems centered around data models
[SOURCE: OMG UML 2.5]
2.1.6. model authoring tool
software used for authoring a conceptual model (Clause 2.1.2)
2.1.7. platform-independent model
PIM ADMITTED
conceptual model (Clause 2.1.2) that does not contain platform-specific concerns
2.1.8. platform-specific model
PSM ADMITTED
data model that contains platform-specific concerns
2.1.9. model transformation
model conversion from one form to another which may not preserve all semantics
2.1.10. model conversion
process that converts a data model in one format into another format that preserves all model semantics
2.1.11. stereotype
extension of an existing UML metaclass that enables the use of platform or domain specific terminology or notation in place of, or in addition to, those used for the extended metaclass
[SOURCE: OMG UML 2.5]
2.1.12. tagged value
attribute on a stereotype used to extend a UML model element
[SOURCE: OMG UML 2.5]
2.1.13. UML profile
predefined set of stereotypes, tagged values, constraints, and notation icons that collectively specialize and tailor UML for a specific domain or process
[SOURCE: ISO/IEC 19501]
2.1.14. metaschema
set of information models that are capable of describing other schemas
2.2. Abbreviated terms
ADE
(CityGML) Application Domain Extension
API
Application Programming Interface
DDL
(SQL) Data Definition Language
DSL
Domain Specific Language
EAP
Enterprise Architect Project
ER
Engineering Report
GFM
General Feature Model
GIS
Geographic Information System
GML
Geography Markup Language
JSON
JavaScript Object Notation
JSON-LD
JSON for Linked Data
MBA
Model-Based Authoring
MDA
Model-Driven Architecture
MDS
Model-Driven Standard
OCL
Object Constraint Language
OWL
Web Ontology Language
PIM
Platform Independent Model
PSM
Platform Specific Model
RDF
Resource Description Framework
SDO
Standards Development Organization
SKOS
Simple Knowledge Organization System
SQL
Structured Query Language
UML
Unified Modeling Language
XSD
XML Schema
3. Introduction
3.1. Problem statement
In recent years the OGC has seen the emergence of new encoding formats, data models, and service architectures. The result has been a proliferation of standards which should form a coherent body of work. The tools required to achieve and guarantee this coherence have been lacking.
This ER, reporting on tasks D022, D143 and D144, investigates the application of MDA tools and techniques to manage the development and maintenance of a portfolio of related standards.
3.2. Model-driven architecture and its potential benefits
The model-driven architecture (MDA) paradigm (introduced by the Object Management Group (OMG) in 2001) is a design approach for the development of software systems.
One of the most important goals of MDA is to maintain a single source of truth for a system (a standard in this context). In an MDA approach, there is a single standardized definition (truth) from which all other derived standards and specifications are created (derived truth), potentially with additional contributions (augmented truth) by secondary sources of information (supplementary truth) (Figure 1). This approach promises technical interoperability of a synchronized specification stack between information systems.
Figure 1 — Conceptual derivation of direct and augmented truths from a single source of truth
3.3. Types of models and their derivatives
Platform Independent Models (PIM) provide the definition of a data and/or computing capability which is independent of the implementing technology.
Example 1
A Conceptual Model can be a PIM, being technology-independent by definition. Conceptual Models are commonly specified using UML Class diagrams.
Platform-Specific Models (PSMs) define how the PIM capability is realized using a specific implementing technology (e.g., an XML Schema (XSD) or a relational database schema (SQL DDL)). Common implementing technologies include: XML Schema, JSON Schema, SQL DDL, and RDF.
The PSM may be derived from a PIM through a transformation taking only the PIM as input, with a deterministic mapping from PIM constructs to PSM constructs. In that case, the PSM can be spoken of as pure. The transformation may be enhanced with mapping guidance specific to the target platform (supplementary truth), in which case the PSM can be spoken of as mixed (Figure 2).
Example 2
A pure mapping from a UML Class diagram to XSD will map all UML class attributes consistently, e.g. as XML elements. If the mapping is instead to choose between XML elements and XML attributes for its rendering of UML class attributes, following user configuration, the PSM is mixed: the guidance as to which class attributes to render as XML elements and which as XML attributes is supplementary truth, as it is information extraneous to the PIM, the UML Class model.
Figure 2 — Conceptual derivation of PSMs from a PIM with supplementary platform-specific information
The PIM can serve as the source of truth for the documentation describing it, as well as for downstream PSMs. Again, the documentation may be derived truth, expressing only information inherent in the PIM; or it may be augmented truth, incorporating supplementary truth outside the PIM proper — such as additional documentation or guidance (Figure 3). The latter is expected for documentation, since documentation has a tutorial and informative function, and is not just a normative description of the model. If the documentation is expressed as a standard, supplementary truth such as term definitions and bibliographic information is required in the document format. Documentation expressed as a standard is expected to have normative effect; the pure model derived from a PIM or PSM may not contain enough guidance or clarifications to have normative effect, and may accordingly be treated only as informative (Figure 4).
Figure 3 — Process in creating PSMs from a PIM with PSM-specific information
Figure 4 — PIM-derived artifacts
A derived truth (e.g. a PSM) can also be used as a source of truth to generate further derived truths (e.g. a more specific PSM). Therefore the “platform” named here can be a floating frame of reference.
Example 3
An API model (PSM) generated from a conceptual model (PIM) can further generate XML encodings (PSM) using the API model as its own starting source of truth.
3.4. MDA as applied in OGC
The OGC Innovation Program has employed model transformations in various guises as far back as the Critical Infrastructure Protection Initiative (CIPI) in 2002. In particular, the open-source tool ShapeChange has been employed in many OGC Testbed activities starting with Testbed-2 (OGC 04-100).
In the OGC, MDA approach, two types of models are defined to distinguish the cases of a source of truth against derived truths: PIM and PSM.
In OGC PIMs are referred to as “Conceptual Models”. In ISO/TC 211 PIMs are referred to as “Conceptual Schemas”. In this Engineering Report (ER) we follow the OGC terminology except in contexts in which ISO 19100-series content is being referenced.
In OGC, PSM-based standards are often referred to as “Implementation Specifications”.
Table 1 — Mapping of terminology for MDA and formats typically used in OGC contexts
MDA | OGC and ISO | Model Formats |
---|---|---|
Platform Independent Model (PIM) | Conceptual Model/Schema | UML |
Platform-Specific Model (PSM) | Implementation Specification | XML Schema, JSON Schema, SQL DDL, OWL/RDF |
3.5. Challenges in developing OGC standards
While OGC has long utilized MDA for standards development, there is a recognition that gaps exist between the development of data models and the publication of those data models.
Challenges encountered include the following:
PIM documentation. A PIM model is often an abstract representation of requirements which require extensive documentation and guidance on the meaning of various components. Such documentation text is often managed outside of the model itself (as supplementary truth), due to tool limitations.
NOTE 1 PIM documentation is typically published in OGC Conceptual Model standards.
Generation of the PSM. The PIM and PSMs may be managed by separate or independent groups. This synchronicity issue between the PIM and its derived PSMs negatively affects interoperability between information systems.
NOTE 2 PSMs are published as artifacts of OGC Implementation Specifications.
Example
An XML encoding (PSM) generated from version 1.0 of the conceptual model (PIM) will be out-of-sync when the conceptual model has advanced to version 1.1.
PSM documentation and guidance. The documentation of PIM and that of its PSMs are often managed separately. This leads to misaligned documentation and practices between the PIM and PSMs. The issue is further exacerbated as PSM documentation is meant to contain additional details specific for a platform, which by definition cannot be derived from the PIM directly.
NOTE 3 PSM documentation is typically published in OGC Implementation Specifications.
Different types of deliverable outputs. For example, documentation is meant for human consumption but XML schemas are meant for machine consumption. Yet both of these deliverables may originate wholly or in part from the same model.
This ER reports on the success of addressing the first two challenges, and partially on the third.
These challenges are typically dealt with using one or more of the following strategies:
Role segregation. For instance, adding control bodies to control and synchronize the flow of information from the PIM to downstream deliverables.
Additional manual resources. Apply additional manual steps and corresponding resources in order to synchronize deliverables, such as in the generation of model-derived artifacts, synchronization of texts, version checking.
These challenges indicate that the following questions need to be resolved when developing a standard:
What is my model specification technology? Is more than one technology being used?
Where are the models and their documentation kept?
What model artifacts need to be generated?
What compromises can be made with regard to adhering to the MDA paradigm?
3.6. Objective: deterministic generation of PIM-derived artifacts
In this ER we report on the following objectives:
Identify and evaluate MDA tools potentially suitable for the generation of PIM-derived artifacts with geospatial standards, and document any gaps not satisfied by these tools.
Document capabilities and limits of each identified tool and provide recommendations on the context of OGC usage (don’t use, adopt or extend).
Develop prototypes which explore solutions to identified gaps.
Document best practices for representing an OGC PIM from experience gained from development of the prototypes. These best practices will provide guidance to the developers of OGC Conceptual Model Standards so that those models can be used to generate valid OGC Implementation Standards using MDA tools.
3.9. Benefits of automated generation of PIM downstream artifacts
There are multiple benefits by having a single-step workflow that automatically generates PIM downstream artifacts.
Enables modern software development practices, such as:
Integration with change management systems (like Git) that allow distributed development
Usage of automated tests that ensure correctness of downstream artifacts
Facilitates modern DevOps practices, including:
ability to automatically generate and distribute PIM downstream artifacts on individual changes, which can be combined with tests to ensure correctness of generated output
Provides confidence in the correctness of PIM-derived artifacts due to them being synchronized with the input PIM.
Reduction in the human effort necessary in validating the correctness of PIM downstream artifacts.
Ultimately, this approach “lets the computer do what a computer does best” — by elevating human effort to validate the generation process of PIM-derived artifacts instead of the validation of the artifacts themselves.
3.10. Previous Work
3.10.1. ISO/TC 211 Standards
Technical Committee 211 of the International Organization for Standardization (ISO/TC 211) manages a set of ISO standards for geographic information.
3.10.2. ISO 19109
ISO 19109:2015 defines a Unified Modeling Language (UML) metaschema for feature-based data. That General Feature Model (GFM) serves as the key underpinning for a family of ISO standards employed by members of the OGC community.
These standards define the structure and content of geospatial data in a family of “conceptual schemas” that employ the UML Class diagram methodology. These standards are regularly employed by members of the OGC community.
3.10.3. ISO 19136
ISO 19136:2007 Annex E “UML-to-GML application schema encoding rules” defines a set of encoding rules that may be used to transform a GFM-conformant UML conceptual schema to a corresponding XML Schema (XSD) based on the structure and requirements of the Geography Markup Language (GML).
The resulting XSD file(s) may be used to define the structure of, and validate the content of, XML instance documents used in geospatial data exchange.
This methodology for deriving technology-specific encodings of GFM-conformant UML conceptual schemas, based on formalized sets of encoding rules, has been successfully applied in other contexts than GML (e.g., technologies based on Resource Description Framework (RDF) encodings), and has come to be known generically as “UGAS”. UGAS is an example of the Model Driven Architecture (MDA) paradigm introduced by the Object Management Group (OMG) in 2001.
3.10.4. ShapeChange
ShapeChange is an open-source implementation of the UGAS methodology that has emerged as a key technological underpinning in many environments where platform-specific data exchange requirements have been separated from platform-independent domain (content) modeling requirements.
MDA techniques have been used sporadically to develop OGC and ISO/TC 211 standards; ShapeChange has been instrumental in many of those efforts, although effort-specific documentation has been generally sparse.
Engineering Reports documenting OGC-related ShapeChange initiatives can be found at https://shapechange.net/about/background-documents/
3.10.5. Metanorma
Metanorma is the leading open-source standards development and publishing suite.
Metanorma enables creation of semantic-aware standard documents in an end-to-end, author-to-publish workflow, based on the notion that standard documents from different standards-setting bodies rely on common requirements. It was named “Best New Semantic Technology Platform, Tools and Applications” and “Best New Scholarly Publishing Information Solution” by the International Business Awards.
Metanorma technology consists of three parts:
a unified document model for standard documents, based on ISO/AWI 36100,
a serialization format for standard documents into semantic and presentational formats, and
a toolchain for authors to directly publish standard documents in the correct structure and appearance without the need for post-processing.
Metanorma is used by over 15 standards organizations, including OGC itself.
3.11. Developed PIM-derivation methodology and prototypes
In this work item the following PIM-to-PSM transformation prototypes were developed using MDA and MBA technologies.
In particular, the D144 task (Clause 10) explored the space of MDA PIM-to-PSM transformations based on two recent OGC Standards that were accompanied by formal UML-based conceptual models:
OGC 20-010 (dated 2021-09-13)
ISO 19170-1:2021 (dated 2021-05-11)
Table 2 — D144 PIM-to-PSM transformation prototypes and links
PIM | PSM |
---|---|
CityGML 3.0 CM | OGC Standard |
CityGML 3.0 CM | XML schema |
CityGML 3.0 CM | JSON schema |
CityGML 3.0 CM | OWL/RDF |
DGGS CM | OGC and ISO standard |
Four target PSM environments were explored:
Metanorma AsciiDoc (Metanorma)
XML Schema (W3C TR xmlschema-1)
JSON Schema (JSON Schema)
Resource Description Framework (W3C RDF) extended by:
Web Ontology Language (W3C OWL), and
Simple Knowledge Organization System (SKOS: W3C TR skos-reference)
3.12. Semantic Web PIM-derivation methodology
The D143 task (Clause 9) explored using Semantic Web ontologies, rather than UML, as the underlying model for a PIM (W3C RDF, W3C OWL, W3C TR skos-reference). It explored how extant ontologies and vocabularies, including document ontologies, could be used to generate an MDS at the PIM level. The task did not provide an implemented prototype.
4. Key findings
4.1. General
This section provides key findings from the prototypes developed.
It is determined that an MDA approach, possibly an organizational-wide one, would streamline the downstream creation of MDSes and PSMs, and greatly benefit all stakeholders of the model-driven process — authors of information models, standards, and the users of those models and standards.
Specifically, the usage of a single source of truth across these deliverables will guarantee a certain consistency in the deliverables, and also provide upstream feedback to conceptual model authors on potential impact of seemingly inconsequential changes.
In general, the MDA approach makes any inconsistencies, omissions, or under-specifications in underlying information models much more visible, since they impact the MDA workflow directly.
This report recommends the enactment of best practices, requirements and policies for wider adoption of MDA in OGC.
As the task of generating Model-Driven Standards (MDS) covering both PIM and PSMs is extensive by itself, the reporting for derivation of MDS from each of PIM in scope for PSMs in OGC are reported on separately.
This report is specific to considerations around PIM-driven MDS and PIM-driven PSM, where a UML model is used as the PIM.
The use of each of XML Schemas, JSON Schemas, and RDF as PSMs for PSM-Driven Standards is considered in separate forthcoming reports (Figure 10).
Figure 10 — Current and future OGC Engineering Reports for PSM documentation standards
4.2. Recommended MDA tools
Metanorma and ShapeChange were determined to be the best readily-available open-source tools to address the task objectives of generating MDA documents and PSMs, respectively. When used together, they form a full MDA toolchain for incorporating UML (from Sparx Systems Enterprise Architect) for OGC deliverables.
Metanorma has been demonstrated to support AsciiDoc as the input documentation format and specification of certain information models such as ModSpec. It has been successfully integrated into OGC workflows and is also used by ISO/TC 211 standards developers for creating model-based standards. Metanorma depends on Ribose LutaML, a data model accessor that supports multiple data model types, to navigate data models within the Metanorma structure.
ShapeChange has been employed by OGC and ISO/TC 211 standards developers. It has been repeatedly demonstrated to successfully employ ISO/TC 211 Harmonized Model Maintenance Group (HMMG) conceptual schemas as input. ShapeChange support generation of PSMs as XML Schema, JSON Schema, and RDF outputs (among others).
4.3. Prototype capabilities
4.3.1. PIM-to-MDS prototypes
In the case of the PIM-to-MDS prototypes, both the PIMs (the UML classes, as expressed in XMI) and the document authoring environment (Metanorma) were stable at the time of implementation.
Metanorma is used to manage and perform the core PIM-to-MDS transformation. Metanorma is the established authoring toolchain tailored for creating OGC Standards.
Several types of information were involved in the PIM-to-MDS transformations:
PIM and the annotations stored within it, managed in Sparx Systems Enterprise Architect
ModSpec models, managed in Metanorma
Supplementary text and additional diagrams, managed in Metanorma
The PIMs are exported as EA-proprietary XMI v2.5 files and EMF diagrams, as input for the Metanorma transformation process.
LutaML (Clause 7.2) and the Metanorma-LutaML plugin are used to mediate between the model authoring tool (EA) and the MDS tool (Metanorma). LutaML is a universal data accessor implemented to facilitate MDA, and has an extensible structure that allows it to read in models expressed in a range of formats, including EA-proprietary XMI.
The prototypes (Clause 10.4, Clause 10.5) have been proven successful, and the approach has been flexible enough to be useful for MDS from a range of models, not limited to the OGC, as demonstrated by the ability to generate the ISO-version of DGGS, ISO 19170.
4.3.2. PIM-to-PSM prototypes
In the case of the PIM-to-PSM prototypes, while the selected PIM (CityGML 3.0 conceptual model) was stable, the PSMs of it were not set in stone.
Given that the project sponsor encouraged experimentation, the development of the prototypes demonstrated the possibility and highlighted issues that should be addressed in order to make PIM-generated PSMs useful.
ShapeChange was used to perform the transformation from PIM to PSM. The PIM was authored in Sparx Systems Enterprise Architect.
The PIM was exported into the EA-proprietary profile of the XMI format, then processed by ShapeChange, as documented in Clause 7.1. ShapeChange is long-established as a PSM generation tool for OGC, and it supports the requisite range of capabilities to deliver the PSMs needed by OGC.
The prototypes (Clause 10.6, Clause 10.7, Clause 10.8) have been shown to be successful and demonstrates that it is indeed possible to generate a PSM that is succinct and specified to a sufficient level for application purposes.
4.4. Criteria for adopting MDA
The following criteria are deemed necessary in using a model-driven architecture:
The authoritative information model must be fully and accurately specified with regard to details that appear in the output model-driven standard.
The authoritative information model must be exportable to a format useable by the MDA tools. For instance, XMI output from most UML tools utilizes a proprietary structure and requires MDA tools to provide vendor-specific support.
Supplementary information to the information model, such as additional information models, guidance information for MDS output, or platform-specific configuration for PSM output, must be available in a form useable by the MDA tools.
A model-driven architecture approach to creation of MDS and PSMs should only be adopted if the above criteria are met.
4.5. Considerations for generating MDS
There are three approaches to developing model-driven standards directly from an information model.
Automatic inclusion. This is the recommended approach that requires minimal intervention of the MDS author in the generation of the MDS from the information model. In this approach, the model content order is inherited from the model authoring tool and fully reflected as shown in the table of contents in the MDS.
Manual inclusion. This is an advanced approach, where the MDS author wishes to manually specify content from the information model to include in the MDS.
Hybrid inclusion. This is an advanced approach that blends automatic and manual inclusion. In this approach, the MDS author specifies portions to include information model content automatically, while being able to manually insert particular content within the automatically generated MDS hierarchy. This approach also allows for tailoring of the order of content as generated in the MDS.
The choice of approaches depends on the difference in organization between the information model and the desired MDS structure.
In this Testbed task:
The CityGML MDS prototype (Clause 10.4) generally adopts the “automatic inclusion” approach
The DGGS MDS prototype (Clause 10.5) adopts the “hybrid inclusion” approach.
4.6. Cross-referencing functionality needs in PIM-MDS interactions
4.6.1. General
There are additional needs for cross-referencing when performing a PIM-to-MDS conversion, categorized in four (4) types: A, B, C and D shown in Figure 11.
Figure 11 — Cross-references supported between PIM-MDS
4.6.2. Type A: Cross-reference model-generated document elements from the information model
This type cross-references document elements generated from the information model, from textual elements within the information model. The intricacies of this mechanism are shown in Figure 12.
Figure 12 — Converting information model cross-references into document cross-references
In the model authoring environment, there are often textual elements of a UML model (such as the description field) that cross-reference another UML model in the same information model context (e.g. an Sparx Systems Enterprise Architect file). However, model authoring tools do not typically provide a formal and structured manner for specifying these cross-references.
The MDS tool must be able to recognize these internal cross-references through a standardized convention.
Example
In the OGC CityGML 3.0 conceptual model, there are cross-references in the description of UML classes and attributes that point to other UML classes or attributes inside the same context.
4.6.3. Type B: Cross-reference document elements from the information model
This type represents the ability to cross-reference static document elements from textual elements from within the information model.
In the model authoring environment, there are textual elements of a UML model that contain cross-references to document elements external to the information model, such as to ModSpec requirements. The MDS tool must provide a mechanism for defining referential identifiers and allowing cross-references that utilize identifiers to be encoded through the model authoring tool, and ultimately creating the MDS with those cross-references realized.
4.6.4. Type C: Cross-reference model-imported elements from the document
In an MDS authoring environment, an expert MDS author may want to cross-reference elements that were made available through the information-model-to-MDS transformation process.
Example
In the MDS portions of the OGC DGGS standard, there are cross-references to particular UML diagrams (through the lutaml_figure command in the MDS) that were provided from within the Sparx Systems Enterprise Architect file.
4.6.5. Type D: Cross-reference model-generated document elements from the document
In the MDS authoring environment, an expert MDS author may want to cross-reference elements that were generated by the information-model-to-MDS transformation process.
Example
In the MDS portions of the OGC CityGML 3.0 standard, there are cross-references to particular UML package and class descriptions (through the lutaml_table command in the MDS) that were document elements generated from information within the Sparx Systems Enterprise Architect file.
4.7. Basic and expert features required for MDS generation tool
An extensive set of functionality in the MDS generation tool is required to support direct generation of an MDS.
These functionalities can be categorized into “basic” and “expert” needs:
Basic features include:
Machine-readable information models. The ability to encode machine-readable requirements, ModSpec models and other encodings.
Ability to distinguish from information models the in-scope and out-of-scope objects. Treatment of classes described in document (in-scope) vs classes not described in document (out-of-scope) (e.g. skipping, alternative references, external references).
Ability to transform standardized and proprietary formats generated by the model authoring tool into formats desired in the MDS deliverable output.
Example 1
When using Sparx Systems Enterprise Architect for UML diagramming, diagrams have to be exported from Sparx Systems Enterprise Architect. However, Sparx Systems Enterprise Architect is unable to generate platform-independent vector graphics (W3C SVG), but only Microsoft EMF (EA-EMF is also incompatible with standard EMF). As OGC requires vector graphics to be rendered in platform-independent formats for HTML, PDF and Word outputs, the MDS tool must handle conversions from EMF to SVG.
Expert features include:
Ability to configure presentation styles of classes. For users of the “automatic inclusion” approach, an OGC-predefined display template is used to transform a UML model in into textual elements (e.g., a UML class uses a display template for showing a UML class in textual elements). An expert MDS author may want to customize how a UML class is represented.
Example 2
In the CityGML 3.0 standard, Clause 7 and Clause 8 use different presentational structures on the same set of UML models: Clause 7 uses the data_dictionary template, while Clause 8 uses the entity_list template.
Ability to filter and order UML packages and classes. For users of the “automatic inclusion” approach, the content order of UML packages and UML classes is inherited from the input information model. An expert MDS author may want to use a different order in the MDS from that of the original information model due to other considerations.
Example 3
In the CityGML 3.0 standard, the content order in the MDS differs from that of the CityGML conceptual model in order to match and align the clause numbers with the CityGML 2.0 standard to allow comparisons between two standards.
Ability to insert document elements before and after each UML package / class presentation. In OGC conceptual models, ModSpec requirements and conformance tests are generally defined outside of the conceptual model itself. When using the automatic inclusion approach, an expert MDS may want to place ModSpec requirements and conformance tests right after the description of a particular package or class.
Example 4
In the OGC DGGS standard, ModSpec requirements and conformance tests are encoded in the Metanorma ModSpec format. These ModSpec models are inserted into the “automatic inclusion” process through conditional insertion procedures provided by Metanorma’s LutaML plugin.
Ability to distinguish model elements that exist within the current PIM or are external to the current PIM. A UML conceptual model may refer to externally-defined UML packages and models that do not exist within the currently loaded package. The MDS tool must distinguish whether a referenced model contains such reference, and create that cross-reference accordingly. There are two possibilities:
A referenced model is not available in the current package. The cross-reference will have to be made to either the specification of the referenced model, to an alternative provided by the user, or omitted completely.
A referenced model is within the current package but is not documented in the MDS, intentionally or not. In this case the cross-reference can only be made if the referenced model exist in the MDS, or if an alternative link was provided by the user.
Example 5
In the CityGML 3.0 conceptual model, there are multiple ISO-related UML classes referenced within the models but the classes are actually located outside of the CityGML 3.0 conceptual model. These external models instead are represented within the MDS as terminology entries in the Glossary, and hence cross-references need to be made from the PIM-generated document elements to those Glossary entries where appropriate.
Ability to provide a dynamic context for programmatic document elements. In the MDS authoring environment, an expert MDS author may want to provide a template for generating document elements to be inserted right after the description of every UML package, but the content generated is context-dependent.
Example 6
In the OGC CityGML 3.0 standard, every Clause 8 subsection represents a UML package. At the end of each of these subsections, a section is inserted to provide a link to that particular package’s documentation in the OGC CityGML 3.0 User Guide. This link depends on the package name of the UML package. With Metanorma providing the dynamic context through the Liquid template language, it is possible to encode this insertion with a single block instead of one block per subsection.
The need for such functionalities is discussed further in Clause 7.2, Clause 10.4 and Clause 10.6.
4.8. PIM-to-PSM transformations rely on supplementary truths
With the CityGML 3.0 conceptual model, the developed prototypes documented in Clause 10.7 and Clause 10.8 demonstrated that the generation of PSMs from PIMs are both feasible and practical.
However, the following considerations must be taken into account:
PIM-to-PSM transformations are, at their core, model conversions. Different information modelling languages present different semantics, and the source semantics may not be fully expressible in the target modelling language. On the other hand, a semantically lossless representation in the target modelling language may be too convoluted to be useable in the target use case.
Example 1
UML is not trivially converted into W3C RDF given the different contextual assumptions of those languages. A full UML representation in RDF requires an implementation of UML metamodels in W3C RDF, of which the result would not be useable in traditional RDF scenarios.
There are multiple methodologies for converting a PIM to PSM, and there is not necessarily an “absolutely correct” methodology. The choice of methodology will likely depend on the target usage case that dictates the usage of the target information modelling language. An organization-wide approach, for consistency reasons, should take into account what conversion methodology should be allowed.
Programmatic guidance for the PSM-generation process, as specific to a PSM, is necessary. These are considered “supplementary truths” necessary for creation of the PSMs. There are two places where such conversion guidance (or “hints”) can be located:
Within the conceptual model
Example 2
In the DGGS conceptual model, XML schema generation hints are provided within the UML models.
In configuration input for the PIM-to-PSM generation tool
Example 3
In the case of the CityGML 3.0, the XML schema generation configuration is placed external to the conceptual model as a separate ShapeChange configuration file.
The management of this PSM-specific information and configuration should be considered part of any MDA approach.
4.9. Considerations when using UML models as PIM
The goal of using MDA is to derive output without relying on additional sources if the necessary information already exists in the authoritative model.
The following findings have been made with regards to PIM-to-MDS and PIM-to-PSM transformations:
UML models exported into XMI from one model authoring tool are typically not interoperable with another tool unless vendor-specific support is implemented. The MDS tool must provide vendor-specific support for the model authoring tool used.
While the machine-readable form of UML is specified in the XMI standard (OMG XMI 2.5), the XMI profiles of nearly every UML authoring tool differs — only the most basic core UML models are interoperable. Only some UML authoring tools implement compatibility features to support the import and export of UML XMI files in order to support XMIs from different vendors.
Both conceptual models used in this Testbed activity, CityGML and DGGS, are authored in the Sparx Systems Enterprise Architect EAP format. A machine-readable UML export file from Sparx Systems Enterprise Architect, in form of XMI v2.5, consists of two separate XML portions. The first portion is the XMI-standard conforming portion, which allows for interoperation between tools. However, this portion omits critical information of UML models needed for documentation, such as the description of models, stereotypes, and diagrams. The second portion is proprietary XML content, which provides most necessary information supported by the Sparx Systems Enterprise Architect GUI for the documentation of UML models.
In the MDS prototypes, the LutaML-XMI plugin had to be extended to support Sparx Systems Enterprise Architect specific XMI parsing in order to retrieve the necessary information for the documentation of the CityGML and DGGS conceptual models.
The authoritative model must be fully specified for an MDS approach. To enable automated tools to utilize information from a model, the model must provide its information in a machine-interpretable manner and allow distinction between specific types of information. In a PIM-generated MDS or PIM, any under-specification or aberration in specification practice will cause unintended failures downstream. It is therefore important to only standardize a conceptual model after its MDS is generated.
To support PIM-to-PSM XML Schema transformation, the CityGML 3.0 Conceptual Model (OGC CityGML 3.0 Conceptual Model) was developed in conjunction with software modifications to a non-current ShapeChange baseline, in order to treat CityGML-specific “core” «BasicType» DoubleBetween0and1List and DoubleList generalization classes on a special-case basis.
To remove this dependency, the current ShapeChange software baseline was extended with one new XML Schema-related rule (rule-xsd-cls-basictype-list), and the CityGML 3.0 Conceptual Model revised accordingly. This rule is independent of the CityGML 3.0 Conceptual Model, addressing the more general topic of the modeling of lists of basic types in Application Schemas for use in developing a corresponding XML Schema-based PSM.
NOTE If the CityGML Standards Working Group (SWG) chooses to adopt these minor enhancements to the CityGML 3.0 Conceptual Model and XSD-based encoding then CityGML Application Domain Extension (ADE) developers will be able to use the ShapeChange capability to generate their community-specific XSD-based encodings.
The DGGS conceptual model was used without revision for PIM-to-MDS generation.
Data elements within a model that have to be documented in the MDS must be specified in a standardized manner and in the correct format. There are potentially multiple ways of achieving similar results with a UML tool like Sparx Systems Enterprise Architect, especially when model authors focus on the diagramming (drawing) functionality and are unaware of best practices on how and where to specify information.
The DGGS conceptual model utilized practices that were problematic in information extraction due to the lack of support of those model elements in the modelling language or the model authoring tool.
Sparx Systems Enterprise Architect does not allow specifying “inactive” or “outdated” elements inside a an Sparx Systems Enterprise Architect project file (it does allow for specifying “draft status”). In the DGGS conceptual model, there were several types of “inactive” elements that are not supposed to be included in the MDS, including:
Spare model elements that were stowed for reference purposes. These were kept in a UML package called “Spare”.
Outdated model elements in various UML packages for reference purposes. These packages, classes, interfaces had names prefixed with the phrase “old:”.
Non-normative diagrams for reference purposes. These diagrams are prefixed with the phrase “fyi:”.
OMG UML XMI does not provide a mechanism for specifying the “dimension” of a UML operation. The DGGS conceptual model relied on differentiating the “dimension values” of UML operations encoded in the “Notes” field, but this information is clearly not machine-readable. (https://github.com/metanorma/ogc-dggs-xmi/issues/21)
The DGGS conceptual model also depended heavily on OCL, but Sparx Systems Enterprise Architect does not support validation of OCL. In the conceptual model, there are OCL entries that used idiosyncratic identifiers and content that are invalid in OCL grammar.
Example 1
In the DGGS conceptual model, the usage of <<query>> (1D), to indicate that the data type of a relative position should be one-dimensional, conflicts with <<query>> that is supposed to mean a two-dimensional relative position. It also used a parenthetical qualifier to restrict the type of the UML attribute.
Naming of diagrams within the model authoring tool should be consistent.
The DGGS conceptual model utilized a prefix of “Fig:” for the names of all diagrams encoded in the UML packages. In the MDS, such prefixes have to be removed as they would pollute the actual name when represented in a figure.
Naming of UML packages within the information model should be easily referable and unique.
In the DGGS conceptual model, most UML packages utilize long names that include spaces and punctuation characters, such as “Common Spatio-Temporal Classes”. While these names prioritizes human-readablity, they present a challenge to machine-referencing.
The useability challenge of these long names is compounded when accompanied by a hierarchical UML package structure. When using UML models with MDA, the models need to be referred to via fully qualified names given the possibility of conflicting model names across UML packages. These fully qualified references are not only cumbersome for MDS and PSM authors, but are also uncomfortably long for any human audience.
Example 2
In the DGGS conceptual model, a unique reference to a particular UML class can look like “Common Spatio-Temporal Classes > Temporal and Zonal Geometry > Temporal Geometry and Topology > EdgeT”,
While model authoring tools such as Sparx Systems Enterprise Architect provides a unique reference per model element and diagram, these unique IDs are long and very difficult to reuse without automated help from the MDS tool, e.g. the CityObjectGroup diagram in the CityGML 3.0 model has the EA GUID of {CCE69980-0DDD-4975-9104-054B018BAA96}.
Generally, as demonstrated by the issues under Clause 8.2, it is essential that the information model being used as input for MDA rigorously follows the model specification that MDA tools expect to see.
Lax usage of UML, while may only have minimal consequences so long as the UML only output diagrams or OGC-tailored PSM conversions, will frustrate MDA tools that are aligned with standard representations of UML.
The stakes are higher in MDA, and the processes far less forgiving of eccentricities, such as non-standard multiplicity notation (Clause 8.2.3), ad hoc usage of novel stereotypes (Clause 8.2.7), under-specified modelling of schema reuse (Clause 8.2.8), and so on.
Standards and requirements on PIM information models need to be set in order to align expectations amongst the three stakeholders in MDA usage:
model authors
model authoring tools
MDA tools
4.10. Level of specification of input models (PIM and others)
As information models are being called upon in MDA to generate complete documentation, any past under-specification or omission of model components for expediency will be correspondingly reflected in the output.
Example 1
In the DGGS conceptual model, some packages were found not to be present in the ISO/TC 211 Harmonized Model.
Example 2
Similar issues with incomplete conceptual model dependencies were encountered repeatedly for CityGML (Clause 8.2.4, Clause 8.2.5, Clause 8.2.6), and point to past lax management of the information model.
Various strategies can be used to remedy insufficient specification:
Merge multiple pre-existing models together, or use those models separately, for a single MDS. The MDS could iterate through multiple source information models, if they cannot conveniently be merged into a single source of truth.
Treat extraneous information models as external bibliographical references, without resolving them in the MDS. However, any external models in a PIM still need to be resolved when generating a PSM, as inclusions.
Omit problematic objects from the PIM in the MDS.
4.11. Improvements required in ModSpec for specification as PIM
OGC ModSpec (Clause 5.4) provides a set of information models for defining requirements and their conformance tests, and its usage is mandatory within OGC Standards.
ModSpec was originally designed to apply to UML and UML diagrams. In this Testbed activity, it is used as a PIM specification mechanism, which is then transformed into a PSM. Specifically, a ModSpec model instance is specified in the Metanorma ModSpec language (the PIM), which is then transformed into a Metanorma Requirement model in XML (the PSM).
A number of issues were discovered in the rigorous usage of ModSpec in the PIM-to-MDS prototypes (Clause 10.4 and Clause 10.6), that require additional specification and clarification in the ModSpec specification.
These issues are documented in detail at Annex D and summarized below:
Clarification between the meaning of Conformance Test Step and Conformance Test Part, and the relationships between them. (Annex D.1)
Clarification and specification of Conformance Tests and Test Steps that apply under a certain condition. (Annex D.2)
Review and update OGC-wide guidance on usage of ModSpec terminology in OGC documents. (Annex D.3)
Review and update the OGC ModSpec specification to address inconsistencies in its UML diagrams, UML model definitions and textual descriptions. (Annex D.4)
4.12. Administrative controls needed for adopting MDA organization-wide
If the MDA approach is applied organization-wide, administrative controls should be implemented (policies and procedures) to streamline development of PIM-generated output, namely the MDS and PSMs.
Mandatory practices (best practices for MDA) should be established and documented that covers the following MDA activities:
PIM model requirements. Specifically, requirements for a UML model being used as a PIM model. This covers the correctness, accuracy and level of specificity of the UML model when used as a PIM.
PIM to MDS specification best practices. When using a PIM to generate MDS, it is important to have all information intended in the MDS available in the PIM. In addition, since the MDS contains detailed specifications of the PIM, the PIM must make available its information in correctly specified semantics.
PIM to PSM specification best practices. The generation of PSMs depend on the general health of both the PIM and PSM-generation configuration or guidance. An incorrectly-specified (or under-specified) PIM or an incorrectly configured PIM-to-PSM process will not generate the desired PSM results.
PIM to PSM to MDS best practices. This topic will be addressed in forthcoming reports (Figure 10). Simply put, the transformation to PIM to PSM to MDS involves both passing through truths generated from the PIM-to-PSM steps to the PIM-to-MDS step (where the PIM is the PSM output of the former step).
4.13. Sequence of content in MDS
In this Testbed activity, both PIMs (CityGML 3.0, DGGS) are implemented with a hierarchy of UML packages.
The information in the source information model may be presented in different sequences in the MDS according to external requirements. The sequence of content impacts how the integration of data from the model will be done, and needs to be planned for.
Take UML, as it was used in this Testbed activity, as an example. UML allows for the creation of package hierarchies, where a UML package can have sub-packages, and so on. This allows for a compartmentalized approach that promotes separation of concerns, potentially preventing confusion in its audience if the models were numerous.
In UML, UML objects within a UML package can be given a particular “sorting order”. Similarly, UML packages themselves, being UML objects, also belong to the same sorting order. The sorting order may or may not be alphabetic.
An MDS document, being a document, naturally provides a sequential sequence of content. When transforming a PIM into an MDS, the author must consider whether the UML object sorting order and the UML package hierarchy are to be reflected in the generated MDS.
It may therefore be necessary to indicate the ordering of model objects in the MDS through a declaration overriding the ordering of objects within the model; the ordering is specific to the target document, and not to the model.
NOTE It is said that Sparx Systems Enterprise Architect supports custom ordering of UML packages. If so, it is possible to have the MDS tool (Metanorma) support that encoded ordering if desired.
The decision on whether to adopt the UML object sorting order and package hierarchy may be based on the following considerations:
Backwards compatibility to a previous edition of the standard. If there is a previous edition of the MDS, an author may wish to retain clause numbering to match the previous edition, and have new UML elements appear after the last clause (or subclause) of the previous edition.
Example 1
The CityGML 3.0 MDS opted to use a “hybrid inclusion” approach with a fixed content sequence in order to retain clause numbering of the previous edition (CityGML 2.0 standard). Description of new model elements were appended after the last subclauses of the previous edition.
Conventions. In some OGC conceptual model standards, a convention is used for describing a UML package that first provides overview diagrams of the involved models, then tables and text that describe the details of those models. Each detailed section of models starts with the corresponding ModSpec requirement instance.
Example 2
The DGGS MDS uses the “automatic inclusion” approach, which implements a default order of first showing information of the UML package, then the diagrams it contains, then UML classes, then UML relationships.
Specific ordering needs. For a PIM based on UML, for example, classes may be presented aggregated by package, by diagram, or by model, and they may be sorted alphabetically or through dependency ordering.
Hierarchy presentation or flattening. UML packages can be nested multiple levels, and having a deeply nested document hierarchy makes the standard hard to read, and there is a possibility of running into governance issues (ISO only allows a maximum of 5 clause levels). An author may wish to free the document clause hierarchy from the UML package hierarchy.
In the prototypes (Clause 10.4, Clause 10.5), the following approaches were used:
In the DGGS prototype, the UML classes of the DGGS were presented in the same order as they were expressed in the source PIM, so the LutaML integration merely iterated through the UML classes in a single loop.
In the case of CityGML, the UML classes were presented in two clauses, one providing an overview of the models (20-010, Clause 7 “CityGML UML Model”), and one providing attribute detail (20-010, Clause 8 “CityGML Data Dictionary”)
This meant that the UML classes were iterated through in two separate loops, each extracting and presenting a different level of detail.
The order of presentation of the CityGML UML classes was also different from that in the PIM, with the classes already present in the previous version of CityGML presented first.
The differences in how the two documents presented their information may be summarized in Table 3.
Table 3 — Comparison of LutaML approaches between CityGML and DGGS
CityGML 3.0 | DGGS | |
---|---|---|
Document structure | Does not align with package hierarchy
| Identical to package hierarchy
|
Model representation structure | Flat | Hierarchical |
Model rendering style | Multiple styles on the same content: entity list vs data dictionary | Single |
4.14. Challenges with coordinating derived and supplementary truth
4.14.1. General
Supplementary truth applied to an MDS or a PSM is extraneous to the primary source information model, by definition, so it has to be planned as a separate activity outside the generation of the augmented truth.
4.14.3. Challenges with collaboration of MDS content
In the MDS prototypes for CityGML 3.0 and DGGS, the supplementary truth for the documents has been written as Metanorma text, and managed through Git in order to enable collaborative authoring and review of that text.
As with any collaboratively authored text, a certain amount of discipline is required around authoring, particularly as the structure of the supplementary truth is dependent on the given information model: the editor needs to ensure that the connection between supplementary truth and the information model is maintained.
There is an added coordination challenge where ideas need to be generalized across different component implementation teams for the same standard, working from the same information model.
4.14.4. Challenge to coordinate PIM annotations and supplementary truth to MDS
A further challenge is that some textual content of the MDS is not extraneous to the information model, but is included in the model as annotation.
The division between the two kinds of content needs to be planned for, to prevent confusion and duplication of effort, especially if the annotations and the supplementary truth are managed by separate teams, and risk either contradicting each other, or presenting information redundantly.
Coordination was proved necessary in the prototype: there needed to be guidance offered on what information to enter in Notes, and what syntax it should be expressed in (which has implications for the integration process).
It may be necessary to constrain the kind of content that can appear in either derived or supplementary truth, to prevent conflict and confusion.
In the MDS prototypes, LutaML iterates through objects from the information model as a block. So it presents each UML class derived from the PIM as a complete entity in the target Metanorma document; it would do the same for an object definition in XSD.
However, it is not currently possible for LutaML to interleave supplementary truth authored outside the model authoring tool with the presentation of an information model object: any commentary or annotation on a model object needs to be added after the object is presented in full. So authoring an MDS is somewhat inflexible: objects from the derived truth (including annotations out of the model management system) are presented as a block, and any commentary or discussion of the object need to occur as a block after the object. There is no current mechanism, for instance, to annotate particular parts of the object with comments as callouts, written in Metanorma.
Example
A note on a UML attribute cannot be interpolated from Metanorma into the PIM-derived tabular presentation of the class: it can only be added before or after the object rendering (provided for in LutaML as [.before] vs [.after] blocks).
This limitation leads to a division of labor in the current tooling: annotations within an object have to be added in the model authoring tool, and cannot include supplementary truth.
This challenge is an instance of the question of how to annotate externally sourced online content. That has been a longstanding concern with hypertext, and approaches have been devised to tackle it (e.g. W3C TR annotation-model). If interleaving supplementary and derived truth more fluidly in MDA proves desirable, LutaML can be expanded to support it better, harnessing such approaches to annotation.
That said, whether interpolating supplementary truth into model-derived artifacts is even desirable is unclear: it makes for more flexible authoring, but it can also lead to more difficulty in coordinating authoring, and it can make the document harder to read.
4.15. Tool experience and limitations
In the development of prototypes for the PIM-to-MDS and PIM-to-PSM activities where the PIM is a UML model, multiple compatibility gaps were discovered in the usage of selected tools for the MDA approach.
While all compatibility gaps have been closed as a consequence of this Testbed activity, mainly through the efforts of the Metanorma and to some extent the ShapeChange development teams, certain gaps that arise due to limitations of tool choices remain to be resolved.
Sparx Systems Enterprise Architect while being a popular tool for authoring UML models, provides generally a large amount of freedom to the model author to create UML models that are not conducive to the machine-interpretation functionality needed for a successful MDS approach:
EA provides a rich-text content area for annotations and notes for UML models and diagrams. However, this rich-text content area uses an outdated format (RTF) and is entirely independent from other UML models defined in the same model package. This means that content within a note in a UML model is unable to specify cross-references to another UML model in the same EA project.
EA allows entering OCL, which is commonly used with UML models, in specifying interfaces and machine logic. EA however does not implement any validation of OCL, which means that a downstream application using EA output can encounter erroneous OCL.
EA provides export capability for its diagrams. Typically, UML diagrams are best rendered in vector formats since they contain heavy use of shapes. However, EA can only export in the outdated, obsolete and proprietary Microsoft EMF format, which cannot be used in applications outside Microsoft Windows, as described in Clause 10.4.3. The EA implementation of EMF is even worse — it does not even conform to the Microsoft EMF specification — a correct implementation of EMF will display some objects in the EMF in a vertically flipped manner.
EA itself is not a cross-platform application. EA only works on Microsoft Windows. Moreover, EA itself is still currently a 32-bit Windows application despite 64-bit Windows being available as mainstay for years (EA Release 16, which is 64-bit, is in Beta as of January 2022). In OGC, many users utilize macOS and Linux systems, and in order to use EA they are forced to install the free and open source Wine software product, or the commercial flavor of CrossOver (the latter requiring an annual subscription). Note that EA has been proven to work on Ubuntu 20.04 LTS through version 7.0 of Wine.
EA itself is not suitable for usage in cloud systems, continuous integration and automatic generation of downstream model artifacts due to licensing limitations and the delivery model as a Windows application.
4.16. Suitability for cloud deployment, automated CI/CD workflows
The software engineering world has gradually adopted open-source software due to the ease and possibility of integrating those tools in cloud systems and the ability of those tools to be incorporated on continuous integration and continuous delivery workflows which are typically run on cloud systems.
Given that both Metanorma and ShapeChange are open-source applications, both tools can easily be incorporated into continuous cloud workflows as demonstrated in the prototypes.
In the case of PIM-to-MDS prototypes, the only manual step is the generation of the XMI export from EA for Metanorma consumption. Metanorma uses LutaML which directly parses the EA-proprietary profile of the XMI standard of the Object Management Group (OMG).
In the case of PIM-to-PSM prototypes, the only manual step is the copying of the EA JAR file from EA to ShapeChange, in order to allow ShapeChange to access the EA-proprietary project (EAP) format.
The limitation of these manual steps presented by EA prevents the PIM being cloud-managed and used in dynamic generation of MDSes and PSMs.
Given that the choice of model authoring tool may be constrained, the non-standard formats used by those tools will force additional labor in establishing workflows, and need to be considered as part of tool evaluation when pursuing MDA.
4.17. Future work
4.17.1. General
This section describes possible work to be done in the future. These are in addition to the findings and recommendations discussed above, which should all be addressed.
4.17.2. SMART standards and models
Because the subject matter of MDS is modelled in information models, MBA makes it possible for documentation to be oriented to both human audiences and machine audiences, as human-readable or machine-readable artifacts.
As described in this document, standards documents themselves are represented as and governed by information models. This means that the supplementary truth in those standards — the guidance and normative content itself — can be made machine-readable and machine-addressable.
The BR SMART initiative (see Annex C) currently underway harnesses this approach to make standard documents themselves fully machine-readable, including granular semantic modelling of normative statements and requirements.
This granular modelling also enables for the exportation to a semantic web-based information representation like W3C RDF.
The benefits of this initiative can be harnessed by OGC to derive greater benefit from its standards, for example in automated testing.
4.17.3. Cross-reference integration between PIM and MDS
References to bibliography and terminological entry, as supplementary truth, are managed in the Metanorma environment, as is appropriate for an authoring environment.
This poses a challenge when cross-references to those entries, or to document content (supplementary truth), need to be made as part of the derived truth, i.e. the content authored within the model management tool, in such places as annotations.
In the case of UML Class diagrams, that arises in case the classes incorporate commentary and annotations with cross-references, as human-readable content.
Because the references the annotations cross-reference are defined externally, in Metanorma, there is a risk that the cross-references and the references will fall out of sync during authoring: if a reference is updated in Metanorma, the author may not find it is disrupting a reference from the PIM until much later. This makes managing cross-references more laborious than if both the supplementary and the derived truth were managed in the same authoring environment.
NOTE Model-internal cross-references to other components of the same PIM, e.g. from one UML class to other UML classes, are much more likely to be well-defined through the tools used to manage the PIM itself, so they do not present the same level of challenge.
To manage external cross-references out of the PIM requires one of the following approaches:
Use a PIM tool that supports external definitions of cross-references.
Example 1
Sparx Systems Enterprise Architect UML class annotations can include Metanorma-formatted references to anchors that are defined in the Metanorma target document (e.g. as defined in <<ISO-639>>).
While this works, it tethers the PIM to a particular combination of authoring environment and definitions of anchors. This makes it more difficult to reuse PIM annotations in different documents, which might apply different anchor identifiers.
Reuse becomes even more difficult if the reference is to a clause in the target document: a naive document-internal reference may need to be changed to a bibliographic citation.
It also means that bibliography and terminology references need to be maintained separately in Metanorma and the UML authoring tool.
Cross-references are not made machine-readable in the UML authoring tool at all, and are left as pure text.
Example 2
In the PIM authoring tool, spell out references to standards documents as document titles. This approach was used during this prototype task.
While this avoids the problem, it also means that the document is semantically impoverished, and there is inconsistent presentation of cross-referenceable information between the derived truth and the supplementary truth in a standards document.
The proper solution to this challenge is tighter integration between Metanorma and PIM authoring tools.
Example 3
The PIM authoring tool and Metanorma could potentially share a bibliography plugin, or that Metanorma can import bibliographic information from the PIM (via LutaML) using a map that translates cross-references in PIM annotations into Metanorma cross-references.
4.17.4. ModSpec as PIM and ModSpec validation
Currently, ModSpec instances constitute supplementary truth in an MDS, as separately authored Metanorma content outside of the PIM. ModSpec instances can be encoded in Metanorma AsciiDoc or in the Metanorma-specific ModSpec-YAML format.
The Metanorma ModSpec authoring process today already provides some validation of ModSpec instances, such as:
providing a fixed structure for entering of ModSpec model attributes
warning if mandatory ModSpec model attributes are left empty
confirming that conformance tests have matching requirements, and vice versa
Even so, during the development of the prototypes, challenges were encountered as detailed in Clause 4.11 due to inconsistencies found, including:
inconsistent treatment of Conformance Test parts and Conformance Test steps (normative description differs from UML specification).
additional unsanctioned ModSpec attributes presented in some OGC Standards that requires adaptation of MDS tool.
usage of parameterization and conditionals in existing OGC Standards can differ from the ModSpec specification.
lack of testable formal requirements for ModSpec compliance.
It is recommended to:
Revise the ModSpec specification to resolve inconsistencies.
Create a dedicated ModSpec authoring and validation tool for ModSpec instances to be used in a modular fashion and shared between standards, as originally intended. Validation of ModSpec instances will improve the quality of requirements and their adoption.
Consider the possibility of machine-encoding of ModSpec for the purpose of automated testing and ModSpec validation, such as to ensure that conformance tests are satisfied by the model through automated testing.
In fact, Metanorma already provides a good basis of such implementation, by:
fully implementing the ModSpec information model.
accepting Metanorma AsciiDoc and YAML as input.
providing some ModSpec validation.
allowing the conversion of ModSpec into XML.
It would be possible for the Metanorma team to provide an open-source implementation for this purpose.
Once such a tool is developed, the ModSpec instances would be managed as an additional source of PIM primary truth (in addition to the original PIM), and integrated into the MDS transformation process just as is done with the PIM-to-PSM processes.
The resulting workflow would be automatic, and would not require manual input or adjustments.
5. Model specification technologies
5.1. General
Models are specified according to potentially one or more different technologies.
5.2. Unified Modeling Language (UML)
5.2.1. General
ISO/IEC 19501 specifies the UML modelling language, a graphical language for visualizing, specifying, constructing, and documenting the artifacts of a software-intensive system.
UML specifies a set of methodologies for developing technical artifacts used in the design of a software system, ranging from business processes and system functions to programming language statements, database schemas, and reusable software components. UML is often used to develop domain-specific models (e.g., geospatial information) used in system development.
In this Testbed task, the use of UML in documenting a PIM relies on the following functionality defined in UML:
For model definition, the definition of information models and their relationships, that contain human- and machine-readable components, and
For class diagrams, the visual arrangement of UML class relationships intended for human consumption only.
5.2.2. Modelling capability
5.2.2.1. Basic modelling elements
UML provides three (3) basic modeling elements:
Package
Class, and
Property
The usage of UML can extend beyond these modelling elements for these purposes:
System developers may sometimes require additional modeling capabilities beyond those defined in the UML standard.
System developers may need to attach a variety of types of information to models
Example
To guide the derivation of technology-specific implementations.
5.2.2.2. Extensions
UML provides three (3) built-in extension mechanisms that enable new kinds of modeling elements to be added to the modeler’s repertoire, as well as to attach “free-form” information to modeling elements. The extension mechanisms can be used separately or in combination to define new modeling elements that can have distinct semantics, characteristics, and notation relative to the built-in modeling elements specified by the UML metamodel.
These extension mechanisms are:
Stereotype,
Tagged Value, and
Constraint.
5.2.2.3. Stereotype
A stereotype is an extension mechanism that is used to extend a UML metaclass by enabling the use of platform- or domain-specific terminology or notation in place of, or in addition to, the ones used for the extended metaclass.
More than one stereotype may be simultaneously used to extend a UML metaclass.
Example 1
The «FeatureType» stereotype applied to a UML Classifier (class) might indicate that in an implementation a spatial representation will be assigned and spatial indexing should be implemented.
Example 2
The «identifier» stereotype applied to a UML Attribute property might indicate that the property value may be used as the Primary Key in a relational implementation.
5.2.2.4. Tagged value
A tagged value is an extension mechanism that is used to define (as a “tag definition”) a stereotype-specific characteristic that extends a UML model element (package, class, property) with additional information (as a “tagged value”).
Different stereotypes for a given UML metaclass may specify different sets of tag definitions. A given tag definition may be associated with more than one stereotype.
Example 1
A definition tagged value may be assigned to a model element in order to store a “concise definition of the element”
Example 2
A version tagged value may be assigned to store configuration management information for that element.
5.2.2.5. Constraints and Object Constraint Language (OCL)
A constraint is an extension mechanism that is used to express characteristics of a model that cannot be expressed in the UML class diagram notation. For example, a validation constraint that the allowed values of two properties interact and only certain patterns of values are allowed.
Constraints are usually expressed using the formal notation of ISO/IEC 19507:2012.
5.2.2.6. UML Profile
A collection of coordinated UML extensions may be documented in the form of a UML Profile. A UML Profile consists of a well-specified set of stereotypes, tagged values, and constraints that collectively specialize and tailor the UML for a specific domain (e.g., geospatial information modeling) or process.
A profile does not extend UML by revising the UML metamodel. Instead, it provides conventions for applying and specializing standard UML metamodel concepts to a particular environment or domain.
5.2.3. Application to geospatial standards (ISO 19100-series UML Profile)
5.2.3.1. ISO 19103:2015 Geographic information — Conceptual schema language
ISO 19103:2015 provides rules and guidelines for the use of a conceptual schema language to model geographic information, and specifies a profile of UML.
That profile includes six stereotypes:
«Interface» (formerly «Type») is an abstract classifier with operations, attributes and associations, which can only inherit from or be inherited by other interfaces (or types).
«DataType» is a set of properties that lack identity (independent existence and the possibility of side effects). A data type is a classifier with no operations, whose primary purpose is to hold information.
«Union» is a type consisting of one and only one of several alternative datatypes (listed as member attributes); this is similar to a discriminated union in many programming languages.
«Enumeration» is a fixed list of valid identifiers of named literal values. Attributes whose range type is an enumeration may only take values from the fixed list.
«CodeList» is a flexible enumeration that uses string values for expressing a list of potential values. The allowed values are often held and managed using an online register.
«Leaf» is a package that contains only classes (packages are disallowed).
The names of stereotypes are not case-sensitive. Stereotypes are essential in the derivation of PSMs from PIMs. Generally speaking, stereotypes can act as flags to determine how to create implementation models from abstract models.
The ISO 19103:2015 profile of UML also includes one tagged value:
codeList, applies to stereotype «CodeList»: Code lists managed by a single external authority may carry a tagged value “codeList” whose value references the actual external code list. If the tagged value is set, only values from the referenced code list are valid.
The ISO 19103:2015 profile of UML is summarized in Figure 13.
Figure 13 — ISO 19103:2015 stereotypes and keywords
5.2.3.2. ISO 19109:2015 Geographic information — Rules for application schema
ISO 19109:2015 defines rules for creating and documenting application schemas (conceptual schemas for data required by one or more applications), including principles for the definition of features, a fundamental unit of geographic information. As part of the general rules for application schemas it specifies the “General Feature Model” (GFM), the meta-model for application schemas.
The ISO 19109:2015 profile of UML that is used as the conceptual schema language for application schemas adds the critical «ApplicationSchema» (package) and «FeatureType» (class) stereotypes as well as three important tagged values that apply to both of these stereotypes:
designation
Natural language designator for the element to complement the name. Optional, with multiple designations allowed in order to support different languages.
definition
Concise definition of the element. One definition is mandatory. Additional definitions can be provided in multiple languages if required.
description
Description of the element, including information beyond that required for concise definition but which may assist in understanding its scope and application. Optional, with multiple descriptions allowed in order to support different languages.
The ISO 19109:2015 profile of UML is summarized in Figure 14:
Figure 14 — Summary of ISO 19109:2015 profile of UML
5.2.4. ISO 19118:2011 Geographic information — Encoding
ISO 19118:2011 specifies the requirements for defining encoding rules for use for the interchange of data that conform to the geographic information in the set of International Standards known as the “ISO 19100 series”. It specifies requirements for creating encoding rules based on UML schemas, requirements for creating encoding services, and requirements for XML-based encoding rules for neutral interchange of data. It specifies a profile of UML that includes eight stereotypes, two of which are not previously defined similarly by either ISO 19103:2015 or ISO 19109:2015.
These are:
«BasicType» is defined in ISO 19118:2011, Clause C.2.1.2:
“Defines a basic data type that has defined a canonical encoding.” Additionally stated is that: “This canonical encoding may define how to represent values of the type as bits in a memory location or as characters in a textual encoding. Examples of simple types are integer, float and string.”
Also from ISO 19118:2011, Clause C.5.2.1.1:
“A class stereotyped «BasicType» shall be converted to a simpleType declaration in XML Schema. Any of the data types defined in XML Schema can be used as building blocks to define user-defined basic types. The encoding of the basic types shall follow the canonical representation defined in XML Schema Part 2: Datatypes.” (W3C TR xmlschema-2)
+ NOTE: The different types are not clearly defined in ISO/TS 19103:2005 and neither is the «BasicType» stereotype used. The following declarations, therefore, follow a subset of the data type definitions in W3C TR xmlschema-2. Declared are the types: Number, Integer, Decimal, Real, Vector, Character, CharacterString, Date, Time, DateTime, Boolean, Logical, Probability, Binary, and UnlimitedInteger (where the symbol “*” is used to represent the infinite value).
«Interface» From ISO 19118:2011, Clause C.2.1.2:
“Defines a service interface and shall not be encoded.”
This definition is inconsistent with that of the subsequently published ISO 19103:2015. While this inconsistency may be useful in contexts where it is clear which definition applies, in general it is undesirable to overload the meanings of stereotypes within the OGC community, and in particular thereby coming into conflict with a stereotype specified in ISO 19103:2015.
While the stereotype «Interface» as defined in ISO 19118:2011 can be (and is here) subsequently ignored, the stereotype «BasicType» is used in the CityGML 3.0 Conceptual Model where it results in difficulties given its tie to a specific encoding technology — XML Schema — and thus lack of true platform independence. The CityGML 3.0 Conceptual Model redefines the stereotype «BasicType» to mean “defines a basic data type”, which is both circular and differs from that of ISO 19118:2011.
ShapeChange adopts a somewhat different definition for stereotype «BasicType» than either ISO 19118:2011 or the CityGML 3.0 Conceptual Model: (https://shapechange.net/app-schemas/uml-profile/#Stereotypes_of_classes)
Marks a so-called basic type, which can have a simple representation in one or more target encodings. It usually is a restriction of CharacterString or Number - or a structured version thereof (e.g., “one two three four” — or any other meaningful combination of such types that is supported by a given encoding).
5.2.4.1. ISO 19136-1:2020 Geographic information — Geography Markup Language (GML) — Part 1: Fundamentals
ISO 19136-1:2020 specifies an XML-based encoding (consistent with ISO 19118:2011) for the transport and storage of geographic information modelled in accordance with the conceptual modelling framework used in the ISO 19100 series of International Standards, including both the spatial and non-spatial properties of geographic features. It specifies normative rules for the mapping of ISO 19109-conformant UML application schemas to corresponding GML application schemas based on XML Schema.
The ISO 19136-1:2020 profile of UML follows that of ISO 19109:2015 (and thus ISO 19103:2015) while adding numerous tagged values to packages, classes, and properties (Figure 15).
Figure 15 — Tagged values in the ISO 19136-1:2020 profile of UML
A valid UML Application Schema conforms to the conceptual schema rules specified in ISO 19103:2015 and the application schema rules specified in ISO 19109:2015.
A GML-ready UML Application Schema also conforms to the general encoding requirements of ISO 19136-1:2020. Those encoding requirements are summarized in Annex A. They identify required patterns and uses of UML elements, stereotypes, and tagged values based on the ISO 19109:2015 General Feature Model and the necessity of ensuring consistent application of the ISO 19136-1:2020 encoding rules.
5.2.5. Tools
In order to develop UML models for PIM-to-PSM and PIM-to-MDS purposes, it is necessary to define a toolchain that can interoperate from PIM to PSM and MDS stages for model transformation and downstream representations.
Various software tools exist to author UML models, and also to read such models.
5.2.5.1. Sparx Systems Enterprise Architect (EA)
Sparx Systems Enterprise Architect is widely used in OGC and ISO/TC 211 for the authoring and management of UML models.
Sparx Systems Enterprise Architect is historically a 32-bit Windows application:
With the release of EA Version 15 a 64-bit Windows application may access an EA project file.
With the upcoming release of Version 16 (in Beta mode as of January 2022), EA will be a 64-bit Windows application.
The UML artifacts it generates are the input to both ShapeChange, for generating PSMs (Clause 7.1), and to Metanorma and LutaML (Clause 7.2), for generating MDS.
5.2.5.2. ShapeChange
ShapeChange is an open-source tool for model conversions. It can read Sparx Systems Enterprise Architect project files using code provided by the Sparx Systems Enterprise Architect JAR file.
It is used to generate PSM outputs such as XML Schema, JSON Schema and RDF outputs from PIMs in the Sparx Systems Enterprise Architect format.
Through integration with EA, ShapeChange can access native EA artifacts directly, and then export the native EA project file into the XMI format (OMG XMI 2.5), then convert the exported XMI into the ShapeChange XML (SCXML) format.
5.2.5.3. LutaML and Metanorma
LutaML is a universal data model accessor that supports both UML and XMI, and is part of the Metanorma software suite which facilitates the generation of MDS documents.
Metanorma provides a LutaML plugin that allows Metanorma authors to access information models from various modelling languages, including UML and EXPRESS. Specifically, it supports parsing and accessing UML written in the XMI format, including the Sparx Systems Enterprise Architect profile of the XMI format.
LutaML can access UML packages stored in Sparx Systems Enterprise Architect project files by first exporting the UML package into the XMI format, of which the LutaML-XMI plugin can consume.
5.3. Resource Description Framework (RDF)
W3C RDF is a standard for representing graph data in terms of the Semantic Web, with Linked Data used to define subjects of description, as well as vocabularies for predicates, expressing attributes of entities and relations between entities, and predicate values, where these can be formally defined as discrete enumerations. It is widely used in semantically-informed description of data. RDF in MDA is extended through two common profiles in the Semantic Web domain:
Web Ontology Language (W3C OWL, used to define ontologies and data domains and ranges; and
Simple Knowledge Organization System (SKOS: W3C TR skos-reference), used to define hierarchical controlled vocabularies.
RDF can be used, like UML, to express PIMs which rely on notions of entities, inheritance, and attributes. The enhancement of RDF through OWL makes it more straightforward for RDF to model inheritance, while SKOS is used to model the constrained enumerations essential to MDA. Clause 9 reports on the testbed sub-task D143, where the use of RDF and OWL was investigated as an alternative to UML for driving MDA within OGC.
5.4. OGC Standard for Modular specifications
5.4.1. General
OGC 08-131r3 “The Specification Model — A Standard for Modular specifications”, also known as the ModSpec, contains requirements and conformance classes for writing standards to be used for any document whose eventual purpose is the specification of requirements for software, services or data structures.
OGC 08-131r3, Introduction helpfully uses an example from Thomas the Tank Engine, who strives to be a “really useful engine”, to explain its motivation in making standards useful.
A standard’s usefulness and hence worth can be measured by:
The ease with which it can be implemented.
The number of times it has been implemented.
The number of times those implementations are used.
The ease with which those implementations interact.
The number of times it has been extended through inclusion in other useful standards.
The intention of ModSpec is to enable interoperability of implementations, and the standard concludes that in order to validate requirements across implementations, it is necessary for conformance tests to be re-useable and organized in an effective manner. It achieves that by providing a standardized set of information models for these requirements and tests.
5.4.2. ModSpec models
ModSpec provides a set of information models towards this goal, as defined in OGC 08-131r3, Clause C.2, in UML, described below.
NOTE 1 The order of these described models differ from the ModSpec standard for clarity of conceptual coherence.
Container:
Specification (OGC 08-131r3, Clause C.3). A specification is a container, a namespace for a set of ModSpec model instances. It represents a “standard”, such as an OGC or ISO standard.
Related to specification:
Normative statement (OGC 08-131r3, Clause C.8). A normative statement.
Requirement (OGC 08-131r3, Clause C.9). A requirement is a normative statement that is required in an implementation. It links to at least one conformance test which, when passed, confirms the satisfaction of the requirement.
Recommendation (OGC 08-131r3, Clause C.10). A recommendation is a normative statement that presents optional but recommended functionality. There may or may not be a conformance test associated with it.
Permission (OGC 08-131r3, Clause 4.20). A permission is a normative statement that is entirely optional. While this model type is not directly defined in the ModSpec standard, it is described at OGC 08-131r3, Clause 4.20. There may or may not be a conformance test associated.
Requirements class (OGC 08-131r3, Clause C.6). A requirements class represents a coherent feature set. A requirements class can depend on other requirements classes and requirements modules, and applies to a standardization target type.
Requirements module (OGC 08-131r3, Clause C.7). A requirements module represents a coherent set of requirements needed by a feature. It is composed of a set of requirements.
Related to verification:
Conformance suite (OGC 08-131r3, Clause C.4). A conformance suite is a set of conformance classes. It is intended to represent a set of conformance classes that represent a “feature set” intended to test an implementation.
Conformance class (OGC 08-131r3, Clause C.5). A conformance class is a set of conformance tests, and links to at least one requirements class. Conceptually it represents a “feature” of an implementation. Implementations may claim conformance to a “conformance class” for a feature that was validated.
Conformance test (OGC 08-131r3, Clause C.11). A conformance test represents a functional test intended to validate an implementation function. A conformance test is allowed to have separate parts and hierarchical steps (OGC 08-131r3, Clause C.11). A conformance test can be abstract, i.e. requires additional information to be executable.
NOTE 2 See Annex D.1 for a discussion of the validity of test parts and test steps.
Abstract test. An abstract test is simply a conformance test that is abstract. While the term “abstract test” is not formally defined by ModSpec, it is heavily used in OGC Standards (and to that extent, standards published by ISO/TC 211).
Abstract test class. An abstract test class is a conformance class that only contains abstract tests. It is not formally defined by ModSpec but is used widely in OGC Standards.
Abstract test suite. An abstract test suite is a conformance suite that only contains abstract tests. It is not formally defined by ModSpec but is used widely in OGC Standards.
Role:
Standardization target (OGC 08-131r3, Clause C.12). An entity to which some requirements of a standard apply.
Standardization target type (OGC 08-131r3, Clause C.13). The type of entity or set of entities to which the requirements of a standard apply.
5.4.3. Usage of ModSpec in OGC
According to the OGC Policy Directives, OGC Standards that contain requirements must have those requirements conform to OGC 08-131r3. Therefore, all OGC Standards are required to utilize ModSpec defined models in the representation of specification and verification mechanisms.
By using these information models, requirements from different OGC Standards can in effect be considered “modular”, i.e. these requirements can coexist in the same standard without being in conflict.
The ModSpec models themselves are abstract information models, and in order to use them, OGC Standards are closely gated by the OGC Standards team to have “instantiated” ModSpec models with the following requirements:
Each ModSpec model instance has a unique identifier in form of an OGC-wide unique URI
The linkages between the defined ModSpec model instances are validated to be correct and consistent.
The ModSpec model instances are published in the OGC Definitions Server.
Prior to this Testbed deliverable, the above steps and validation are often performed manually, which presents a heavy burden on both the standardization project team and the OGC editorial team.
In the course of this Testbed, we have found certain issues in the ModSpec standard that were resolved. Details are documented in Annex D.
5.5. Metanorma
5.5.1. General
As described in Clause 3.10.5, Metanorma is an open-source framework for creating and publishing standardization artifacts with the focus on semantic authoring and flexible output support.
Metanorma provides a model-based documentation system and prioritizes automation.
Overall, Metanorma provides the following items:
a set of standard document metamodels (ISO/AWI 36100), called “Metanorma StanDoc”, that allows different standardization bodies to create their own standardized document model for their standard documents;
a standard XML schema (ISO 36300), as machine-readable standardization documents, that is the serialized form of the document models mentioned above; and
a publishing toolchain that enables authors of standard documents to handle their documents from authoring to publishing in an end-to-end, “author-to-publish” fashion.
The canonical output of Metanorma is an XML file that represents an ISO/AWI 36100 model tree.
In addition, the Metanorma technology suite also provides:
standards metadata specification capability, based on ISO 36200, a set of metamodels for the development of organization-specific bibliographic item models from ISO 690, the international standard for citations and references
ability to encode concepts (and terms and definitions) in interoperable formats in accordance with the ISO 10241-1 and ISO 704 standards
ability to directly access certain information models types through the Ribose LutaML model parsing engine, including:
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
ISO/TC 184/SC 4/TF 1 uses Metanorma to annotate EXPRESS schemas resulting in model-derived documentation of EXPRESS schemas.
5.5.2. Usage in OGC
“Metanorma for OGC” is the implementation of Metanorma for OGC. It has been approved as an official way to publish new OGC Standard documents since 2021-09-17, with Metanorma-based document templates subsequently approved by the OGC Document SubCommittee on 2022-02-25.
Metanorma for OGC documents are created in the Metanorma AsciiDoc format. Metanorma AsciiDoc is a textual syntax for preparing a ISO/AWI 36100 compliant document model tree which can be rendered in a variety of presentation formats. In OGC, the supported rendering formats are PDF, HTML, Microsoft Word, and ISO/AWI 36100 XML.
Metanorma for OGC differs from typical Metanorma in the following critical ways:
supports specification of OGC Standards metadata, including document types, stages, identifiers and authorship;
supports specification of OGC ModSpec (OGC 08-131r3) model instances through a specialized syntax.
Figure 16 shows the range of models used in Metanorma, including the OGC-specific use of OGC ModSpec.