Foreword

The EXPRESS Language Foundation (“ELF”) is a registered public charity in the US that facilitates the education, standardization, research, promotion, definition, and usage of information modelling and programming languages, with a focus on the EXPRESS language family.

ELF works with international partners and experts across the globe, reflecting the international nature of its mission. More information about ELF is available on the official website (https://www.expresslang.org).

The procedures used to develop this document and those intended for its further maintenance are described in the ELF Directives.

In particular, the different approval criteria needed for the different types of ELF documents should be noted. This document was drafted in accordance with the editorial rules of the ELF Directives.

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. ELF shall not be held responsible for identifying any or all such patent rights. Details of any patent rights identified during the development of the document will be provided in the Introduction.

Any trade name used in this document is information given for the convenience of users and does not constitute an endorsement.

This document was prepared by Technical Committee EXPRESS.

Introduction

The Metanorma ELF format provides a standardized approach for creating EXPRESS language documentation using the Metanorma toolchain. This document describes the process of converting existing EXPRESS documentation into the Annotated EXPRESS format, which is the model-based method preferred for modern EXPRESS documentation.

This guide is intended for document maintainers and developers who need to migrate existing EXPRESS documentation to the standardized Annotated EXPRESS format. The approach described here can be applied to PDF parts after converting them into Metanorma.

Conversion of EXPRESS documentation into Annotated EXPRESS

1 Scope

This document specifies the methods and procedures for converting traditional EXPRESS documentation into the Annotated EXPRESS format.

The document:

defines the structure conversion process from Metanorma documents containing EXPRESS to Metanorma documents with Annotated EXPRESS;
specifies content conversion rules for various EXPRESS components including schemas, entities, types, and rules;
provides guidelines for converting attributes, formal propositions, and informal propositions;
outlines approaches for handling notes, examples, figures, and tables in the conversion process; and
includes practical examples illustrating the conversion process.

2 Normative references

The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

ISO 10303-11, Industrial automation systems and integration — Product data representation and exchange — Part 11: Description methods: The EXPRESS language reference manual

Metanorma, Metanorma framework for standards documents — https://www.metanorma.org

Annotated EXPRESS, EXPRESS Language Foundation: Annotated EXPRESS Specification

3 Terms and definitions

For the purposes of this document, the following terms and definitions apply.

ISO and IEC maintain terminology databases for use in standardization at the following addresses:

ISO Online browsing platform: available at https://www.iso.org/obp
IEC Electropedia: available at https://www.electropedia.org

For the purposes of this document, the following terms and definitions apply.

3.1

EXPRESS

data modeling language defined in ISO 10303-11 that provides a formal way to specify data structures and constraints

[SOURCE: ISO 10303-11]

3.2

Annotated EXPRESS

set of rules that build on top of the EXPRESS remark tag syntax for documentation and description of EXPRESS code

[SOURCE: Annotated EXPRESS]

3.3

remark tag

syntax in EXPRESS using (* … *) notation to indicate documentation content

[SOURCE: ISO 10303-11]

3.4

named remark tag

remark tag that includes a specific name to reference an EXPRESS object

3.5

traditional EXPRESS documentation

documentation approach where text content is placed outside EXPRESS schema content in standard document format, with EXPRESS code embedded within the document

3.6

model-based documentation

documentation approach where documentation content is embedded within the model (EXPRESS schema) using structured remark tags

4 Structure conversion

4.1 General

In the current ISO documents, the role of Metanorma is reversed with EXPRESS.

Text is handled in the blocks like this:

{document content}
*)

{EXPRESS schema content}

(*
{document content continued}

Figure 1

Notice that this is in the syntax of an EXPRESS comment. The intention here is to reverse the structure, where the {document content} exists as Annotated EXPRESS objects within the EXPRESS schema.

Let’s reverse this so that we have:

{EXPRESS schema content}

(*
{document content}
*)

{EXPRESS schema content continued}

Figure 2

Now, anything outside the remarks is in plain EXPRESS.

4.2 Example

We take ISO 10303-49, Clause 4 as an example.

This file sections/04-method_definition.adoc contains this content (partial copy):

[[method_definition]]
== Method definition

The following EXPRESS declaration begins the *method_definition_schema* and
identifies the necessary external references.

EXPRESS specification:

[%unnumbered]
[source,html]

Figure 3

*) SCHEMA method_definition_schema;

REFERENCE FROM action_schema (action_method, action_method_relationship, action_relationship);

