AHG 05 Report
ISO/TC 211 Geographic information/Geomatics
Draft final report: Knut Jetlund, 2022-04-09
[TOC]
| Abbreviation | Full name |
|---|---|
| EA | Enterprise Architect |
| HM | The ISO/TC 211 Harmonized UML Model |
| HMMG | The ISO/TC 211 Harmonized Model Maintenance Group |
| MLGT | The ISO/TC 211 Multi-Lingual Glossary of Terms |
| MDD | Model-Driven Documentation |
| MDA | Model-Driven Architecture |
| UML | Unified Modelling Language |
| TMG | The ISO/TC 211 Terminology Maintenance Group |
This ad hoc group was established by CIB Resolution 2020-05 in June 2020:
Ad hoc group on automated documentation
ISO/TC 211 resolves to establish an ad hoc group to study machine-readable normative statements and model-driven documentation of standards. The previous work from the ad hoc group on producing documentation from UML models (Resolution 633) shall be taken into consideration. The ISO/TC 211 appoints the HMMG Convenor to lead the ad hoc group. The ad hoc group shall present a report of their findings during the next plenary week at the Resources meeting.
| Role | Appointed by | Country | Salutation | Last name, First name |
|---|---|---|---|---|
| Convenor | ISO/TC 211 | Dr | Jetlund, Knut | |
| Convenor/Secretary Support Team | SIS | Sweden | Ms | Allansson, Christine |
| Convenor/Secretary Support Team | SIS | Sweden | Mr | Åhlin, Mats |
| Committee member | ANSI | United States | Mr | Heazel, Charles |
| Committee member | ANSI | United States | Dr | Herring, John |
| Committee member | ANSI | United States | Mr | Stolarz, David |
| Committee member | DIN | Germany | Mr Dipl.-Phys. | Portele, Clemens |
| Committee member | DS | Denmark | Ms | Vanparys, Heidi |
| Committee member | JISC | Japan | Mr | Plews, Reese |
| Committee member | KATS | Korea, Republic of | Dr | Heo, Min |
| Committee member | KATS | Korea, Republic of | Dr | Kim, Eun-Hyung |
| Committee member | KATS | Korea, Republic of | Mr | Kim, Kyung Min |
| Committee member | KATS | Korea, Republic of | Mr | Lee, Jeong Eun |
| Committee member | KATS | Korea, Republic of | Ms | Lee, Jin Hui |
| Committee member | KATS | Korea, Republic of | Prof. | Lee, Yong Ho |
| Committee member | KATS | Korea, Republic of | Ms | Oh, Min Young |
| Committee member | NZSO | New Zealand | Mr | Gibb, Robert |
| Committee member | SCC | Canada | Mr | Spears, Tobias |
| Committee member | SIS | Sweden | Ms | Bengtsson, Lena |
| Committee member | SIS | Sweden | Ms | Engberg, Agneta |
| Committee member | SN | Norway | Mr | Karge, Magnus |
| Liaison representative (organizations) | CalConnect | Mr | Tse, Ronald Henry | |
| Liaison representative (organizations) | CalConnect | Dr | Wong, Wait Kit | |
| Document monitor | AFNOR | France | Mme | Dégardin, Martine |
| Document monitor | DIN | Germany | Mrs M. Sc. | Pfeifer, Sarah |
| Document monitor | JISC | Japan | Mr | Noda, Takaaki |
| Technical programme manager | ISO | Mr. | Dryden, Andrew |
The work in AHG 5 has been based on a discussions in a series of ten meetings:
| Meeting # | Date | Main topics | Minutes |
|---|---|---|---|
| 1 | 2020-10-27 | Experiences and prerequisites for MDD | 20201027 Minutes |
| 2 | 2020-12-16 | Sources and processing for MDD | 20201216 Minutes |
| 3 | 2021-01-13 | Sources and processing for MDD | 20210113 Minutes |
| 4 | 2021-02-23 | Sources and processing for MDD Model for normative statements |
20210223 Minutes |
| 5 | 2021-03-16 | Conceptual model of normative statements | 20210316 Minutes |
| 6 | 2021-04-23 | Conceptual model of normative statements | 20210423 Minutes |
| 7 | 2021-05-20 | Conceptual model of normative statements | 20210520 Minutes |
| 8 | 2021-09-30 | The conceptual model of a modular specification Examples of MDD |
20210930 Minutes |
| 9 | 2021-10-28 | Towards a TC211 good practice on document style | 20210028 Minutes |
| 10 | 2021-11-25 | AHG Report | 20211125 Minutes |
The draft conceptual model of a modular specification is a further development and extension of the conceptual UML model for conformance and testing in Annex B of ISO/DIS 19105 (2021), and incorporates elements from the OGC Modular Specification.
NOTE: The conceptual model is a draft that need further development through a formal ISO/TC 211 project.
Figure 1: Draft conceptual UML model for a modular specification
The UML model in ISO 19105 is merely an illustration of the concepts in a modular specification. In order to prepare the model for implementation and MDD, we made the following improvements:
- Specified navigability on associations.
- Specified multiplicities on association ends.
- Defined role names for navigable association ends.
- Moved role names that were placed at the wrong association end.
- Changed role names that were not NCNames.
- Added attributes for identification and test descriptions.
Besides, elements from the OGC Modular Specification were implemented as extensions to the ISO 19105 model:
- Classes for normative statements (Requirement, Recommendation, Permission)
- A Class for the Specification Target (Standardization Target)
A class for External Specification.
Abstract class that defines attributes for identifiers, for use in several classes in the model. The classes ConformanceClass, RequirementsClass, AbstractTestCase, NormativeStatement and SpecificationTarget are all subclasses of IdentifiedObject.
-
URI (1..1) : The main identifier of the object. To be defined according to the ISO/TC 211 URI Structure.
-
name (1..1) : The local name (identifier) within the document. Can be a string (e.g., "multi-curve") or a number (Requirement 1). If used, prefixes that represents the type of IdentifiedObject should be written as whole words (for example, "Requirement 1", not "Req 1").
An alternative and more descriptive name of this property could be localId. However, we recommend the term name, for direct implementation as the core property name in the UML profile.
- text (0..1) : Description of the IdentifiedObject.
The text property is implemented as the core property documentation (notes in the EA user interface) in the UML profile.
Abstract class which is the superclass for the concrete classes Requirement, Recommendation and Permission. The class is a subtype of IdentifiedObject. A normative statement can be a hierarchy of sub statements.
- externalReference (0..*) : Link to an external reference for the normative statement.
- subStatement (0..*) : Reference to a sub statement for the normative statement.
The specification target for a requirement class.
An external specification that a requirements class depends on.
The conceptual model may be implemented in several technologies. We tested a UML profile and an OWL Ontology in our work.
A challenge for the practical use of the conceptual model may be how to get Project Teams to develop modular specifications as implementations of the model. EA and the UML profile has a user thershold, and so do tools for writing RDF according to the OWL Ontology. The suggested approach from the ad hoc group is that for now, we follow the UML profile approach, where the modular specification can be described together with the conceptual model of the specification in question. An RDF representation according to the OWL Ontology may be exported for further use. However, a specification described directly in RDF may be a better option in the future, depending on the modelling approach ISO/TC 211 will select to follow in general.
A template of a modular specification in EA may be useful for Project Teams. Besides, export and import to and from spreadsheets etc may also be useful for maintaining content.
Implementation as a UML Profile has the advantage that conformance tests and normative statements can be modelled and maintained together with the main model for the specification.
In our implementation, all UML classes from the conceptual model are implemented as extensions of the metaclass Class. Originally, several classes were implemented as UML packages. However, an implementation as classes gives the advantage that associations can be created from e.g. a requirements class to something else, e.g. to indicate the specification target of a requirements class. Which then again could make it possible to ask questions like "Which requirements classes standardize application schemas?".
Tagged values in EA can only contain 255 characters, which proved to be an issue for requirement texts. Sparx has a workaround. However, we consider that a better and more user-friendly option is to use the Notes field (UML documentation) for implementation for the text attribute.
Figure 2: Draft UML Profile implementation of the conceptual model.
Figure 3: Example modular specification based on the UML Profile.
Figure 4: Example test cases and requirements based on the UML Profile.
An implementation in XML Schema can easily be derived from the conceptual model and may be used for implementation in XML files.
An implementation as OWL Ontology can be derived from the conceptual model and may be used for implementation in RDF files. Some manual preparation may be needed.
Figure 5: Example OWL ontology representation of the conceptual model.
Figure 6: Example RDF implementation of the requirements class content in ISO 19131.
Figure 7: Example RDF implementation of the requirements extent in ISO 19131.
The conceptual models presented in this report is a draft model, discussed and tested briefly in the ad hoc group. The model should be further developed and tested, and then formalized for further use. There are several possible solutions for a formalization, and we consider three of these to be the most probable:
-
Internal ISO/TC 211 document without any formal standardization.
-
Addendum to, or revision of, ISO 19105.
-
Individual standardization project, as Technical Specification, Technical Report or International Standard.
The model may very well be used by other communities as well, not only internally in ISO/TC 211. For example, in international domain models, or regional and national specifications.
We did not reach a final conclusion, but we consider the most likely approach would be a NWIP for a TR/TS. However, we recommend to gain some experiences with implementations of the draft model first.
Besides, the model should be harmonized with the parallel work in OGC, focusing on establishing a common conceptual model for modular specification in the two organizations.
We have discussed sources and possible processing for MDD for different parts of the standards documents. These are summarized in Table 1, and further discussed in the subsequent sections.
| Documentation part | Possible derivation from a UML model | Written text (MS Word, AsciiDoc etc) | Other sources |
|---|---|---|---|
| Normative references | Can be dervied from dependencies in the UML model. | Manual editing may be required in addition. Some normative references cannot be expressed in UML. | |
| Terms and definitions | Written text with new defintitions | Existing definitions could possibly be exported from Geolexica | |
| Conformance | Should be the derived from an implementation of the modular specification model (UML, XML or RDF). | ||
| Normative statements | Should be the derived from an implementation of the modular specification model (UML, XML or RDF). | Some manual editing may be required in addition, for combining with model documentation and supporting documentation. | |
| Model documentation | Should be derived from the UML model of the standard, including all definitions. | Some manual editing may be required for combining with supporting documentation. | |
| Supporting documentation | May need to be combined with derived documentation. | ||
| Abstract test suite | Should be the derived from an implementation of the modular specification model (UML, XML or RDF). |
Table 1: Overview of sources and processing for MDD.
It is possible store and derive much information from UML models. However, three matters need to be concidered:
- We should not put information into the UML model that can be easier maintained elsewhere or try to use UML outside of its purpose. EA is a UML tool, not a word-processing tool.
- There must be a balance between the effort put into automated documentation and the output achieved. If it gets too complex to derive some part of the documentation, it may not be worth doing it automatically.
- Automation that depends heavily on specific EA functionality or specific EA XMI files should be avoided as far as possible, in order to be interoperable.
In general, we consider early involvement with project teams to be essential for implementation of MDD as a way of working. The efforts and requirements should be demonstrated early in the project.
We have discussed the formatting of the URIs in documents, as input to the description of an ISO/TC 211 good practice on document style. Preferably, the URIs should be complete in the documents (for example, https://standards.isotc211.org/19131/-/2/req/content/specification-language), and not fragments (for example, /req/content/specification-language). Furthermore, they should be resolvable to an address where the content is described. This is useful, for example, for automated conformance testing: An error message could link to the requirement for further explanation.
However, as this setup has caused some concerns in ISO CS, our suggested approach is:
Each document shall contain a core URI to be used for the modular specification (for example,
https://standards.isotc211.org/19131/-/2). The core URI shall be resolvable, leading to a page that contains a list of all identified objects (instances of subtypes of IdentifiedObject) (only identifier and name) for this modular specification, but no further information.URIs for identified objects (instances of subtypes of IdentifiedObject) shall be written as fragments (for example,
/req/content/specification-language) and shall be formatted as normal text, not as hyperlinks.Each identified requirement shall have only one specified requirement. Several parts can be handled as linked requirements.
The clause on normative references in ISO documents contains a formatted list of standards that the document in question have a normative reference to.
- A UML model that defines the main content of a standard (not the modular specification model) will normally contain references to other standards. It is possible to derive a list of normative references based on dependencies in the UML model. A script may be developed for summarizing references per main standards package in the HM and export to a file, or Metanorma (or other tools) may extract the information directly from the UML model.
- Manual editing will probably be required in addition, as some standards have normative references that cannot be expressed in UML. Besides, some standards don't have a UML model at all.
The clause on terms and definitions contains a formatted list of terms that are relevant for the document in question. Existing terms can be defined in the MLGT or in other sources, while new terms are defined by the standard in question.
- The list of existing terms that are relevant for a specific standard may be generated automatically, based on an analysis of the terms used in the document.
- TMG and Ribose plan to implement a vocabulary service for Geolexica that may be used for existing terms from the MLGT.
- New terms must be added manually.
The clause on Conformance and the annex on Abstract Test Suite contain tables and/or lists of conformance classes and tests for evaluation. There is a close relationship between the abstract test suite, conformance classes and requirements, as can be seen in the draft conceptual model of a modular specification.
- By describing the standard as a modular specification according to the draft conceptual model, the two document parts may be derived from the modular specification model.
Therefore, conformance classes and abstract test cases should be described according to the draft model of a modular specification.
The ISO directives, part 2 describes different kinds of expressions of provisions, with rules for verbal forms, stating that
"The user of the document shall be able to identify the requirements he/she is obliged to satisfy in order to claim conformance to a document. The user shall also be able to distinguish these requirements from other types of provision (recommendations, permissions, possibilities and capabilities)."
In the draft conceptual model of a modular specification, we have defined the three kinds of provisions that are most commonly used in ISO/TC 211 standards as subtypes of a class NormativeStatements: Requirements, Recommendations and Permissions. Among these, Requirements are the only provisions that are tested for conformance.
NOTE: The term Normative Statementis also used for a supertypes of these three types of provisions in the OGC Modular Specification.
NOTE: There are significant differences between the expressions of normative statements and conformance classes from standard to standard. Some requirements are closely related to elements defined in the main UML model of a standard (not the modular specification model), while others are independent of model elements. Independent of this, a model of a modular specification will be a model of its own, where requirements can be defined and related other elements or not.
- By describing the standard as a modular specification according to the draft conceptual model, normative statements and their relations to conformance classes and abstract test suites may be derived from the modular specification model.
Therefore, normative statements and their relations to conformance classes and abstract test cases should be described according to the draft model of a modular specification.
Some manual editing of the document may be required in addition, for combining the normative statements with the model documentation and supporting documentation.
For the formatting of documents, we will emphasize that there needs to be some way of separating the text of normative statements from the rest of the document.
UML models have been used for describing the main content of the majority of ISO/TC 211 standards. Therefore, a previous ad hoc group initiated by ISO/TC 211 investigated whether and how documentation can be produced from UML models. The scope of the previous group did not explicitly state which models that should be documented, but they focused on the UML models in the HM and the documentation of these in ISO documents.
However, such documentation tools should be applicable for any UML model modelled according to ISO 19103, regardless of their inclusion in the harmonized model. Automatic generation of documentation of UML models would also be useful for UML application schemas at global, regional and national level.
- The documentation of the tools is available in the [report on Automatic generation of documentation from UML models](https://github.com/ISO-TC211/UML-Best-Practices/blob/master/DocumentationOfUMLModels/Automatic generation of documentation from UML models.docx)
- A documentation template for Enterprise Architect is available at EA-template
- Shape Change configuration and a demo UML model is available at ShapeChange
More recent work by OGC and Ribose, and in the ISO/TC 211 standard ISO 19170-1 has proved how alternative tools such as Metanorma and AsciiDoc can be used for production of model documentation. These tools has the ability to update already derived documents from changes in the UML model, instead of not just deriving a new report.
The model documentation is the main outcome of the UML model, with two main parts that are either interwoven or in separate clauses of the document:
- Documentation of the model in diagrams with supporting text.
- Data dictionary with tables that lists the content of the UML model.
The source for the model documentation and data dictionary in ISO/TC 211 documents should always be the UML model.
In order to succeed with an automated documentation of UML models, it is vital that the models are complete and modeled according to modeling rules in ISO 19103 (and possibly ISO 19109, depending on the level of abstraction). Completeness is essential, in particular definitions at all levels in the model. Furthermore, a model must be structured as a story with diagrams in correct order to ensure the correct order in the document.
Some manual editing of the document may be required in addition, for combining the model documentation with normative statements and supporting documentation.
Not every aspect of a standard is fit for describing in UML. Some extra documentation will mostly be needed. This supportive documentation can be written i text editors such as AsciiDoc or Word or and needs to be combined with the derived model documentation and normative statements.
The current experiences with MDD in ISO/TC 211 and OGC are mainly limited to model documentation (figures and data dictionary). As the draft conceptual model of a modular specification was developed in this Ad hoc group, there are no standards yet where the model has been implemented. However, several standards projects have started to describe normative statements in UML. First and foremost, the revision project for ISO 19103 is following the draft model.
With the help from Ribose Inc., several recent standards documents (or parts of the documents) have been produced based on MDD:
The full model documentation in the ISO 19170-1 standards document was generated from the ISO/TC 211 HM. A previous version was derived from a ShapeChange Metanorma AsciiDoc export of the UML model, but the final version was generated with direct access to the Enterprise Architect project from Metanorma.
The document structure follows the order and hierarchy of the UML packages. Each subpackage of the main standard becomes a main clause in the document (6, 7, 8), with diagrams and a full textual documentation integrated in these clauses.
Requirements for the 19170-1 standard are described as part of the main UML model, as Notes (Documentation) to diagrams.
The model documentation and the data dictionary for OGC CityGML 3.0 was generated in a one-step process from the CityGML UML model and represented in HTML: OGC City Geography Markup Language (CityGML) Part 1: Conceptual Model Standard. The model documentation and the data dictionary is described in separate main clauses (6 and 7) .
Requirements are maintained in shell scripts outside of the model, with identical requirements being repeated for several sub clauses.
The data dictionary (Annex F) for ISO 19123-1 was derived from the ISO/TC 211 HM and manually merged into the standard document. Unlike ISO 19170-1 and CityGML 3.0, this was a one-time process, not an automated update of a complete document.
Some issues that have been identified from the MDD pilots:
- Completeness of the UML model is essential, and most important: definitions at all levels in the model.
- A model must be structured as a story with diagrams in correct order to ensure the correct order in the document.
- The different structural approaches in ISO 19170-1 and OGC CityGML (integrated dictionary or separate clauses) can be configured.
- Tools for documentation need to be able to update the content of documents from changes in the UML model (like for ISO 19170-1 and CityGML), instead of producing a complete new document (like for ISO 19123-1).
- ISO/TC 211 standards and OGC standards have used many different structures and layouts for data dictionaries (for representing classes, attributes and associations). Such differences can be avoided with MDD and a standardized layout.
- Manually written content should be avoided for the model documentation clauses, in order to simplify the document derivation and maintenance.
The ISO online authoring tool will be tested in the ISO 19103 revision project. To be able to combine the online tool with MDD, one will need functionality for importing documents into the authoring tool. Metanorma supports the XML format that is used, but we do not yet know whether the online tool will allow for import.
We also see that in some cases, documenting requirements in the notes field in a UML model is not sufficient, for example for formulas. A possible approach is to provide links to an extended description.
-
We recommend to use MDD for ISO/TC 211 standards as the main way of documenting UML models. NOTE: This will require an early involvement of modelling expertice in standardization projects, to help the project getting started with UML in the best way and ensure the quality of the UML model.
-
We recommend to set up a NWIP for standardizing the conceptual model for a modular specification. This should be done in collaboration with OGC.
-
The layout for model documentation and data dictionary should be standardized.
-
JAG should pick up this discussion. At the end of the process, the outcome should be a MDD processing based on a common underlying UML structure for ISO/TC 211 and OGC.
-
Experiences from the pilots concerning how to structure the model for best possible automated documentation should be taken into consideration as best practices and documented on the UML Best Practices Wiki.
-
The existing documentation on MDD in the UML Best Practices Wiki: Documentation of UML models and Automatic generation of documentation from UML models should be updated from findings in the pilots. The documentation should be a pure GitHub Wiki, not a linked Word document.