feat: add mapping spec document 5006

expresslang/docs/sources/express-mapping/sections/01-scope.adoc

@@ -0,0 +1,16 @@
+== Scope
+
+This document specifies the mapping language used to express reference paths in
+ISO 10303 application module mapping specifications.
+
+The language describes navigation through EXPRESS schema entity relationships,
+including:
+
+* Subtype and supertype relationships;
+* Forward and inverse attribute navigation;
+* Constrained paths with entity and attribute conditions;
+* Alternative path expressions.
+
+This specification applies to mapping files used in ISO 10303 modular
+architecture, where Application Resource Model (ARM) entities are mapped to
+Module Interpreted Model (MIM) entities through reference paths.

metanorma.yml

@@ -7,6 +7,7 @@ metanorma:
       - sources/expressdocs-migration/document.adoc
       - sources/express-schema-manifest/document.adoc
       - sources/express-changes/document.adoc
+      - sources/express-mapping/document.adoc
 
   collection:
     organization: "EXPRESS Language Foundation"

sources/express-mapping/document.adoc

@@ -0,0 +1,47 @@
+= EXPRESS mapping language specification
+:docnumber: 5006
+:edition: 1
+:copyright-year: 2025
+:revdate: 2025-10-19
+:language: en
+:title-main-en: EXPRESS mapping language specification
+:doctype: standard
+:technical-committee: EXPRESS
+:imagesdir: images
+:mn-document-class: elf
+:mn-output-extensions: xml,html,doc,pdf,rxl
+:fullname: Ronald Tse
+:surname: Tse
+:givenname: Ronald
+:affiliation: EXPRESS Language Foundation
+:fullname_2: Thomas Thurman
+:surname_2: Thurman
+:givenname_2: Thomas
+:affiliation_2: EXPRESS Language Foundation
+:docidentifier: ELF 5006:2025
+:data-uri-image:
+:local-cache-only:
+
+include::sections/00-foreword.adoc[]
+
+include::sections/00-introduction.adoc[]
+
+include::sections/01-scope.adoc[]
+
+include::sections/02-normrefs.adoc[]
+
+include::sections/03-terms.adoc[]
+
+include::sections/04-overview.adoc[]
+
+include::sections/05-operators.adoc[]
+
+include::sections/06-navigation.adoc[]
+
+include::sections/07-constraints.adoc[]
+
+include::sections/08-validation.adoc[]
+
+include::sections/aa-examples.adoc[]
+
+include::sections/az-bibliography.adoc[]

sources/express-mapping/sections/00-foreword.adoc

@@ -0,0 +1,27 @@
+.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 _{technical-committee}_.

sources/express-mapping/sections/00-introduction.adoc

@@ -0,0 +1,39 @@
+== Introduction
+
+=== General
+
+The EXPRESS mapping language is a domain-specific language designed to express
+reference paths between entities in a set of EXPRESS schemas.
+
+It provides a formal syntax and semantics for specifying how entities in one schema
+relate to entities in another schema through a series of navigations. These paths
+can include subtype and supertype relationships, forward and inverse attribute
+navigations, and constraints on entity attributes.
+
+The operators and syntax to express allow for these navigations to be defined
+precisely and unambiguously.
+
+The mapping language serves several purposes:
+
+Documentation:: Provides a clear, machine-readable specification of how concepts
+of a conceptual model described in EXPRESS maps to an implementation described
+in another EXPRESS schema.
+
+Validation:: Enables automated validation that mapping paths are correct and
+traverse valid relationships in the EXPRESS schema.
+
+Interoperability:: Ensures consistent interpretation of mappings across
+different tools and implementations.
+
+Maintenance:: Facilitates detection of broken mappings when schemas evolve.
+
+=== Historical context
+
+In ISO 10303 (STEP), requirements of the application modules are defined using
+Application Resource Models (ARMs) expressed in EXPRESS.
+
+The implementation of these requirements is defined using Module Interpreted
+Models (MIMs), also expressed in EXPRESS.
+
+The EXPRESS mapping language was developed to formally express the relationships
+between ARM entities and MIM entities.

sources/express-mapping/sections/01-scope.adoc

@@ -0,0 +1,5 @@
+== Scope
+
+This document describes the EXPRESS mapping language used to express reference
+paths amongst a set of EXPRESS schemas.
+

sources/express-mapping/sections/02-normrefs.adoc

@@ -0,0 +1,7 @@
+
+[bibliography]
+== Normative references
+
+* [[[ISO10303-1,ISO 10303-1:2024]]]
+
+* [[[ISO10303-11,ISO 10303-11:2004]]]

sources/express-mapping/sections/03-terms.adoc

