From f282cd9373a4a9401f1d0fe1c107a422ccb9597d Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Mon, 20 Oct 2025 15:47:19 +0800 Subject: [PATCH] feat: add mapping spec document 5006 --- .../express-mapping/sections/01-scope.adoc | 16 + metanorma.yml | 1 + sources/express-mapping/document.adoc | 47 + .../express-mapping/sections/00-foreword.adoc | 27 + .../sections/00-introduction.adoc | 39 + .../express-mapping/sections/01-scope.adoc | 5 + .../express-mapping/sections/02-normrefs.adoc | 7 + .../express-mapping/sections/03-terms.adoc | 70 ++ .../express-mapping/sections/04-overview.adoc | 110 ++ .../sections/05-operators.adoc | 428 ++++++++ .../sections/06-navigation.adoc | 418 ++++++++ .../sections/07-constraints.adoc | 338 ++++++ .../sections/08-validation.adoc | 366 +++++++ .../express-mapping/sections/aa-examples.adoc | 964 ++++++++++++++++++ .../sections/az-bibliography.adoc | 4 + 15 files changed, 2840 insertions(+) create mode 100644 expresslang/docs/sources/express-mapping/sections/01-scope.adoc create mode 100644 sources/express-mapping/document.adoc create mode 100644 sources/express-mapping/sections/00-foreword.adoc create mode 100644 sources/express-mapping/sections/00-introduction.adoc create mode 100644 sources/express-mapping/sections/01-scope.adoc create mode 100644 sources/express-mapping/sections/02-normrefs.adoc create mode 100644 sources/express-mapping/sections/03-terms.adoc create mode 100644 sources/express-mapping/sections/04-overview.adoc create mode 100644 sources/express-mapping/sections/05-operators.adoc create mode 100644 sources/express-mapping/sections/06-navigation.adoc create mode 100644 sources/express-mapping/sections/07-constraints.adoc create mode 100644 sources/express-mapping/sections/08-validation.adoc create mode 100644 sources/express-mapping/sections/aa-examples.adoc create mode 100644 sources/express-mapping/sections/az-bibliography.adoc diff --git a/expresslang/docs/sources/express-mapping/sections/01-scope.adoc b/expresslang/docs/sources/express-mapping/sections/01-scope.adoc new file mode 100644 index 0000000..c75dda7 --- /dev/null +++ b/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. diff --git a/metanorma.yml b/metanorma.yml index a3f15ee..c368938 100644 --- a/metanorma.yml +++ b/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" diff --git a/sources/express-mapping/document.adoc b/sources/express-mapping/document.adoc new file mode 100644 index 0000000..cc41c99 --- /dev/null +++ b/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[] diff --git a/sources/express-mapping/sections/00-foreword.adoc b/sources/express-mapping/sections/00-foreword.adoc new file mode 100644 index 0000000..f655af7 --- /dev/null +++ b/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}_. diff --git a/sources/express-mapping/sections/00-introduction.adoc b/sources/express-mapping/sections/00-introduction.adoc new file mode 100644 index 0000000..4d21d4c --- /dev/null +++ b/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. diff --git a/sources/express-mapping/sections/01-scope.adoc b/sources/express-mapping/sections/01-scope.adoc new file mode 100644 index 0000000..3455193 --- /dev/null +++ b/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. + diff --git a/sources/express-mapping/sections/02-normrefs.adoc b/sources/express-mapping/sections/02-normrefs.adoc new file mode 100644 index 0000000..022781d --- /dev/null +++ b/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]]] diff --git a/sources/express-mapping/sections/03-terms.adoc b/sources/express-mapping/sections/03-terms.adoc new file mode 100644 index 0000000..0f9d555 --- /dev/null +++ b/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] +<> + +=== module interpreted model +preferred:[MIM] + +implementation model that maps ARM concepts to EXPRESS constructs using entities +and relationships from integrated resources + +[.source] +<> + +=== 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 diff --git a/sources/express-mapping/sections/04-overview.adoc b/sources/express-mapping/sections/04-overview.adoc new file mode 100644 index 0000000..afc3ee1 --- /dev/null +++ b/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. diff --git a/sources/express-mapping/sections/05-operators.adoc b/sources/express-mapping/sections/05-operators.adoc new file mode 100644 index 0000000..0b17bf4 --- /dev/null +++ b/sources/express-mapping/sections/05-operators.adoc @@ -0,0 +1,428 @@ +[[operators]] +== Operators + +=== General + +The mapping language uses operators to express different types of navigation +through EXPRESS schema entity relationships. + +Each operator has specific semantics defining how entities and attributes +relate in the path traversal. + +The operators are: + +[options="header",cols="1,5a"] +|=== +| Operator | Description + +| `<=` | Subtype relationship (left is subtype of right) | `entity_a <= entity_b` +| `=>` | Supertype relationship (left is supertype of right) | `entity_a => entity_b` +| `<-` | Inverse relationship (navigate backwards) | `entity_a <- entity_b.attr` +| `->` | Forward relationship (navigate through attribute) | `entity_a.attr -> entity_b` +| `{}` | Constraint block | `{entity.attr = 'value'}` +| `[]` | Required section constraint | `[section1][section2]` +| `()` | Alternative section | `(alt1)(alt2)` +| `<>` | Required reference path | `` +| `||` | Supertype entity marker | `||supertype||` +| `[i]` | Aggregate element access | `attr[i]` +| `[n]` | Ordered aggregate nth element | `attr[n]` +| `=` | Equality constraint | `attr = 'value'` +| `\` | Line continuation | `entity \` +| `*` | Relationship tree structure | `*relationship*` +| `--` | Comment | `-- this is a comment` +| `*>` | Select/enumeration extension | `select_a *> select_b` +| `<*` | Inverse select/enumeration extension | `select_a <* select_b` +| `!{}` | Negative constraint | `!{entity.attr = 'bad'}` + +|=== + +=== Subtype operator (symbol: `<=`) + +The subtype operator `<=` indicates that the left entity is a subtype of the +right entity. + +Syntax: + +[source] +---- +entity_a <= entity_b +---- + +Semantics: + +* `entity_a` must be defined as a subtype of `entity_b` in the EXPRESS schema +* `entity_a` inherits all attributes and constraints from `entity_b` +* The path continues from `entity_b` + +[example] +==== +[source] +---- +land <= +stratum_feature_template_component +---- + +Indicates that `land` is a subtype of `stratum_feature_template_component`. +==== + +=== Supertype operator (symbol: `=>`) + +The supertype operator `=>` indicates that the left entity is a supertype of +the right entity. + +Syntax: + +[source] +---- +entity_a => entity_b +---- + +Semantics: + +* `entity_a` must be defined as a supertype of `entity_b` in the EXPRESS schema +* `entity_b` is a subtype of `entity_a` and inherits from it +* The path continues from `entity_b` + +[example] +==== +[source] +---- +product_definition => +part_template_definition +---- + +Indicates that `product_definition` is a supertype of +`part_template_definition`. +==== + +=== Forward navigation operator (symbol: `->`) + +The forward navigation operator `->` navigates from an entity through one of +its attributes to the entity referenced by that attribute. + +Syntax: + +[source] +---- +entity_a.attribute_name -> entity_b +---- + +Semantics: + +* `entity_a` must have an attribute named `attribute_name` +* The attribute must reference `entity_b` or a supertype of `entity_b` +* The path continues from `entity_b` + +[example] +==== +[source] +---- +product_definition_relationship.relating_product_definition -> +product_definition +---- + +Navigates from `product_definition_relationship` through its +`relating_product_definition` attribute to `product_definition`. +==== + +=== Inverse navigation operator (symbol: `<-`) + +The inverse navigation operator `<-` navigates backwards from a referenced +entity to entities that reference it through a specific attribute. + +Syntax: + +[source] +---- +entity_b <- +entity_a.attribute_name +entity_a +---- + +Semantics: + +* `entity_a` must have an attribute named `attribute_name` +* The attribute must reference `entity_b` or a supertype of `entity_b` +* The path finds all `entity_a` instances that reference the current `entity_b` + through `attribute_name` +* The path continues from `entity_a` + +[example] +==== +[source] +---- +product_definition <- +product_definition_relationship.related_product_definition +product_definition_relationship +---- + +Finds all `product_definition_relationship` entities that reference +`product_definition` through their `related_product_definition` attribute. +==== + +=== Constraint block operators + +==== General + +Constraint blocks use curly braces `{}` to specify conditions that must be +satisfied during path navigation. + +==== Constraint start (operator: `{`) + +The constraint start operator `{` begins a constraint block. + +Syntax: + +[source] +---- +{constraint_expression} +---- + +==== Constraint end (operator: `}`) + +The constraint end operator `}` ends a constraint block. + +==== Equality operator (symbol: `=`) + +The equality operator `=` specifies that an attribute must equal a specific +value. + +Syntax: + +[source] +---- +{entity_name +entity_name.attribute_name = value} +---- + +Where `value` is: + +* A string literal in single quotes for STRING attributes +* A numeric literal without quotes for INTEGER, REAL, or NUMBER attributes +* A boolean or logical literal (TRUE, FALSE, UNKNOWN) for BOOLEAN or LOGICAL + attributes +* An enumeration value for ENUMERATION attributes + +[example] +==== +[source] +---- +{product_definition_relationship +product_definition_relationship.name = 'definition usage'} +---- + +Constrains the path to `product_definition_relationship` entities where the +`name` attribute equals `'definition usage'`. +==== + +=== Alternative section operators + +==== Required sections (operator: `[...]`) + +Square brackets `[]` enclose sections that must all be satisfied. + +Syntax: + +[source] +---- +[section_1] +[section_2] +---- + +Semantics: + +* All enclosed sections must be satisfied +* Each section is a distinct path segment + +==== Alternative sections (operator: `(...)`) + +Parentheses `()` enclose alternative sections where one alternative must be +satisfied. + +Syntax: + +[source] +---- +(alternative_1) +(alternative_2) +---- + +Semantics: + +* Exactly one of the enclosed alternatives must be satisfied +* Each alternative represents a different possible path + +=== Aggregate access operators + +==== Element access operator (symbol: `[i]`) + +Square brackets with `i` `[i]` indicate access to any element of an aggregate +attribute. + +Syntax: + +[source] +---- +entity_name.aggregate_attribute[i] +---- + +Semantics: + +* The attribute must be an aggregate type (ARRAY, LIST, SET, or BAG) +* The notation accesses an arbitrary element +* The specific element accessed is not specified + +==== Ordered element access operator (symbol: `[n]`) + +Square brackets with a number `[n]` indicate access to a specific element of an +ordered aggregate. + +Syntax: + +[source] +---- +entity_name.aggregate_attribute[n] +---- + +Where `n` is a positive integer. + +Semantics: + +* The attribute must be an ordered aggregate type (ARRAY or LIST) +* The notation accesses the `n`-th element +* The first element is at position 1 + +=== Special operators + +==== Negation operator (symbol: `!`) + +The negation operator `!` negates a constraint. + +Syntax: + +[source] +---- +!{entity_name +entity_name.attribute_name = value} +---- + +Semantics: + +* The constraint is inverted +* The path excludes entities that match the specified condition + +==== Line continuation operator (symbol: `\`) + +The backslash `\` indicates that the path expression continues on the next line. + +Syntax: + +[source] +---- +long_entity_name_a \ +long_entity_name_b +---- + +Semantics: + +* Purely syntactic +* The path is treated as if the line break did not exist +* Used for readability in complex paths + +==== Comment operator (symbol: `--`) + +The double dash `--` introduces a comment. + +Syntax: + +[source] +---- +entity_name -- this is a comment +next_entity_name +---- + +Semantics: + +* All text from `--` to the end of the line is ignored +* Used for documentation and annotations +* Does not affect path semantics + +==== Select extension operators (symbol: `*>`) + +The select extension operator `*>` indicates that a SELECT type extends another +SELECT type. + +Syntax: + +[source] +---- +select_type_a *> select_type_b +---- + +Semantics: + +* `select_type_a` is extended to include all options from `select_type_b` +* Used in schema extension contexts + +The inverse select extension operator `<*` indicates the inverse relationship. + +Syntax: + +[source] +---- +select_type_a <* select_type_b +---- + +Semantics: + +* `select_type_a` is an extension of `select_type_b` +* Equivalent to `select_type_b *> select_type_a` + +==== Supertype entity marker (symbol: `||`) + +The supertype entity marker `||` encloses a supertype entity name. + +Syntax: + +[source] +---- +||supertype_entity|| +---- + +Semantics: + +* Explicitly marks an entity as a supertype in the path +* Used for clarity in complex inheritance hierarchies + +==== Relationship tree marker (symbol: `*`) + +The relationship tree marker `*` indicates a relationship tree structure. + +Syntax: + +[source] +---- +*relationship_entity* +---- + +Semantics: + +* Multiple instances of the relationship entity may be assembled in a tree +* The path between the relationship entity and related entities is implied +* Used for complex recursive relationships + +==== Required reference path marker (symbol: `<>`) + +The required reference path marker `<>` encloses a required path segment. + +Syntax: + +[source] +---- + +---- + +Semantics: + +* The enclosed path segment must be present +* Used to emphasize mandatory portions of alternative paths diff --git a/sources/express-mapping/sections/06-navigation.adoc b/sources/express-mapping/sections/06-navigation.adoc new file mode 100644 index 0000000..b578fdf --- /dev/null +++ b/sources/express-mapping/sections/06-navigation.adoc @@ -0,0 +1,418 @@ +[[navigation]] +== Navigation patterns + +=== General + +This clause describes common navigation patterns used in EXPRESS mapping +reference paths. + +These patterns represent typical ways ARM entities and attributes map to MIM +entities through schema relationships. + +=== Subtype chain navigation + +==== Pattern description + +A subtype chain navigates through multiple subtype relationships from a starting +entity to a base entity. + +==== Syntax pattern + +[source] +---- +subtype_entity_1 <= +subtype_entity_2 <= +... +base_entity +---- + +==== Semantics + +* Each entity is a subtype of the next entity in the chain +* The chain terminates at a base entity that is not itself a subtype +* Each step must be a valid subtype relationship in the EXPRESS schema + +==== Example + +[example] +==== +[source] +---- +contact_size_dependent_land <= +land <= +stratum_feature_template_component <= +laminate_component <= +assembly_component <= +component_definition <= +product_definition +---- + +This path shows that `contact_size_dependent_land` ultimately derives from +`product_definition` through a chain of subtypes. +==== + +=== Supertype chain navigation + +==== Pattern description + +A supertype chain navigates through multiple supertype relationships from a base +entity to increasingly specific subtypes. + +==== Syntax pattern + +[source] +---- +base_entity => +supertype_entity_1 => +supertype_entity_2 => +... +specific_subtype +---- + +==== Semantics + +* Each entity is a supertype of the next entity in the chain +* The chain starts from a base entity and moves to more specific subtypes +* Each step must be a valid supertype relationship in the EXPRESS schema + +==== Example + +[example] +==== +[source] +---- +product_definition => +part_template_definition => +single_stratum_template => +single_stratum_continuous_template => +stratum_feature_template => +land_physical_template +---- + +This path shows progressive specialization from `product_definition` to the +specific `land_physical_template` entity. +==== + +=== Forward attribute navigation + +==== Pattern description + +Forward attribute navigation follows an attribute from an entity to the entity +it references. + +==== Syntax pattern + +[source] +---- +source_entity.reference_attribute -> target_entity +---- + +==== Semantics + +* `source_entity` has an attribute named `reference_attribute` +* The attribute type is `target_entity` or a SELECT type containing + `target_entity` +* The path continues from `target_entity` + +==== Example + +[example] +==== +[source] +---- +product_definition_relationship.relating_product_definition -> +product_definition +---- + +Navigates from a `product_definition_relationship` to the `product_definition` +it relates through the `relating_product_definition` attribute. +==== + +=== Inverse attribute navigation + +==== Pattern description + +Inverse attribute navigation finds entities that reference the current entity +through a specific attribute. + +==== Syntax pattern + +[source] +---- +referenced_entity <- +referencing_entity.reference_attribute +referencing_entity +---- + +==== Semantics + +* `referencing_entity` has an attribute named `reference_attribute` +* The attribute references `referenced_entity` +* The path finds all `referencing_entity` instances referencing the current + `referenced_entity` +* The path continues from `referencing_entity` + +==== Example + +[example] +==== +[source] +---- +product_definition <- +product_definition_relationship.related_product_definition +product_definition_relationship +---- + +Finds all `product_definition_relationship` entities that reference a specific +`product_definition` through their `related_product_definition` attribute. +==== + +=== Round-trip navigation + +==== Pattern description + +Round-trip navigation combines inverse and forward navigation to traverse a +relationship entity connecting two entities. + +==== Syntax pattern + +[source] +---- +entity_a <- +relationship_entity.attribute_to_a +relationship_entity +relationship_entity.attribute_to_b -> +entity_b +---- + +==== Semantics + +* Starts from `entity_a` +* Finds all `relationship_entity` instances referencing `entity_a` +* From those instances, navigates to `entity_b` +* Effectively finds all `entity_b` related to `entity_a` through + `relationship_entity` + +==== Example + +[example] +==== +[source] +---- +product_definition <- +product_definition_relationship.related_product_definition +product_definition_relationship +product_definition_relationship.relating_product_definition -> +product_definition +---- + +Finds all `product_definition` entities related to the starting +`product_definition` through `product_definition_relationship`. +==== + +=== Constrained navigation + +==== Pattern description + +Constrained navigation adds conditions that entities or attributes must satisfy +during path traversal. + +==== Syntax pattern + +[source] +---- +entity_name +{entity_name +entity_name.attribute_name = constraint_value} +---- + +==== Semantics + +* The constraint applies to the current entity in the path +* Only entities satisfying the constraint are considered valid +* Multiple constraints may be specified for the same entity + +==== Example + +[example] +==== +[source] +---- +product_definition_relationship +{product_definition_relationship +product_definition_relationship.name = 'definition usage'} +---- + +Constrains the path to only those `product_definition_relationship` entities +where the `name` attribute equals `'definition usage'`. +==== + +=== Constrained round-trip navigation + +==== Pattern description + +Combines round-trip navigation with constraints on the relationship entity. + +==== Syntax pattern + +[source] +---- +entity_a <- +relationship_entity.attribute_to_a +relationship_entity +{relationship_entity +relationship_entity.constraint_attribute = constraint_value} +relationship_entity.attribute_to_b -> +entity_b +---- + +==== Semantics + +* Navigates from `entity_a` through `relationship_entity` to `entity_b` +* Only `relationship_entity` instances satisfying the constraint are traversed +* Common pattern for relationship entities with type or role attributes + +==== Example + +[example] +==== +[source] +---- +product_definition <- +product_definition_relationship.related_product_definition +product_definition_relationship +{product_definition_relationship +product_definition_relationship.name = 'definition usage'} +product_definition_relationship.relating_product_definition -> +product_definition +---- + +Finds related `product_definition` entities specifically through +`product_definition_relationship` instances of type `'definition usage'`. +==== + +=== Mixed subtype and attribute navigation + +==== Pattern description + +Combines subtype relationships with attribute navigation in a single path. + +==== Syntax pattern + +[source] +---- +entity_a <= +entity_b <= +... +base_entity <- +relationship.attribute +relationship +relationship.other_attribute -> +target_entity +---- + +==== Semantics + +* First establishes the entity hierarchy through subtype relationships +* Then navigates through attributes and relationships +* Common in complex mappings involving both inheritance and association + +==== Example + +[example] +==== +[source] +---- +land <= +stratum_feature_template_component <= +laminate_component <= +assembly_component <= +component_definition <= +product_definition <- +product_definition_relationship.related_product_definition +product_definition_relationship +{product_definition_relationship +product_definition_relationship.name = 'definition usage'} +product_definition_relationship.relating_product_definition -> +product_definition => +part_template_definition +---- + +Establishes the subtype chain, navigates through relationships, and continues to +supertypes. +==== + +=== Alternative path navigation + +==== Pattern description + +Specifies multiple alternative paths, where at least one must be valid. + +==== Syntax pattern + +[source] +---- +(path_alternative_1) +(path_alternative_2) +---- + +==== Semantics + +* Exactly one of the alternatives must be satisfied +* Each alternative is a complete path segment +* Used when different schema patterns can satisfy the same mapping + +==== Example + +[example] +==== +[source] +---- +(product_definition <- +product_definition_formation.of_product +product_definition_formation) +(product_definition <- +product_definition_context_association.definition +product_definition_context_association) +---- + +The target can be reached through either `product_definition_formation` or +`product_definition_context_association`. +==== + +=== Required combined path navigation + +==== Pattern description + +Specifies multiple path segments that must all be satisfied. + +==== Syntax pattern + +[source] +---- +[required_segment_1] +[required_segment_2] +---- + +==== Semantics + +* All required segments must be satisfied +* Each segment is a distinct portion of the path +* Used when multiple relationships must exist simultaneously + +==== Example + +[example] +==== +[source] +---- +[product_definition <= +characterized_product_definition <= +characterized_definition] +[product_definition_shape <= +property_definition] +---- + +Both the product definition characterization and the shape property definition +must exist. +==== diff --git a/sources/express-mapping/sections/07-constraints.adoc b/sources/express-mapping/sections/07-constraints.adoc new file mode 100644 index 0000000..96688f4 --- /dev/null +++ b/sources/express-mapping/sections/07-constraints.adoc @@ -0,0 +1,338 @@ +[[constraints]] +== Constraints + +=== General + +Constraints specify conditions that entities or attributes must satisfy during +path navigation. + +They enable precise mapping specifications by limiting paths to entities +matching specific criteria. + +=== Constraint syntax + +==== Basic structure + +A constraint block is enclosed in curly braces and contains one or more +constraint expressions. + +Syntax: + +[source] +---- +{entity_name +entity_name.attribute_name operator value} +---- + +==== Multiple constraints + +Multiple constraints may be specified within a single block or across multiple +blocks. + +Syntax for single block: + +[source] +---- +{entity_name +entity_name.attribute_1 = value_1 +entity_name.attribute_2 = value_2} +---- + +Syntax for multiple blocks: + +[source] +---- +{entity_name +entity_name.attribute_1 = value_1} +{entity_name +entity_name.attribute_2 = value_2} +---- + +Semantics: + +* All constraints must be satisfied +* Multiple constraints represent a logical AND condition + +[example] +==== +[source] +---- +{product_definition_relationship +product_definition_relationship.name = 'definition usage' +product_definition_relationship.description = 'explicit'} +---- + +Requires both the `name` and `description` attributes to match. +==== + +=== Value types + +==== String values + +String values must be enclosed in single quotes. + +Syntax: + +[source] +---- +{entity_name +entity_name.string_attribute = 'string value'} +---- + +[example] +==== +[source] +---- +{product_definition_relationship +product_definition_relationship.name = 'definition usage'} +---- +==== + +==== Numeric values + +Numeric values (INTEGER, REAL, NUMBER) are specified without quotes. + +Syntax: + +[source] +---- +{entity_name +entity_name.numeric_attribute = numeric_value} +---- + +[example] +==== +[source] +---- +{dimension_count +dimension_count.dim = 3} +---- +==== + +==== Boolean and logical values + +Boolean and logical values use keywords TRUE, FALSE, or UNKNOWN. + +Syntax: + +[source] +---- +{entity_name +entity_name.boolean_attribute = TRUE} +---- + +[example] +==== +[source] +---- +{representation_item +representation_item.optional_flag = TRUE} +---- +==== + +==== Enumeration values + +Enumeration values are specified as identifiers without quotes. + +Syntax: + +[source] +---- +{entity_name +entity_name.enum_attribute = ENUM_VALUE} +---- + +[example] +==== +[source] +---- +{geometric_representation_context +geometric_representation_context.coordinate_space_dimension = THREE_D} +---- +==== + +=== Negated constraints + +==== Syntax + +The negation operator `!` inverts a constraint. + +[source] +---- +!{entity_name +entity_name.attribute_name = value} +---- + +==== Semantics + +* The path excludes entities matching the specified condition +* Equivalent to "attribute_name NOT EQUAL TO value" + +==== Example + +[example] +==== +[source] +---- +!{product_definition_relationship +product_definition_relationship.name = 'alternate'} +---- + +Excludes `product_definition_relationship` entities where `name` is +`'alternate'`. +==== + +=== Constraint application + +==== Applying to current entity + +Constraints apply to the entity specified in the constraint block. + +[source] +---- +entity_name +{entity_name +entity_name.attribute = value} +---- + +The constraint is checked when the path reaches `entity_name`. + +==== Applying during navigation + +Constraints can be placed at any point in the path to filter entities during +navigation. + +[example] +==== +[source] +---- +product_definition <- +product_definition_relationship.related_product_definition +product_definition_relationship +{product_definition_relationship +product_definition_relationship.name = 'definition usage'} +product_definition_relationship.relating_product_definition -> +product_definition +---- + +The constraint filters which `product_definition_relationship` instances are +traversed. +==== + +=== Constraint validation + +==== Entity validation + +The constrained entity must: + +* Exist in the EXPRESS schema +* Appear in the path at the location where the constraint is specified + +==== Attribute validation + +The constrained attribute must: + +* Exist on the specified entity +* Be accessible (not private or restricted) +* Have a type compatible with the constraint value + +==== Value validation + +The constraint value must: + +* Match the attribute's base type (STRING, INTEGER, etc.) +* Follow proper literal syntax for the type +* For enumerations, be a valid enumeration value + +==== Type compatibility + +The following table shows required value syntax for each attribute type: + +[cols="1,1,2",options="header"] +|=== +|Attribute type |Value syntax |Example + +|STRING +|Single-quoted string +|`'definition usage'` + +|INTEGER +|Unquoted integer +|`42` + +|REAL +|Unquoted decimal +|`3.14159` + +|NUMBER +|Unquoted number +|`100` or `2.5` + +|BOOLEAN +|TRUE or FALSE +|`TRUE` + +|LOGICAL +|TRUE, FALSE, or UNKNOWN +|`UNKNOWN` + +|ENUMERATION +|Unquoted enumeration value +|`CARTESIAN` + +|=== + +=== Common constraint patterns + +==== Relationship type constraints + +Constraining relationship entities by their type or role. + +[example] +==== +[source] +---- +{product_definition_relationship +product_definition_relationship.name = 'definition usage'} +---- +==== + +==== Geometry type constraints + +Constraining geometric entities by their dimensionality or type. + +[example] +==== +[source] +---- +{geometric_representation_context +geometric_representation_context.coordinate_space_dimension = 3} +---- +==== + +==== Description constraints + +Constraining by description attributes that specify roles or purposes. + +[example] +==== +[source] +---- +{shape_aspect +shape_aspect.description = 'land interface terminal'} +---- +==== + +==== Multiple attribute constraints + +Requiring multiple attributes to satisfy conditions simultaneously. + +[example] +==== +[source] +---- +{characterized_object +characterized_object.name = 'boundary' +characterized_object.description = 'outer'} +---- +==== diff --git a/sources/express-mapping/sections/08-validation.adoc b/sources/express-mapping/sections/08-validation.adoc new file mode 100644 index 0000000..e0cf31b --- /dev/null +++ b/sources/express-mapping/sections/08-validation.adoc @@ -0,0 +1,366 @@ +[[validation]] +== Validation rules + +=== General + +Validation ensures that reference paths are correct and navigate valid +relationships in the EXPRESS schema repository. + +All validation rules shall be applied to verify path correctness. + +=== Entity validation + +==== Entity existence + +All entities referenced in a path must exist in the EXPRESS schema repository. + +Rule: + +* For each entity name in the path, the validator shall verify that an entity + with that exact name exists in the repository + +Error condition: + +* If an entity does not exist, the path is invalid + +Error message shall include: + +* The entity name that was not found +* The location in the path where the entity appears +* The source file and line number if available + +[example] +==== +For the path: + +[source] +---- +non_existent_entity <= +product_definition +---- + +If `non_existent_entity` does not exist in the schema, the validator shall +report: "Entity 'non_existent_entity' not found in repository". +==== + +==== Entity name case sensitivity + +Entity names in EXPRESS are case-insensitive, but the validator should use +canonical case matching. + +Rule: + +* Entity name matching shall be case-insensitive +* The validator may optionally warn if case does not match the schema definition + +=== Relationship validation + +==== Subtype relationship validation + +For subtype operator `\<=`, the left entity must be a declared subtype of the +right entity. + +Rule: + +* The validator shall verify that the left entity's definition includes the + right entity in its SUBTYPE OF clause, either directly or through transitive + subtype relationships + +Error condition: + +* If the subtype relationship does not exist, the path is invalid + +Error message shall include: + +* The two entity names involved +* Whether the relationship should be direct or transitive +* A suggestion to verify the entity hierarchy + +[example] +==== +For the path: + +[source] +---- +land <= +product_definition +---- + +The validator shall verify that `land` is a subtype of `product_definition`, +either directly or through intermediate entities. +==== + +==== Supertype relationship validation + +For supertype operator `\=>`, the left entity must be a declared supertype of +the right entity. + +Rule: + +* The validator shall verify that the right entity's definition includes the + left entity in its SUBTYPE OF clause, either directly or through transitive + relationships + +Error condition: + +* If the supertype relationship does not exist, the path is invalid + +=== Attribute validation + +==== Attribute existence + +All attributes referenced in navigation must exist on the specified entity. + +Rule: + +* For forward navigation `entity.attribute ->`, the validator shall verify that + `entity` has an attribute named `attribute` +* For inverse navigation `<- entity.attribute`, the validator shall verify that + `entity` has an attribute named `attribute` + +Error condition: + +* If the attribute does not exist, the path is invalid + +Error message shall include: + +* The entity name +* The attribute name that was not found +* Available attributes on the entity (as suggestion) + +==== Attribute name case sensitivity + +Attribute names in EXPRESS are case-insensitive. + +Rule: + +* Attribute name matching shall be case-insensitive +* The validator may optionally warn if case does not match the schema definition + +=== Navigation validation + +==== Forward navigation validation + +For forward navigation `entity_a.attribute -> entity_b`: + +Rules: + +* The attribute must exist on `entity_a` +* The attribute type must be `entity_b` or a type that can reference `entity_b` +* If the attribute type is a SELECT, `entity_b` must be one of the SELECT options + +Error conditions: + +* Attribute does not exist on `entity_a` +* Attribute type is not compatible with `entity_b` +* Attribute type is a basic type (STRING, INTEGER, etc.) and cannot reference + an entity + +==== Inverse navigation validation + +For inverse navigation `entity_b <- entity_a.attribute`: + +Rules: + +* The attribute must exist on `entity_a` +* The attribute type must be `entity_b` or a type that can reference `entity_b` +* The path is following the relationship backwards from `entity_b` to `entity_a` + +Error conditions: + +* Attribute does not exist on `entity_a` +* Attribute does not reference `entity_b` + +==== Navigation continuity + +The validator shall verify that each navigation step properly connects to the +next step. + +Rule: + +* The ending entity of one step must match or be compatible with the starting + entity of the next step +* For subtype/supertype chains, entities must be properly related +* For attribute navigation, the referenced entity must match the next entity in + the path + +Error condition: + +* If navigation continuity is broken, the path is invalid + +=== Constraint validation + +==== Constraint entity validation + +For each constraint, the constrained entity must: + +* Exist in the schema +* Appear in the path at or before the constraint location + +Rule: + +* The validator shall verify that the entity specified in the constraint block + exists and is part of the current path context + +==== Constraint attribute validation + +For each constraint, the constrained attribute must: + +* Exist on the specified entity +* Be accessible (not DERIVED or INVERSE unless explicitly allowed) + +Rule: + +* The validator shall verify that the attribute exists on the entity and can be + constrained + +Error condition: + +* If the attribute does not exist or cannot be constrained, the constraint is + invalid + +==== Constraint value type validation + +For each constraint value, the type must be compatible with the attribute type. + +Rules for type compatibility: + +[cols="1,1,2",options="header"] +|=== +|Attribute type |Required value syntax |Validation rule + +|STRING +|Single-quoted string +|Value must be a valid string literal + +|INTEGER +|Unquoted integer +|Value must be a valid integer + +|REAL +|Unquoted decimal +|Value must be a valid real number + +|NUMBER +|Unquoted number +|Value must be a valid number + +|BOOLEAN +|TRUE or FALSE +|Value must be TRUE or FALSE + +|LOGICAL +|TRUE, FALSE, or UNKNOWN +|Value must be TRUE, FALSE, or UNKNOWN + +|ENUMERATION +|Unquoted identifier +|Value must be a valid enumeration item + +|SELECT +|Depends on selected type +|Value must match one of the SELECT options + +|=== + +Error condition: + +* If value type does not match attribute type, the constraint is invalid + +Error message shall include: + +* The attribute name and its type +* The provided value and its inferred type +* Expected value format + +[example] +==== +For a STRING attribute: + +[source] +---- +{entity.string_attr = 'valid'} -- Valid +{entity.string_attr = invalid} -- Invalid: missing quotes +{entity.string_attr = 123} -- Invalid: wrong type +---- +==== + +=== Path completeness validation + +==== Start entity validation + +The path should start with a valid entity from the ARM entity being mapped. + +Rule: + +* The first entity in the refpath should match or be compatible with the ARM + entity specified in the mapping + +Note: This rule may be relaxed for attribute mappings where the path starts +from a different context. + +==== End entity validation + +The path should end with a valid MIM entity. + +Rule: + +* The final entity in the path should be a valid MIM entity that can represent + the ARM concept + +Note: The specific MIM entity expected may be specified in the mapping's +`aimelt` field. + +=== Error collection + +The validator shall collect all errors rather than stopping at the first error. + +Rule: + +* The validator shall continue processing the entire path +* All errors shall be collected and reported together +* Each error shall include sufficient context for diagnosis + +=== Warning conditions + +The validator may issue warnings for conditions that are not strictly invalid +but may indicate problems: + +* Case mismatches between path and schema definitions +* Deprecated entities or attributes +* Excessively long paths that may indicate design issues +* Redundant navigation steps +* Constraints that are always true or always false + +=== Validation output + +==== Success output + +For valid paths, the validator shall report: + +* Path validation status: VALID +* Starting entity +* Ending entity +* Number of navigation steps +* List of entities traversed + +==== Error output + +For invalid paths, the validator shall report: + +* Path validation status: INVALID +* List of all errors found +* For each error: +** Error type (entity not found, invalid relationship, etc.) +** Error message +** Location in path (entity name, line number if available) +** Relevant path context +** Suggestion for correction if available + +==== Output formats + +The validator should support multiple output formats: + +* Text format for human reading +* JSON format for programmatic processing +* YAML format for integration with other tools diff --git a/sources/express-mapping/sections/aa-examples.adoc b/sources/express-mapping/sections/aa-examples.adoc new file mode 100644 index 0000000..a852707 --- /dev/null +++ b/sources/express-mapping/sections/aa-examples.adoc @@ -0,0 +1,964 @@ +[appendix] +== Examples + +=== General + +This annex provides comprehensive examples of EXPRESS mapping language reference +paths drawn from actual ISO 10303 module mapping specifications. Each example +demonstrates specific patterns and operators described in the normative clauses +of this document. + +[[examples-simple-chains]] +=== Simple entity chains + +==== General + +Simple entity chains demonstrate the most basic form of reference path +navigation, using only subtype and supertype operators. + +==== Basic subtype chain + +This example from ISO 10303-1692 (Land) shows a simple subtype chain navigating +from a specialized entity to its base entity. + +.Simple subtype navigation +[example] +==== +[source] +---- +land <= +stratum_feature_template_component <= +laminate_component <= +assembly_component <= +component_definition <= +product_definition +---- + +This path specifies that: + +* `land` is a subtype of `stratum_feature_template_component` +* `stratum_feature_template_component` is a subtype of `laminate_component` +* `laminate_component` is a subtype of `assembly_component` +* `assembly_component` is a subtype of `component_definition` +* `component_definition` is a subtype of `product_definition` + +The path establishes the complete subtype hierarchy from the ARM entity `Land` +to the base MIM entity `product_definition`. +==== + +==== Extended subtype chain + +This example shows a longer subtype chain for more specialized entities. + +.Extended subtype navigation +[example] +==== +[source] +---- +plated_passage_dependent_land <= +inter_stratum_feature_dependent_land <= +land <= +stratum_feature_template_component <= +laminate_component <= +assembly_component <= +component_definition <= +product_definition +---- + +This path demonstrates: + +* Multiple levels of specialization through subtype relationships +* Navigation from a highly specialized entity (`plated_passage_dependent_land`) +through intermediate specializations to the base entity +* The hierarchical nature of entity classifications in ISO 10303 +==== + +[[examples-round-trip]] +=== Round-trip navigation + +==== General + +Round-trip paths navigate forward through relationships, then backward through +inverse relationships, demonstrating complex attribute-based navigation +patterns. + +==== Simple round-trip with constraint + +This example from ISO 10303-1692 shows a complete round-trip pattern with a +constraint. + +.Round-trip with constrained relationship +[example] +==== +[source] +---- +land <= +stratum_feature_template_component <= +laminate_component <= +assembly_component <= +component_definition <= +product_definition <- +product_definition_relationship.related_product_definition +product_definition_relationship +{product_definition_relationship +product_definition_relationship.name = 'definition usage'} +product_definition_relationship.relating_product_definition -> +product_definition => +part_template_definition => +single_stratum_template => +single_stratum_continuous_template => +stratum_feature_template => +land_physical_template +---- + +This path demonstrates: + +* Subtype chain navigation (`<=`) from `land` to `product_definition` +* Inverse attribute navigation (`<-`) via `product_definition_relationship.related_product_definition` +* Constraint application (`{}`) requiring `name = 'definition usage'` +* Forward attribute navigation (`->`) via `product_definition_relationship.relating_product_definition` +* Supertype chain navigation (`=>`) from `product_definition` to `land_physical_template` + +The complete path maps the ARM attribute `derived_from` of entity `Land` to an instance of `Land_physical_template` in the MIM. +==== + +==== Complex round-trip with multiple constraints + +This example shows a more complex round-trip with detailed constraints. + +.Complex constrained round-trip +[example] +==== +[source] +---- +plated_passage_dependent_land <= +inter_stratum_feature_dependent_land <= +land <= +stratum_feature_template_component <= +laminate_component <= +assembly_component <= +component_definition <= +product_definition <- +product_definition_relationship.related_product_definition +product_definition_relationship +{product_definition_relationship +product_definition_relationship.name = 'definition usage'} +product_definition_relationship.relating_product_definition -> +product_definition => +part_template_definition => +single_stratum_template => +single_stratum_continuous_template => +stratum_feature_template => +land_physical_template => +default_passage_based_land_physical_template => +default_plated_passage_based_land_physical_template +---- + +This path illustrates: + +* A complete subtype chain to establish the starting context +* A constrained relationship traversal to find related definitions +* An extended supertype chain navigating through multiple specialization levels +* Multiple constraint validations ensuring the correct relationship type + +The path maps from a specialized ARM entity through a constrained relationship to a specialized template in the MIM. +==== + +[[examples-shape-aspect]] +=== Shape aspect navigation + +==== General + +Shape aspect navigation patterns demonstrate complex traversals through shape definitions and feature relationships. + +==== Shape aspect with feature instantiation + +This example from ISO 10303-1698 shows navigation through shape aspects and feature relationships. + +.Shape aspect to component navigation +[example] +==== +[source] +---- +laminate_component_interface_terminal <= +laminate_component_feature <= +component_feature <= +shape_aspect +shape_aspect.of_shape -> +product_definition_shape <= +property_definition +property_definition.definition -> +characterized_definition +characterized_definition = characterized_product_definition +characterized_product_definition +characterized_product_definition = product_definition +product_definition => +component_definition => +assembly_component => +laminate_component => +stratum_feature_template_component => +land => +contact_size_dependent_land +---- + +This path demonstrates: + +* Subtype navigation through shape aspect hierarchy +* Forward navigation via `shape_aspect.of_shape` attribute +* Navigation through property definitions +* Type selection using `=` operator for `characterized_definition` +* Multiple type selections for `characterized_product_definition` +* Supertype chain to reach the target entity + +The complete path establishes the relationship between a terminal feature and its associated component. +==== + +==== Shape aspect with relationship constraint + +This example shows constrained navigation through shape aspect relationships. + +.Constrained shape aspect relationship +[example] +==== +[source] +---- +laminate_component_interface_terminal <= +laminate_component_feature <= +component_feature <= +shape_aspect <- +shape_aspect_relationship.related_shape_aspect +shape_aspect_relationship +{shape_aspect_relationship +shape_aspect_relationship.name = 'instantiated feature'} +shape_aspect_relationship.relating_shape_aspect -> +{shape_aspect +shape_aspect.description = 'interface terminal'} +shape_aspect => +land_template_terminal +---- + +This path illustrates: + +* Inverse navigation through `shape_aspect_relationship` +* Constraint on the relationship name +* Forward navigation to the relating shape aspect +* Constraint on the shape aspect description +* Supertype navigation to the target entity + +The path validates both the relationship type and the shape aspect characteristics. +==== + +[[examples-alternative-paths]] +=== Alternative paths + +==== General + +Alternative paths specify multiple valid navigation routes to reach the target entity or attribute value. + +==== Simple alternative with shared endpoint + +This example from ISO 10303-1692 demonstrates alternative subtype chains. + +.Alternative subtype paths +[example] +==== +[source] +---- +land_with_join_terminal <= +[land <= +stratum_feature_template_component <= +laminate_component <= +assembly_component <= +component_definition <= +product_definition] +[laminate_component_join_terminal <= +laminate_component_feature <= +component_feature <= +shape_aspect] +---- + +This path specifies: + +* Two alternative navigation routes enclosed in `[]` brackets +* First alternative: subtype chain through product definition hierarchy +* Second alternative: subtype chain through shape aspect hierarchy +* Both alternatives must lead to valid entity instances + +The entity `land_with_join_terminal` can be reached through either path. +==== + +[[examples-constrained-paths]] +=== Constrained paths + +==== General + +Constrained paths apply validation criteria at specific points in the navigation sequence. + +==== Single constraint on entity attribute + +This example shows a simple constraint on an entity attribute. + +.Attribute value constraint +[example] +==== +[source] +---- +laminate_component_interface_terminal <= +laminate_component_feature <= +component_feature <= +shape_aspect +{shape_aspect +shape_aspect.description = 'land interface terminal'} +---- + +This path demonstrates: + +* Navigation through a subtype chain +* Constraint application at the final entity +* Validation that `description` attribute equals a specific string value + +Only instances with the specified description value satisfy this mapping. +==== + +==== Multiple constraints in sequence + +This example shows multiple constraints applied at different points. + +.Multiple sequential constraints +[example] +==== +[source] +---- +land <= +stratum_feature_template_component <= +laminate_component <= +assembly_component <= +component_definition <= +product_definition_relationship +{product_definition_relationship +product_definition_relationship.name = 'alternate instantiated template'} +product_definition_relationship.relating_product_definition -> +product_definition => +part_template_definition => +single_stratum_template => +single_stratum_continuous_template => +stratum_feature_template => +land_physical_template +---- + +This path illustrates: + +* A subtype chain leading to a relationship entity +* Constraint on the relationship's name attribute +* Navigation through the constrained relationship +* Continued navigation through supertype chain + +Each constraint must be satisfied for the path to be valid. +==== + +[[examples-reference-relationships]] +=== Reference relationships + +==== General + +Reference relationship patterns establish connections between entities through named relationships. + +==== Simple reference relationship + +This example shows a basic reference relationship pattern. + +.Named reference relationship +[example] +==== +[source] +---- +plated_passage_dependent_land <= +inter_stratum_feature_dependent_land <= +land <= +stratum_feature_template_component <= +laminate_component <= +assembly_component <= +component_definition <= +product_definition <- +product_definition_relationship.related_product_definition +product_definition_relationship +{product_definition_relationship +product_definition_relationship.name = 'reference plated passage'} +product_definition_relationship.relating_product_definition -> +product_definition => +component_definition => +assembly_component => +laminate_component => +inter_stratum_feature => +plated_inter_stratum_feature => +plated_passage +---- + +This path demonstrates: + +* Establishing context through subtype chain +* Inverse navigation to find relationships +* Constraint identifying the reference relationship by name +* Forward navigation through the relationship +* Supertype navigation to the referenced entity + +The pattern establishes the `reference_plated_passage` attribute mapping. +==== + +==== Multiple reference relationships + +This example from ISO 10303-1692 shows handling multiple reference relationships. + +.Dual reference pattern +[example] +==== +[source] +---- +unsupported_passage_dependent_land <= +inter_stratum_feature_dependent_land <= +land <= +stratum_feature_template_component <= +laminate_component <= +assembly_component <= +component_definition <= +product_definition <- +product_definition_relationship.related_product_definition +product_definition_relationship +{product_definition_relationship +product_definition_relationship.name = 'reference passage'} +product_definition_relationship.relating_product_definition -> +product_definition => +component_definition => +assembly_component => +laminate_component => +inter_stratum_feature => +unsupported_passage +---- + +This path illustrates: + +* A reference relationship identified by name 'reference passage' +* Navigation pattern similar to other reference relationships +* Targeting a different entity type (unsupported_passage) + +Different reference relationship names distinguish between multiple relationships from the same source entity. +==== + +[[examples-thermal-isolation]] +=== Structured template navigation + +==== General + +Structured template patterns navigate through geometric template hierarchies. + +==== Structured component to template + +This example from ISO 10303-1698 shows navigation from a structured component to its template. + +.Structured template reference +[example] +==== +[source] +---- +thermal_isolation_removal_component <= +material_removal_structured_component <= +structured_layout_component <= +assembly_group_component <= +assembly_component <= +component_definition <= +product_definition <- +product_definition_relationship.related_product_definition +product_definition_relationship +{product_definition_relationship.name = 'definition usage'} +product_definition_relationship.relating_product_definition -> +product_definition => +part_template_definition => +geometric_template => +structured_template => +single_stratum_structured_template => +material_removal_structured_template => +thermal_isolation_removal_template +---- + +This path demonstrates: + +* Navigation through structured component hierarchy +* Constrained relationship to template definition +* Navigation through geometric template specializations +* Multiple levels of template specialization + +The pattern establishes the relationship between a physical component and its abstract template definition. +==== + +==== Dependent thermal isolation pattern + +This example shows a dependent component referencing its template. + +.Dependent component template reference +[example] +==== +[source] +---- +dependent_thermal_isolation_removal_component <= +thermal_isolation_removal_component <= +material_removal_structured_component <= +structured_layout_component <= +assembly_group_component <= +assembly_component <= +component_definition <= +product_definition <- +product_definition_relationship.related_product_definition +product_definition_relationship +{product_definition_relationship.name = 'definition usage'} +product_definition_relationship.relating_product_definition -> +product_definition => +part_template_definition => +geometric_template => +structured_template => +single_stratum_structured_template => +material_removal_structured_template => +thermal_isolation_removal_template => +dependent_thermal_isolation_removal_template +---- + +This path illustrates: + +* Additional level of specialization for dependent components +* Same relationship pattern as independent components +* Extended template specialization hierarchy + +Dependent and independent components follow parallel mapping patterns with different specialization levels. +==== + +[[examples-electrical-isolation]] +=== Material removal patterns + +==== General + +Material removal patterns demonstrate navigation through specialized component and template hierarchies. + +==== Electrical isolation removal + +This example from ISO 10303-1698 shows electrical isolation removal mapping. + +.Electrical isolation component to template +[example] +==== +[source] +---- +dependent_electrical_isolation_removal_component <= +electrical_isolation_laminate_component <= +material_removal_laminate_component <= +laminate_component <= +assembly_component <= +component_definition <= +product_definition <- +product_definition_relationship.related_product_definition +product_definition_relationship +{product_definition_relationship.name = 'definition usage'} +product_definition_relationship.relating_product_definition -> +product_definition => +part_template_definition => +single_stratum_template => +single_stratum_continuous_template => +material_removal_feature_template => +electrical_isolation_removal_template => +dependent_electrical_isolation_removal_template +---- + +This path demonstrates: + +* Material removal component specialization hierarchy +* Constrained definition usage relationship +* Material removal feature template hierarchy +* Parallel structure between component and template hierarchies + +The pattern establishes the mapping for electrical isolation removal features. +==== + +[[examples-attachment-size]] +=== Attachment size based patterns + +==== General + +Attachment size based patterns demonstrate navigation to templates parameterized by attachment dimensions. + +==== Contact size dependent land + +This example from ISO 10303-1692 shows navigation to an attachment size based template. + +.Attachment size based template reference +[example] +==== +[source] +---- +contact_size_dependent_land <= +land <= +stratum_feature_template_component <= +laminate_component <= +assembly_component <= +component_definition <= +product_definition <- +product_definition_relationship.related_product_definition +product_definition_relationship +{product_definition_relationship +product_definition_relationship.name = 'definition usage'} +product_definition_relationship.relating_product_definition -> +product_definition => +part_template_definition => +single_stratum_template => +single_stratum_continuous_template => +stratum_feature_template => +land_physical_template => +default_attachment_size_based_land_physical_template +---- + +This path demonstrates: + +* Navigation from a size-dependent component +* Constrained relationship to template definition +* Specialization to attachment size based template +* The relationship between component sizing and template selection + +The pattern enables parameterization of land geometry based on attached component sizes. +==== + +[[examples-passage-based]] +=== Passage based patterns + +==== General + +Passage based patterns establish relationships between land features and passage features that they interface with. + +==== Unsupported passage based land + +This example shows the mapping for lands based on unsupported passages. + +.Unsupported passage based template +[example] +==== +[source] +---- +unsupported_passage_dependent_land <= +inter_stratum_feature_dependent_land <= +land <= +stratum_feature_template_component <= +laminate_component <= +assembly_component <= +component_definition <= +product_definition <- +product_definition_relationship.related_product_definition +product_definition_relationship +{product_definition_relationship +product_definition_relationship.name = 'definition usage'} +product_definition_relationship.relating_product_definition -> +product_definition => +part_template_definition => +single_stratum_template => +single_stratum_continuous_template => +stratum_feature_template => +land_physical_template => +default_passage_based_land_physical_template => +default_unsupported_passage_based_land_physical_template +---- + +This path illustrates: + +* Navigation from passage-dependent land +* Template specialization for passage-based features +* Additional specialization for unsupported passages +* Hierarchical template classification + +The pattern enables land geometry to be defined relative to associated passage features. +==== + +==== Plated passage based land + +This example shows the mapping for lands based on plated passages. + +.Plated passage based template +[example] +==== +[source] +---- +plated_passage_dependent_land <= +inter_stratum_feature_dependent_land <= +land <= +stratum_feature_template_component <= +laminate_component <= +assembly_component <= +component_definition <= +product_definition <- +product_definition_relationship.related_product_definition +product_definition_relationship +{product_definition_relationship +product_definition_relationship.name = 'definition usage'} +product_definition_relationship.relating_product_definition -> +product_definition => +part_template_definition => +single_stratum_template => +single_stratum_continuous_template => +stratum_feature_template => +land_physical_template => +default_passage_based_land_physical_template => +default_plated_passage_based_land_physical_template +---- + +This path demonstrates: + +* Same base pattern as unsupported passage based land +* Different final template specialization +* Consistent mapping structure across passage types + +The pattern maintains structural consistency while accommodating different passage metallization types. +==== + +[[examples-alternate-definitions]] +=== Alternate definition patterns + +==== General + +Alternate definition patterns provide alternative template references for entities that support multiple configuration options. + +==== Alternate land definition + +This example from ISO 10303-1692 shows the mapping for alternate land template definitions. + +.Alternate template instantiation +[example] +==== +[source] +---- +land <= +stratum_feature_template_component <= +laminate_component <= +assembly_component <= +component_definition <= +product_definition_relationship +{product_definition_relationship +product_definition_relationship.name = 'alternate instantiated template'} +product_definition_relationship.relating_product_definition -> +product_definition => +part_template_definition => +single_stratum_template => +single_stratum_continuous_template => +stratum_feature_template => +land_physical_template +---- + +This path demonstrates: + +* Direct navigation to relationship entity (no inverse navigation) +* Constraint specifying 'alternate instantiated template' relationship +* Navigation through the relationship to template +* Simplified path for alternate definitions + +The pattern enables entities to reference multiple template definitions for different configuration scenarios. +==== + +[[examples-validation-scenarios]] +=== Validation scenarios + +==== General + +These examples illustrate various validation scenarios and error conditions. + +==== Valid path with all constraints satisfied + +This example shows a valid path where all constraints are satisfied. + +.Fully valid reference path +[example] +==== +[source] +---- +land <= +stratum_feature_template_component <= +laminate_component <= +assembly_component <= +component_definition <= +product_definition <- +product_definition_relationship.related_product_definition +product_definition_relationship +{product_definition_relationship +product_definition_relationship.name = 'definition usage'} +product_definition_relationship.relating_product_definition -> +product_definition => +part_template_definition => +single_stratum_template => +single_stratum_continuous_template => +stratum_feature_template => +land_physical_template +---- + +Validation checks: + +* All entities exist in the EXPRESS repository +* All subtype relationships are valid +* Attributes used for navigation exist +* Relationship constraints are syntactically correct +* Complete path from ARM to MIM + +This path would pass all validation rules. +==== + +==== Invalid entity reference + +This example shows an error condition with an invalid entity reference. + +.Invalid entity in path +[example] +==== +[source] +---- +land <= +invalid_entity_name <= +laminate_component <= +assembly_component +---- + +Validation errors: + +* Entity 'invalid_entity_name' does not exist in the EXPRESS repository +* Subtype relationship cannot be validated +* Path is incomplete + +This path would fail entity existence validation. +==== + +==== Invalid attribute reference + +This example shows an error condition with an invalid attribute reference. + +.Invalid attribute navigation +[example] +==== +[source] +---- +land <= +stratum_feature_template_component <= +laminate_component +laminate_component.invalid_attribute -> +product_definition +---- + +Validation errors: + +* Attribute 'invalid_attribute' does not exist on entity 'laminate_component' +* Navigation cannot proceed +* Path is broken + +This path would fail attribute existence validation. +==== + +==== Constraint validation failure + +This example shows a constraint that cannot be validated. + +.Invalid constraint syntax +[example] +==== +[source] +---- +product_definition <- +product_definition_relationship.related_product_definition +product_definition_relationship +{product_definition_relationship +product_definition_relationship.invalid_attribute = 'value'} +---- + +Validation errors: + +* Attribute 'invalid_attribute' does not exist on 'product_definition_relationship' +* Constraint cannot be evaluated +* Path may proceed but constraint is invalid + +This path would generate a constraint validation warning. +==== + +==== Type mismatch in navigation + +This example shows a type mismatch error. + +.Type incompatibility +[example] +==== +[source] +---- +shape_aspect +shape_aspect.of_shape -> +product_definition +---- + +Validation errors: + +* Attribute 'of_shape' has type 'product_definition_shape' +* Expected target is 'product_definition_shape', not 'product_definition' +* Type mismatch in navigation + +This path would fail type compatibility validation. +==== + +[[examples-complex-patterns]] +=== Complex combined patterns + +==== General + +These examples demonstrate combinations of multiple navigation patterns in a single reference path. + +==== Multi-constraint round-trip with alternatives + +This hypothetical example combines multiple advanced patterns. + +.Complex combined navigation +[example] +==== +[source] +---- +specialized_component <= +[base_component_type_a <= +component_definition] +[base_component_type_b <= +alternate_component_definition] +{component_definition +component_definition.description = 'specialized'} +component_definition <= +product_definition <- +product_definition_relationship.related_product_definition +product_definition_relationship +{product_definition_relationship +product_definition_relationship.name = 'usage'} +product_definition_relationship.relating_product_definition -> +{product_definition +product_definition.description = 'template'} +product_definition => +template_definition => +specialized_template +---- + +This path demonstrates: + +* Alternative paths for initial navigation +* Constraints on both source and target entities +* Round-trip through relationship +* Multiple constraint validations +* Combined use of all major operators + +Such complex paths require careful validation at each step. +==== + +[[examples-summary]] +=== Summary of example patterns + +The examples in this annex demonstrate: + +. Simple subtype and supertype chains establishing entity hierarchies +. Round-trip navigation through forward and inverse attribute references +. Constrained paths validating attribute values at specific points +. Alternative paths providing multiple valid navigation routes +. Reference relationship patterns establishing named entity connections +. Shape aspect navigation through feature and property hierarchies +. Template reference patterns connecting physical components to abstract definitions +. Complex combined patterns using multiple operators and constraints + +Each pattern serves specific mapping requirements in the ISO 10303 modular architecture, enabling precise specification of how ARM entities and attributes correspond to MIM entity instances and values. diff --git a/sources/express-mapping/sections/az-bibliography.adoc b/sources/express-mapping/sections/az-bibliography.adoc new file mode 100644 index 0000000..8328ea8 --- /dev/null +++ b/sources/express-mapping/sections/az-bibliography.adoc @@ -0,0 +1,4 @@ +[appendix,obligation=informative] +== Bibliography + +* [[[ISO10303-2,ISO 10303-2]]]