parson AGiiRDS for the documentation of technical standards
Corresponding service: Smart content and iiRDS
The iiRDS standard makes documentation smart – so it can be made available on portals, apps and data glasses. Case studies in the field of mechanical engineering are very often mentioned in connection with iiRDS – for example, the scenario of the service technician who uses an end-device to scan an error code on a machine that needs repairing and then receives a snippet of information on the display showing how to fix the problem [1].
Less has been said about how the iiRDS model can be extended to other areas and applications. In my Master’s thesis, I examined the question of whether and what useful implementation options exist for technical standards and developer documentation. For this purpose, I prototypically applied iiRDS for the electronic delivery of ASAM e.V. documentation and extended it based on the iiRDS specification [2]. ASAM develops technical standards for the automotive sector [3].
ASAM e.V. – Documentation of technical standards
I wrote the Master’s thesis in cooperation with ASAM e.V. ASAM’s standardization work covers a number of areas including software development for electronic vehicle components, the measurement and calibration of these components, and the simulation of road networks and driving functions.
In the Master’s thesis, I utilized the documentation for the following ASAM standards:
- OpenDRIVE, a standard that describes static aspects of a road.
- OpenCRG, a standard that defines a file format for the surface of a road.
The documentation for these standards is already topic-based, so there was high degree of standardization and structuring – important for providing the documentation in a meaningful way in an iiRDS package. Ultimately, the documentation is to be made available on a content delivery portal based on iiRDS.
Standardization documents are not yet covered in a custom domain in the iiRDS model, unlike the existing domains iiRDSMachineryDomain and iiRDSSoftwareDomain. There are also no classes and instances that deal exclusively with standardization documentation.
Another interesting feature of the project was the fact that ASAM describes the technical concepts of traffic infrastructure and simulation in the form of an ontology in another project [4]. This meant there was an opportunity to combine iiRDS with a product ontology. More about that later.
Defining the requirements – User stories
In the first step of the creation process, we discussed ASAM’s requirements and defined them in writing. I therefore wrote user stories based on an interview with ASAM project managers. I present some of them below as examples so you can understand the resulting iiRDS extensions and search and filter mechanisms in the portal.
User story, example 1: Cross-standard search for functions (features)
As a software developer, I want to be able to search different standards for certain features such as roads or lanes because I need to export the data from my tool into different ASAM standards. And for each feature I need to know how this is implemented in the respective standard.
User story, example 2: Overview of mandatory requirements
As a product manager, I would like to have an overview of all the mandatory requirements from the standard so that I can use this overview to check (or as an input for) the implementations.
This indicates that it should be possible to filter the documentation, based on the mandatory requirements, i.e. the rules, of a standard.
User story, example 3: Release or concept
As a software developer, I want to be able to see whether a piece of information or guidance I have found in the documentation belongs to a published ASAM standard or originates from a concept project so that I can assess whether I can safely use the data structure or otherwise even contribute to the ongoing project.
Deriving metadata from the user stories
The user stories helped me to determine ASAM’s requirements. But I also used them to define metadata. The metadata must cover the information needs described in the individual user stories.
There are three possible sources for the metadata:
- Existing classes and instances from the iiRDS model
- OpenXOntology from ASAM
- Individual extension of iiRDS
I was able to take most of the metadata from the existing iiRDS model. This shows that iiRDS contains a comprehensive vocabulary for technical documentation. I only needed to make some small extensions to iiRDS for my project.
One of these is filtering by rules: Users of the ASAM standards want to see rules that must be observed for standard-compliant modelling of roads. In sub-sections of the documentation, this is indicated by the “Rules” item. If you assign a metadatum to these items, it can be used as a search facet in the portal. I therefore added the Rules instance below the InformationSubject class.
Another example is the distinction between published standards and concept projects. For this purpose, I added a ProductStatus class with the ReleasedStandard and ConceptProject instances.
Besides these classes and instances to be created, another key point was linking ASAM’s custom product ontology (OpenXOntology) to the iiRDS-compliant documentation. The goal of ASAM OpenXOntology is to collect, consolidate, and harmonize the traffic concepts and definitions from different ASAM standards. The ontology contains definitions of concepts such as roads and lanes, for example. They relate to the product itself, i.e. the ASAM standard, and not the information in a specific piece of documentation. This is product descriptive metadata that can mostly be added to the ProductFunctions class (subclass of ProductFeature) in iiRDS.
Mapping the metadata as a semantic network
As a semantic network needs to be created with the help of iiRDS metadata, the metadata must also be linked to each other. Relations (properties) are used for this. By linking two instances of iiRDS classes, a “triple” is created, consisting of subject - predicate - object. InformationUnit is the main class of the iiRDS model and mostly represents the subject of the triple.
Below you can find examples of iiRDS triples that I used for the user stories above:
- InformationUnit – relates to product variant – ProductVariant (OpenDRIVE | OpenCRG, ...)
- InformationUnit – is applicable for document type – DocumentType (ConceptPaper | UserGuide)
- InformationUnit – relates to product status – ProductStatus (ConceptProject | ReleasedStandard)
- InformationUnit – has subject – InformationSubject (Rules)
- InformationUnit – relates to product feature – ProductFunction (Roads | Lanes | Junctions | ...)
Creating custom iiRDS-compliant classes and instances
After I had defined all metadata and triples, I was able to start modeling custom iiRDS-compliant classes and instances. So I could keep an overview, I created an overview table with all extensions:
It is important to assign an IRI with its custom namespace to the classes and instances that you have created yourself. Otherwise, you would indicate the custom extensions are part of the standard iiRDS vocabulary. Systems that process iiRDS do not recognize the extensions if an IRI from the iiRDS namespace is assigned. Care should be taken to choose names that are highly likely to remain unique in the future. It therefore makes sense to provide information about the project and the creator of the classes and instances in the IRI.
In the table, I have defined a custom namespace for the classes and instances.
ASAM’s product ontology is referred to using its ASAM-specific IRI (http://asam.net/ontologies/OpenXOntology#).
The classes and instances from the table can then be integrated into the existing iiRDS model using any text editor. The next figure shows an example of the creation of a custom class UseCase as a subclass of the existing TopicType class:
Adding your custom instances to existing iiRDS classes looks like this:
By looking at the start and end tags, it is clear the Rules instance was added to an existing class from the iiRDS model. In this case it is iirds:Conformity. In the rdf:about that follows, you specify the IRI of the instance to be added. The creation of a custom instance that is added to a custom class is provided for comparison here:
Ontology editors are very useful for checking and visualizing custom extensions to the iiRDS model. One of them, Protégé, is an open source solution for this.
The next figure shows that the custom instance Rules (under Direct Instances) has been correctly added to the Conformity class:
iiRDS generator - plusmeta
To enrich the documentation content with iiRDS metadata, an iiRDS generator is needed. The iiRDS OpenToolkit, which is available free of charge on the internet, is generally suitable for this purpose. [5] But it has a limited range of functions. For example, custom instances can be added within existing classes, but custom classes cannot. For this reason, I worked with the software plusmeta for this project. plusmeta has many functions that extend far beyond creating an iiRDS package. [6] One practical feature is that some iiRDS-specific metadata is automatically recognized in the processed content. This means there is no need to go through the tedious process of assigning all metadata manually. Of course, automatic recognition does not initially work for custom classes and instances. But with plusmeta it is possible to train an AI model to automatically recognize custom metadata. In addition, plusmeta supports other metadata models, such as VDI2770.
Implementing the content delivery in a web portal
I then integrated the finished iiRDS package into a content delivery portal. These portals have a wide range of semantic query and search options. For this project I used iv-content from the company empolis intelligent views GmbH. The portal’s homepage looks like this:
In the middle column, you can select the documentation of a specific ASAM standard. Various metadata from the iiRDS model are shown on the right. If you click on one of these metadata, the portal displays all topics that have this metadatum:
Click on “Table of Contents – ASAM OpenDRIVE v1.6 User Guide” in the middle column “Documents” to open the following view:
The user documentation for the OpenDRIVE standard is displayed here in a directory with a hierarchical chapter structure. Even though iiRDS is mainly intended for the context and user-oriented delivery of individual topics (instead of long documents), the model offers clear navigation in a document context through the use of “directory nodes”.
If you select one of the topics, some metadata is displayed in “context boxes” on the right-hand side. For example, the product variant or the standard of the displayed topic is named here, along with the subjects that the contents deal with (in this case: architecture and source code structure) and a list of related topics.
In addition, a search field on the homepage provides a full-text search. If you enter a search term (in the following example “Roads”), the portal will display a list of all topics containing this search term:
To support the full-text search, the portal can narrow the search results with the help of facets. These can be seen in Figure 10 on the left. The solution contains the following facet groups:
- Standard
- Feature
- Standard status
- Document type
- Type of information
- Type of topic
Each group contains facets to narrow down the list of topics displayed in the search result.
The following screenshots show how you can find information on the portal based on the user stories explained above.
User Story, Example 1: Cross-standard search for functions (features)
An important use case for the relevant target groups is the cross-standard search for product functions. For this, iiRDS offers the class ProductFeature. In the OpenX standards, such features can be objects such as roads, lanes or intersections. The individual standards specify their modeling. To find these product features, the portal offers a faceted search, which begins with a full-text search around a keyword or by entering several keywords on the landing page. The following picture shows the keyword search on the portal's landing page:
The portal then shows all topics containing the keyword. In this view, the facets are displayed on the left. You can filter in the search results by product function, for example, streets:
The search results can be narrowed down by selecting further filters. In this context, it may be useful to search for product functions in a specific standard:
There are also filters for document and information type so that you can further narrow down the results by subject.
User Story, Example 2: Overview of mandatory requirements
It is charactistic for standards that they specify the degree of obligation with modal verbs such as shall, should, may, or can. The documentation of a standard usually explains these obligations, or mandatory requirements, in a separate section. This applies to the OpenXStandards as well. By assigning metadata, the corresponding sections can be easily found in a portal. This way, you get an overview of all mandatory requirements in a standard or even in several standards.
As for the product functions, you can find the mandatory requirements in the portal via full-text search, followed by a faceted search.
Here too, you can further narrow down the search results, for example, by selecting a specific standard:
Instead of using the full text and faceted search, you can search thematically in "Topics" on the portal's start page . In this thematic search, there is a sub-item "Rules", as shown in the following figure:
Subsequently, the portal shows all the topics that contain mandatory requirements across all standards:
User Story, Example 3: Release or concept
Developing technical standards usually takes several months or years – also at ASAM. Before a first or new version of a standard is published, the new features are specified and evaluated in a so-called concept project. The concept documents are also published. For users to recognize whether the description of a feature belongs to a concept project or to a published version, we have included this metadata in the document publication:
Ongoing projects in the area of digitalization of norms and standards
DiTraNo – The digital transformation of standardization [7]
Thematically very well suited to the topic of the Master’s thesis was a project of the “German Commission for Electrical, Electronic & Information Technologies in DIN and VDE”, or “DKE” for short, during the same period. The aim of the project is to enable the machine processing of DKE standards. An important criterion for DiTraNo is labelling content according to its binding nature (“must”, “should”, “may”, “can”).
The DiTraNo project also uses iiRDS to mark up the content of the standards with metadata. The project has now been successfully completed and the results will be made available in a final report in fall 2021.
The findings of DiTraNo are being refined in the IDiS project, the Digital Standards Initiative. One goal of IDiS is the practical implementation of digital standards for specific products of an industrial company. As an iiRDS consortium member, parson is actively involved in the IDiS project.
DIN – Smart Standards
The German Institute for Standardization (DIN e.V.) is also striving to digitalize standards. The title of the project is Smart Standards. Here, too, the aim is to have standards in machine-readable form to enable automated processing. It is planned to have this in place by 2030. The project is therefore in its initial stages. In the first step, the creation process was changed from Word to XML to allow the standards documents to be better structured in terms of content. The next step for DIN is to classify the contents according to their binding nature and to have them available in a form that can be analyzed by machine. The content will therefore need to be semantically enriched. The next step is to map the information from the standards into ontologies so that a higher degree of automation is ensured and the standards content can be used directly in software systems. It is not yet possible to determine whether and to what extent iiRDS will be used in this process.
Conclusion
The work with ASAM e.V. and the ongoing projects on digitalization in the field of standards show that iiRDS can be applied in a variety of ways in the field of documentation. iiRDS permits optimal expansion to adjacent areas of work that have tended to fall below the radar up to now.
Footnotes
[3] Details on the ASAM e.V. ontology project can be found online at: https://www.asam.net/project-detail/asam-openxontology/ (last accessed on: 24 March 2021)
[6] The following link provides some basic information on this project: german-standardization-strategy-data.pdf (dke.de) (last accessed on: 13 September 2022)
[7] https://www.dke.de/de/news/projektabschluss-ditrano (last accessed on: 18 May 2021)
[8] https://din.one/ (last accesses on 23 September 2022)
Add new comment