… (*

[NOTE]
====
The schemas referenced above can be found in the following parts of ISO 10303:

action_schema:: <<iso10303-41>>
document_schema:: <<iso10303-41>>
...
====

NOTE: See <<annexD>>, <<figD1>>, for a graphical presentation of this schema.

=== Introduction

The subject of the ...

=== Fundamental concepts and assumptions

The *method_definition_schema* provides ...

Figure 4

Given this input, we want to reverse the roles to obtain a new file:method_definition_schema.exp.

The resulting file looks like this (method_definition_schema.exp):

SCHEMA method_definition_schema;

REFERENCE FROM action_schema
    (action_method,
     action_method_relationship,
     action_relationship);

...

(*"method_definition_schema.__note
The schemas referenced above can be found in the following parts of ISO 10303:

action_schema:: <<iso10303-41>>
document_schema:: <<iso10303-41>>
...
*)

(*"method_definition_schema.__note
See <<annexD>>, <<figD1>>, for a graphical presentation of this schema.
*)

(*"method_definition_schema"
The subject of ...
*)

(*"method_definition_schema.__fund_cons"
The *method_definition_schema* provides...
*)

Figure 5

5 Content conversion

5.1 Schema information conversion

5.1.1 General

In a schema if there are lines like this:

ENTITY action_method_with_associated_documents
  SUBTYPE OF (action_method);
  documents : SET [l:?] of document;
END_ENTITY;

Figure 6

It means that action_method_with_associated_documents is defined in the current schema.

Given a text like this, we need to convert them:

An *action_method* defines a potential means of satisfying an *action*.
An *action_method_to_select_from*, an **action_method_with_associated_document**s,
and an *action_method_associated_documents_constrained*,
specify different types of **action_method**s
that may be used to satisfy an action.

Figure 7

To reflect the actual EXPRESS entity with schema information:

An *action_method* defines a potential means of satisfying an *action*.
An <<express:method_definition_schema.action_method_to_select_from,action_method_to_select_from>>,
an <<express:method_definition_schema.action_method_with_associated_document,action_method_with_associated_documents>>,
and an
<<express:method_definition_schema.action_method_associated_documents_constrained,action_method_associated_documents_constrained>>,
specify different types of **action_method**s that may be used to satisfy an action.

Figure 8

5.1.2 References to external schema

In a schema if there are lines like this:

REFERENCE FROM action_schema
    (action_method,
     action_method_relationship,
     action_relationship);

Figure 9

This means that the entities called action_method,action_method_relationship and action_relationship come from the schemaaction_schema.

Given a text like this, we need to convert them:

An *action_method* defines a potential means of satisfying an *action*.
An *action_method_to_select_from*, an **action_method_with_associated_document**s,
and an *action_method_associated_documents_constrained*,
specify different types of **action_method**s
that may be used to satisfy an action.

Figure 10

To reflect the actual EXPRESS entity with fully resolved schema information:

An <<express:action_schema.action_method,action_method>>
defines a potential means of satisfying an
<<express:action_schema.action,action>>.
An *action_method_to_select_from*, an **action_method_with_associated_document**s,
and an *action_method_associated_documents_constrained*, specify different types of
<<express:action_schema.action_method,action_methods>> that may be used to satisfy an action.

Figure 11

5.1.3 Fully expressed references

Combining the above two approaches, from this text:

An *action_method* defines a potential means of satisfying an *action*.
An *action_method_to_select_from*, an **action_method_with_associated_document**s,
and an *action_method_associated_documents_constrained*,
specify different types of **action_method**s
that may be used to satisfy an action.

Figure 12

We get:

An <<express:action_schema.action_method,action_method>>
defines a potential means of satisfying an
<<express:action_schema.action,action>>.
An <<express:method_definition_schema.action_method_to_select_from,action_method_to_select_from>>,
an <<express:method_definition_schema.action_method_with_associated_document,action_method_with_associated_documents>>,
and an
<<express:method_definition_schema.action_method_associated_documents_constrained,action_method_associated_documents_constrained>>,
specify different types of <<express:action_schema.action_method,action_methods>>
that may be used to satisfy an action.

Figure 13

5.2 Example

The converted method_definition_schema.exp would look like this:

SCHEMA method_definition_schema;

REFERENCE FROM action_schema
    (action_method,
     action_method_relationship,
     action_relationship);

...

(*"method_definition_schema.__note
The schemas referenced above can be found in the following parts of ISO 10303:

action_schema:: <<iso10303-41>>
document_schema:: <<iso10303-41>>
...
*)

(*"method_definition_schema.__note
See <<annexD>>, <<figD1>>, for a graphical presentation of this schema.
*)

(*"method_definition_schema"
The subject of ...
*)

(*"method_definition_schema.__fund_cons"
The *method_definition_schema* provides...
*)

(*"method_definition_schema.relationship_with_condition"
A *relationship_with_condition* type ...
*)

TYPE relationship_with_condition = SELECT
  (action_method_relationship,
   action_relationship,
   context_dependent_action_method_relationship,
   context_dependent_action_relationship);
END_TYPE;

(*"method_definition_schema.process_or_process_relationship"
A *process_or_process_relationship* type ...
*)

TYPE process_or_process_relationship = SELECT
  (product_definition_process,
   property_process,
   relationship_with_condition);
END_TYPE;

(*"method_definition_schema.action_method_with_associated_documents"
An **action_method_with_associated_document**s is a type ...
*)

(*"method_definition_schema.action_method_with_associated_documents.__example"
A process specification document that ...
*)

ENTITY action_method_with_associated_documents
  SUBTYPE OF (action_method);
  documents : SET [l:?] of document;
END_ENTITY;

...

END_SCHEMA; -- method_definition_schema

Figure 14

6 Specific conversion cases

6.1 Attribute conversion

Given this text:

ENTITY action_method_with_associated_documents
  SUBTYPE OF (action_method);
  documents : SET [l:?] of document;
END_ENTITY;

Figure 15

…

Attribute definitions:

documents: the set of one or more documents that identifies the action_method.

It should be converted into:

ENTITY action_method_with_associated_documents
  SUBTYPE OF (action_method);
  documents : SET [l:?] of document;
END_ENTITY;

(*"method_definition_schema.action_method_with_associated_documents.documents"
the set of one or more documents that identifies the *action_method*.
*)

Figure 16

6.2 Formal propositions conversion

Given this text:

Formal propositions:

*WR1*:: The *number_of_elements* shall be greater than or equal to one.
*WR2*:: The value of the *number_of_elements* shall ...

Figure 17

It should be converted into:

(*"method_definition_schema.action_method_to_select_from.WR1"
The *number_of_elements* shall be greater than or equal to one.
*)

(*"method_definition_schema.action_method_to_select_from.WR2"
The value of the *number_of_elements* shall ...
*)

Figure 18

6.3 Informal propositions conversion

Given this text:

ENTITY serial_action_method
  SUBTYPE OF (action_method_relationship);
END_ENTITY;

Figure 19

…

Informal propositions:

IP1: Individual action_methods in a collection…

It should be converted into:

(*"method_definition_schema.serial_action_method.IP1"
Individual **action_method**s in a collection...
*)

Figure 20

6.4 Notes, examples, figures and tables

These objects are to be converted into native Annotated EXPRESS remarks.

For example, this content:

==== sequential_method

A *sequential_method* is ...

NOTE: See <<annexE>> for an extended example using indexes for *sequential_method*.

EXPRESS specification:

[%unnumbered]
[source]

Figure 21

) ENTITY sequential_method SUBTYPE OF (serial_action_method); sequence_position : count_measure; END_ENTITY; (

Attribute definitions:

*sequence_position*:: the position of ...

Informal propositions:

*IP1*:: There shall be ...

NOTE: This proposition...

NOTE: If the *sequential_method* ...

NOTE: The context ...

Figure 22

Needs to become:

ENTITY sequential_method
  SUBTYPE OF (serial_action_method);
  sequence_position : count_measure;
END_ENTITY;

(*"method_definition_schema.sequential_method"
A *sequential_method* is ...
*)

(*"method_definition_schema.sequential_method.__note"
See <<annexE>> for an extended example using indexes for *sequential_method*.
*)

(*"method_definition_schema.sequential_method.__note"
This proposition ...
*)

(*"method_definition_schema.sequential_method.__note"
If the *sequential_method* ...
*)

(*"method_definition_schema.sequential_method.__note"
The context ...
*)

(*"method_definition_schema.sequential_method.sequence_position"
the position of ...
*)

(*"method_definition_schema.sequential_method.IP1"
There shall be ...
*)

Figure 23

NOTE Place the annotations after the EXPRESS declarations.

Bibliography

[1] ISO 10303 (all parts), Industrial automation systems and integration – Product data representation and exchange

[2] ISO 10303-41, Industrial automation systems and integration — Product data representation and exchange — Part 41: Integrated generic resource: Fundamentals of product description and support

[3] ISO 10303-49, Industrial automation systems and integration — Product data representation and exchange — Part 49: Integrated generic resources: Process structure and properties

[4] Metanorma, Metanorma. https://www.metanorma.org/

[5] STEPmod, STEP Modules Library