1. Resolutions
  2. ISO/TC 211 Good practices
  3. - Content of the document

Content of the standard document

This section contains a collection of good practices for ISO/TC 211 standard documents. These are additions to, or in a few cases exemptions from, the ISO directives part 2. You can find more about the ISO rules for writing standards in: ISO - HOW TO WRITE STANDARDS - TIPS FOR STANDARDS WRITERS and in the model document (“Rice Model”). There’s much more information on the page Drafting Standards.

General

The project leader is responsible for checking that:

  • the scope statement is clear and within the ISO/TC 211 scope
  • scope and content correspond
  • all conformance classes, conformance tests, requirements, and recommendations are identified using a URI (Resolution 858). See how to specify the URIs.
  • informative parts do not have provisions (shall, should)
  • informative annexes contain supporting information for the standard
  • check the ISO/TC 211 Standards tracker and consider all issues raised against prior editions of the standard.
  • if the project was initiated by a systematic review, address the comments from the systematic review

According to ISO Directives all the decimal separator in any numbers is to be the decimal comma (,) but for ISO/TC 211 we have the possibility to us the decimal point (.) instead. You can read more about this in the Resolution 958 and in the N document 5171.

Figures

UML diagrams should be in EMF format; list of accepted formats for other figures that contain text.

  • AutoCAD (.dwg or .dxf)
  • Illustrator (.ai)
  • Vector file type (.eps .svg .wmf or .emf)
  • Word (.doc .docx), Excel (.xls .xlsx), Powerpoint (.ppt .pptx), Visio (.vsd .vsdx)
  • CorelDraw (.cdr)
  • Photoshop (.psd)

For other images, where there is no text, ISO accepts other formats, such as .png, .tif, .jpeg.

UML models

UML Models can be found in Enterprise Architect cloud version and more information can be read in the ISO/TC 211 HMMG Wiki.

All project team that will work on UML models should include the necessary expertise. Do not expect HMMG to do your modelling for you; they there to guide and assure consistency (harmonization). See Resolution 777.

All projects that include a UML model shall have a reference to UML and ISO 19103 in the symbols and abbreviation clause: "In this document, conceptual schemas are presented in the Unified Modeling Language (UML). ISO 19103 Conceptual schema language presents the specific profile of UML used in this document." Resolution 806.

If your document will contain UML models, either normative or informative – including illustrative diagrams – you should use Enterprise Architect and work as described in the TC211 UML Best Practices on the HMMG wiki. If you are going to use Enterprise Architect, ISO/TC 211 have a collaboration with Sparx Systems to get a free license when working with ISO/TC 211 models. You need to contact ISO/TC 211 secretariat for help obtaining a free license.

During the project the Project Leader and Project Editor is automatically a member of the ISO/TC 211/AG 5 Harmonized Model Maintenance Group (HMMG) Resolution 777. 

If your document contains UML models the Resolution 684 says that you will need an annex with the information about where a conceptual Model can be found. Read more on how to specify the URI.

According to Resolution 2023-11 the UML models need to be sent for review to the HMMG Convenor before the CD Consultation or DTS Ballot and the UML models would need to be controlled and tested by the HMMG Convenor before the DIS Ballot. an additional check of the UML Model is done after the DIS ballot before the document moves forward to either the FDIS or publication.

If the project is a revision you may also need to consult if there are any model inconsistencies, this can be found in the complete project list for each standard. If you navigate to the project and look for Model References all shown in red are indications that the models need updating. If you have any question about what needs changing you should consult with the HMMG Convenor.

XML

If your document contains an XML schema,  Resolution 684 says that you will need an annex with the information about where the XML schema can be found. That annex may also contain a description of how the resources were derived. Read more on how to specify the namespace URI.

If your UML follows the approach described above, the XML schema can and should be derived from the UML model using the rules in ISO 19136 Annex E or ISO 19139-1 as appropriate. 

OWL 

If your document contains an OWL ontology, Resolution 684 says that you will need an annex with the information about where the OWL ontology can be found. Read more on how to specify the URI.

If your UML follows the approach described above, the ontology can and should be derived from the UML model using the rules in ISO 19150-2.

Dependencies and References

The project leader is responsible for checking that:

  • all ISO/TC 211 normative references are dated
  • the required normative references for dependencies are listed
  • all none ISO/TC 211 normative reverences are not dated
  • that no circular references are created

Conformance

The project leader is responsible for checking that:

  • conformance classes exist and correspond to the scope
  • content corresponds to conformance clause
  • conformance classes match the abstract test suites

For further information, see Modular standard

Backward compatibility

According to Resolution 744 it is strongly recommended to include an annex to describe how backward compatibility is addressed. More can also be read in the N document 3165 Report and recommendations from the ad-hoc group on strategy for configuration management and backwards compatibility.

When revising a document, include sufficient documentation of the changes for users to easily understand what has been changed (N 3165). The ISO editors recommend that the Foreword includes a summary of the changes.

Formatting requirement statements

In an ISO document, the presence of the verb shall means that a statement is normative – a requirement. However, ISO/TC 211 is keen that the requirements and recommendations in our standard stand out from the rest of the text. This is related to our decision to provide each requirement and recommendation with an identifier. The form and structure of these identifiers is described at Structure of URIs in ISO/TC 211 resources for implementation.  

This is stated as a requirement in ISO 19105:2000 Requirement 16
https://standards.isotc211.org/iso19105/-/2/req/standard/Identification

  • State the identifier root for the document near the start of the document’s normative text, which will generally be clause 5 or 6.
              -  Note: it would be good if these document identifiers could actually be
                 dereferenced (i.e. perform as URLs as well as URIs).
                 We will need to agree with ISO how much information we can openly return.
                 Perhaps a redirect or link to the documents page in the ISO shop?
  • Start each requirement on a new line, with the word “Requirement” in bold OR place each requirement or set of related requirements in a table. This depends on how complex the document and its conformance/requirements classes are.
  • Identify each requirement with a URI fragment. (This satisfies the requirement for a URI whilst reducing the number of identifiers that get converted into URLs / links)
  • In addition, identify each requirement with a serial number or name. This assists in verbal communication, using such as “requirement 21” or “recommendation 1”.
  • Each identified requirement should only contain one occurrence of “shall”
  • There is no need to highlight the word “shall”, so do not put it in capitals
  • There should be no occurrences of “shall” outside of these identified requirements

Example 1
Following this good practice should result in a simple requirement appearing like this:

The URI root is given in clause 6.2 of this standard: https://standards.isotc211.org/iso19105/-/2

Note 1: This ‘style’ should be the target of the model driven documentation approach (AHG 5).

Note 2: This good practice applies to documents being prepared by ISO projects using Word or similar software. Projects working as pilots of the new ISO online collaboration tool need to follow the instructions of that project.

Contributors

Chair
Committee Manager
PMG Convenor
Changes  
2024-03-28 Changed to the 2023-11 resolution in the UML section.
2023-09-20 Updated recomendation from ISO EPM to include a summary of changes in the foreword.
2022-07-20 Changed CD ballot to CD consultation

2022-03-02

Updated link to ISO How to write standards

2022-02-09

Changed the figures section with new information about UML that now must be in format EMF but also more formats accepted by ISO. 

2021-12-01

Added section Formatting requirement statements