@@ -0,0 +1,70 @@
+== Terms and definitions
+
+=== application resource model
+preferred:[ARM]
+
+conceptual model that represents application domain concepts in a neutral,
+implementation-independent manner
+
+[.source]
+<<ISO10303-2>>
+
+=== module interpreted model
+preferred:[MIM]
+
+implementation model that maps ARM concepts to EXPRESS constructs using entities
+and relationships from integrated resources
+
+[.source]
+<<ISO10303-2>>
+
+=== reference path
+
+sequence of navigation steps through EXPRESS schema entity relationships,
+expressing how an entity in one schema relates to an entity in another schema
+
+=== subtype relationship
+
+relationship where one entity inherits all attributes and constraints from
+another entity, expressed in EXPRESS with the SUBTYPE OF construct
+
+=== supertype relationship
+
+relationship where an entity serves as a base type for one or more subtypes,
+providing attributes and constraints inherited by those subtypes
+
+=== forward attribute navigation
+
+navigation that follows an attribute from an entity to the entity it references
+
+[example]
+Navigating from `product_definition` through attribute `formation` to
+`product_definition_formation`.
+
+=== inverse attribute navigation
+
+navigation that finds entities referencing the current entity through a specific
+attribute
+
+[example]
+Finding all `product_definition_relationship` entities that reference a
+`product_definition` through their `related_product_definition` attribute.
+
+=== constraint block
+
+expression that specifies conditions that entities or attributes must satisfy
+during path navigation
+
+[example]
+`{product_definition_relationship.name = 'definition usage'}` requires the
+`name` attribute to equal the specified string value.
+
+=== navigation step
+
+single element in a reference path representing one traversal operation
+(subtype, supertype, forward navigation, or inverse navigation)
+
+=== path expression
+
+complete reference path from one schema entity to another schema entity,
+composed of at least one navigation step

sources/express-mapping/sections/04-overview.adoc

@@ -0,0 +1,110 @@
+[[overview]]
+== Overview
+
+=== General
+
+The EXPRESS mapping language is a formal notation for specifying reference paths
+between entities in EXPRESS schemas.
+
+A reference path describes a sequence of navigation steps that traverse entity
+relationships in the schema, starting from one schema entity and ending at
+another schema entity.
+
+There are two types of reference paths used in EXPRESS mapping:
+
+* Entity reference paths: Define how an entity in one schema relates to an
+  entity in another schema through a series of navigations.
+
+* Attribute reference paths: Define how an attribute of an entity in one schema
+relates to an attribute of an entity in another schema through a series of
+navigations.
+
+
+=== Path structure
+
+A reference path consists of one or more navigation steps, where each step
+represents:
+
+* A subtype or supertype relationship between entities;
+* Forward navigation through an attribute to a referenced entity;
+* Inverse navigation from a referenced entity back through an attribute;
+* Optional constraints on entities or attributes.
+
+=== Basic example
+
+The following simple path shows navigation through subtype relationships:
+
+[source]
+----
+land <=
+stratum_feature_template_component <=
+laminate_component <=
+assembly_component <=
+component_definition <=
+product_definition
+----
+
+This path indicates that `land` is a subtype of
+`stratum_feature_template_component`, which is a subtype of
+`laminate_component`, and so on, ultimately reaching `product_definition`.
+
+=== Path with attribute navigation
+
+More complex paths include attribute navigation:
+
+[source]
+----
+product_definition <-
+product_definition_relationship.related_product_definition
+product_definition_relationship
+product_definition_relationship.relating_product_definition ->
+product_definition
+----
+
+This path:
+
+. Starts from `product_definition`
+. Navigates inversely through the `related_product_definition` attribute to find
+  `product_definition_relationship` entities
+. Then navigates forward through the `relating_product_definition` attribute
+  back to another `product_definition`
+
+=== Path with constraints
+
+Paths can include constraints to specify required conditions:
+
+[source]
+----
+product_definition_relationship
+{product_definition_relationship
+product_definition_relationship.name = 'definition usage'}
+----
+
+This constrains the path to only `product_definition_relationship` entities
+where the `name` attribute equals `'definition usage'`.
+
+=== Role in ISO 10303 modules
+
+In ISO 10303 application modules, mapping files specify how each ARM entity and
+attribute maps to MIM entities. These mappings appear in YAML files with the
+following structure:
+
+[source,yaml]
+----
+ae:  # Application elements
+  - entity: ARM_Entity_Name
+    aimelt:
+      content: mim_entity_name
+    refpath:
+      content: |-
+        {reference path here}
+    aa:  # Attribute assertions
+      - attribute: attribute_name
+        assertion_to: Target_ARM_Entity
+        refpath:
+          content: |-
+            {attribute reference path here}
+----
+
+The `refpath.content` fields contain reference paths expressed in the mapping
+language specified by this document.