From 5b0b4952b60e486fa04aeb68a57fb0d95c361bcc Mon Sep 17 00:00:00 2001 From: TRThurman Date: Sat, 14 Feb 2026 08:46:48 -0600 Subject: [PATCH] Add EXPRESS links and YAML serialization to ELF 5006 spec EBNF grammar: - Add express_link production for <> syntax - Remove source_decl from entity_mapping and attribute_mapping - Update entity_mapping to accept express_link for entity name - Update aim_element_decl and ASSERTION_TO to accept express_link Specification (04-spec.adoc): - Add new EXPRESS link section documenting the cross-reference syntax - Remove source declaration section (redundant with EXPRESS links) - Update entity mapping, AIM element, and attribute mapping sections - Update all examples to use EXPRESS links Validation rules (05-validation.adoc): - Add EXPRESS link validation rules - Remove source validation rule - Update entity and attribute mapping validation for EXPRESS links Examples and use cases: - Replace Product example with Activity module (real-world EXPRESS links) - Update all examples to use EXPRESS links, remove SOURCE declarations New annex (ab-yaml-serialization.adoc): - Define YAML serialization format for mapping.yaml files - Document entity mapping, attribute mapping, and reference path fields - Specify EXPRESS link format in YAML values - Correspondence table between EBNF constructs and YAML keys - Complete Activity module example in YAML format Closes #9 --- sources/document.adoc | 2 + sources/resources/express-q.ebnf | 22 +- sources/sections/04-spec.adoc | 170 ++++++++---- sources/sections/05-validation.adoc | 22 +- sources/sections/07-use-cases.adoc | 107 +++++--- sources/sections/aa-example.adoc | 181 +++++++------ sources/sections/ab-yaml-serialization.adoc | 275 ++++++++++++++++++++ 7 files changed, 586 insertions(+), 193 deletions(-) create mode 100644 sources/sections/ab-yaml-serialization.adoc diff --git a/sources/document.adoc b/sources/document.adoc index 77fd037..c0b5df1 100644 --- a/sources/document.adoc +++ b/sources/document.adoc @@ -48,4 +48,6 @@ include::sections/08-summary.adoc[] include::sections/aa-example.adoc[] +include::sections/ab-yaml-serialization.adoc[] + include::sections/az-bibliography.adoc[] diff --git a/sources/resources/express-q.ebnf b/sources/resources/express-q.ebnf index ba39294..fbd6711 100644 --- a/sources/resources/express-q.ebnf +++ b/sources/resources/express-q.ebnf @@ -1,9 +1,8 @@ express_q_file = { entity_mapping } ; -entity_mapping = "ENTITY_MAPPING" entity_name ";" newline +entity_mapping = "ENTITY_MAPPING" entity_ref ";" newline [ extensible_decl ] [ aim_element_decl ] - [ source_decl ] [ express_ref_decl ] [ refpath_decl ] [ alt_map_decl ] @@ -12,9 +11,7 @@ entity_mapping = "ENTITY_MAPPING" entity_name ";" newline extensible_decl = "EXTENSIBLE" ":" boolean ";" newline ; -aim_element_decl = "AIM_ELEMENT" ":" string ";" newline ; - -source_decl = "SOURCE" ":" string ";" newline ; +aim_element_decl = "AIM_ELEMENT" ":" ( express_link | string ) ";" newline ; express_ref_decl = "EXPRESS_REF" ":" "[" [ string { "," string } ] "]" ";" newline ; @@ -28,7 +25,7 @@ refpath_line = [ indentation ] reference_expression newline ; reference_expression = entity_reference [ relationship { relationship } ] ; -relationship = path_relation | supertype_relation | subtype_relation | +relationship = path_relation | supertype_relation | subtype_relation | select_extension | constraint ; entity_reference = identifier ; @@ -50,17 +47,26 @@ indentation = ? one or more spaces or tabs ? ; alt_map_decl = "ALT_MAP" ":" "[" [ string { "," string } ] "]" ";" newline ; attribute_mapping = "ATTRIBUTE_MAPPING" attribute_name ";" newline - "ASSERTION_TO" ":" string ";" newline + "ASSERTION_TO" ":" ( express_link | string ) ";" newline [ aim_element_decl ] - [ source_decl ] [ express_ref_decl ] [ refpath_decl ] "END_ATTRIBUTE_MAPPING" ";" newline ; +entity_ref = express_link | entity_name ; + entity_name = identifier ; attribute_name = identifier ; +express_link = "<>" ; + +schema_name = identifier ; + +element_name = identifier ; + +display_name = identifier ; + identifier = letter { letter | digit | "_" } ; boolean = "TRUE" | "FALSE" ; diff --git a/sources/sections/04-spec.adoc b/sources/sections/04-spec.adoc index 5cfde13..0306934 100644 --- a/sources/sections/04-spec.adoc +++ b/sources/sections/04-spec.adoc @@ -10,9 +10,13 @@ introduces new constructs specific to querying and mapping. An EXPRESS-Q file typically consists of one or more entity mappings, each of which defines how an ARM entity and its attributes correspond to MIM elements. These mappings can include various declarations such as extensibility, AIM -elements, sources, EXPRESS references, reference paths, and alternative +elements, EXPRESS references, reference paths, and alternative mappings. +Entity names, AIM element names, and assertion targets use EXPRESS links to +identify both the schema and element, enabling cross-document reference +resolution in published documentation. + === EBNF grammar The following EBNF (Extended Backus-Naur Form) grammar defines the syntax of @@ -32,14 +36,40 @@ of relationships between entities and constraints, and various declarations. This section describes the meaning and usage of each major construct in EXPRESS-Q. +==== EXPRESS link + +[source,ebnf] +---- +express_link = "<>" ; +---- + +An EXPRESS link is a cross-reference that identifies an element within a +specific EXPRESS schema. It encodes the schema name, element name, and a +display name used for rendering. + +The schema origin of a referenced element is derived from the EXPRESS link, +eliminating the need for a separate source declaration. + +Usage:: +* Use in entity mapping names to identify the ARM entity and its schema. +* Use in AIM_ELEMENT declarations to identify the MIM entity and its schema. +* Use in ASSERTION_TO declarations to identify the target entity and its schema. +* The `display_name` is used for rendering in published documentation. + +[example] +---- +<> +<> +<> +---- + ==== Entity mapping [source,ebnf] ---- -entity_mapping = "ENTITY_MAPPING" entity_name ";" newline +entity_mapping = "ENTITY_MAPPING" entity_ref ";" newline [ extensible_decl ] [ aim_element_decl ] - [ source_decl ] [ express_ref_decl ] [ refpath_decl ] [ alt_map_decl ] @@ -49,26 +79,33 @@ entity_mapping = "ENTITY_MAPPING" entity_name ";" newline An entity mapping defines how an ARM entity corresponds to one or more MIM entities or constructs. It encapsulates all the information needed to map a single ARM entity to its MIM counterpart(s). +The entity name shall be an EXPRESS link identifying the ARM entity and its +schema, or a plain entity name for backward compatibility. + Usage:: -* Begin with "ENTITY_MAPPING" followed by the ARM entity name. -* Include optional declarations for extensibility, AIM element, source, EXPRESS references, reference path, and alternative mappings. +* Begin with "ENTITY_MAPPING" followed by the ARM entity reference (EXPRESS link or plain name). +* Include optional declarations for extensibility, AIM element, EXPRESS references, reference path, and alternative mappings. * Include attribute mappings for the entity's attributes. * End with "END_ENTITY_MAPPING". [example] ---- -ENTITY_MAPPING Product; +ENTITY_MAPPING <>; EXTENSIBLE: FALSE; -AIM_ELEMENT: "product"; -SOURCE: "ISO 10303-41"; -EXPRESS_REF: ["product_definition_schema"]; +AIM_ELEMENT: "<>"; +EXPRESS_REF: ["action_schema"]; REFPATH: { - product <= product_definition_formation - product_definition_formation.of_product -> product + executed_action <= action +}; +ATTRIBUTE_MAPPING chosen_method; +ASSERTION_TO: "<>"; +AIM_ELEMENT: "PATH"; +REFPATH: { + executed_action + executed_action <= action + action.chosen_method -> action_method + action_method }; -ATTRIBUTE_MAPPING id; -ASSERTION_TO: "id"; -AIM_ELEMENT: "product.id"; END_ATTRIBUTE_MAPPING; END_ENTITY_MAPPING; ---- @@ -88,7 +125,7 @@ Usage:: [example] ---- -ENTITY_MAPPING ProductCategory; +ENTITY_MAPPING <>; EXTENSIBLE: TRUE; ... END_ENTITY_MAPPING; @@ -98,42 +135,55 @@ END_ENTITY_MAPPING; [source,ebnf] ---- -aim_element_decl = "AIM_ELEMENT" ":" string ";" newline ; +aim_element_decl = "AIM_ELEMENT" ":" ( express_link | string ) ";" newline ; ---- -The AIM element declaration specifies the corresponding AIM (MIM) element for the ARM entity, providing a direct link between the ARM and MIM schemas. +The AIM element declaration specifies the corresponding AIM (MIM) element for +the ARM entity, providing a direct link between the ARM and MIM schemas. + +When the AIM element is an entity or type defined in an EXPRESS schema, the +value shall be an EXPRESS link. When the AIM element is a keyword (such as +`PATH`, `IDENTICAL MAPPING`, or `NO MAPPING EXTENSION PROVIDED`) or a dotted +attribute path (such as `action.name`), the value shall be a plain string. Usage:: -* Specify the AIM element name as a string. +* Specify the AIM element as an EXPRESS link for entity references. +* Specify the AIM element as a plain string for keywords and attribute paths. [example] +.Entity-level AIM element with EXPRESS link ---- -ENTITY_MAPPING Product; -AIM_ELEMENT: "product"; +ENTITY_MAPPING <>; +AIM_ELEMENT: "<>"; ... END_ENTITY_MAPPING; ---- -==== Source declaration - -[source,ebnf] +[example] +.Attribute-level AIM element with plain string ---- -source_decl = "SOURCE" ":" string ";" newline ; +ATTRIBUTE_MAPPING name; +ASSERTION_TO: "name"; +AIM_ELEMENT: "action.name"; +END_ATTRIBUTE_MAPPING; ---- -The source declaration indicates the source (typically an ISO standard) of the MIM element, which is crucial for traceability and maintaining consistency with relevant standards. - -Usage:: -* Specify the source as a string, typically an ISO standard number. - [example] +.Attribute-level AIM element with PATH keyword ---- -ENTITY_MAPPING Product; -SOURCE: "ISO 10303-41"; -... -END_ENTITY_MAPPING; +ATTRIBUTE_MAPPING chosen_method; +ASSERTION_TO: "<>"; +AIM_ELEMENT: "PATH"; +REFPATH: { + executed_action + executed_action <= action + action.chosen_method -> action_method + action_method +}; +END_ATTRIBUTE_MAPPING; ---- + ==== EXPRESS reference declaration [source,ebnf] @@ -149,8 +199,8 @@ Usage:: [example] ---- -ENTITY_MAPPING Product; -EXPRESS_REF: ["product_definition_schema", "management_resources_schema"]; +ENTITY_MAPPING <>; +EXPRESS_REF: ["action_schema", "management_resources_schema"]; ... END_ENTITY_MAPPING; ---- @@ -182,12 +232,10 @@ Usage:: [example] ---- -ENTITY_MAPPING Product; +ENTITY_MAPPING <>; REFPATH: { - product <= product_definition_formation - product_definition_formation.of_product -> product - {product.name -> product.name - product.description -> product.description} + executed_action <= action + action.chosen_method -> action_method }; ... END_ENTITY_MAPPING; @@ -292,7 +340,7 @@ REFPATH: { REFPATH: { shape_representation <= representation {representation.items[i] -> representation_item - representation_item => + representation_item => (geometric_representation_item [geometric_representation_item.dim = 3] | mapped_item) @@ -364,9 +412,8 @@ END_ENTITY_MAPPING; [source,ebnf] ---- attribute_mapping = "ATTRIBUTE_MAPPING" attribute_name ";" newline - "ASSERTION_TO" ":" string ";" newline + "ASSERTION_TO" ":" ( express_link | string ) ";" newline [ aim_element_decl ] - [ source_decl ] [ express_ref_decl ] [ refpath_decl ] "END_ATTRIBUTE_MAPPING" ";" newline ; @@ -374,31 +421,42 @@ attribute_mapping = "ATTRIBUTE_MAPPING" attribute_name ";" newline An attribute mapping defines how an individual attribute of an ARM entity corresponds to elements in the MIM schema. +The ASSERTION_TO value shall be an EXPRESS link when the attribute refers to an +entity data type or a SELECT type, and a plain string otherwise. + Usage:: * Begin with "ATTRIBUTE_MAPPING" followed by the attribute name. -* Specify the ASSERTION_TO value, which indicates the corresponding MIM element or type. -* Optionally include AIM_ELEMENT, SOURCE, EXPRESS_REF, and REFPATH declarations. +* Specify the ASSERTION_TO value as an EXPRESS link or plain string. +* Optionally include AIM_ELEMENT, EXPRESS_REF, and REFPATH declarations. * End with "END_ATTRIBUTE_MAPPING". [example] +.Attribute mapping with EXPRESS link assertion ---- -ENTITY_MAPPING Product; -ATTRIBUTE_MAPPING id; -ASSERTION_TO: "id"; -AIM_ELEMENT: "product.id"; +ENTITY_MAPPING <>; +ATTRIBUTE_MAPPING chosen_method; +ASSERTION_TO: "<>"; +AIM_ELEMENT: "PATH"; REFPATH: { - product.id -> id + executed_action + executed_action <= action + action.chosen_method -> action_method + action_method }; END_ATTRIBUTE_MAPPING; +END_ENTITY_MAPPING; +---- +[example] +.Attribute mapping with plain string AIM element +---- ATTRIBUTE_MAPPING name; -ASSERTION_TO: "label"; -AIM_ELEMENT: "product.name"; -SOURCE: "ISO 10303-41"; -EXPRESS_REF: ["product_definition_schema"]; +ASSERTION_TO: "name"; +AIM_ELEMENT: "action.name"; REFPATH: { - product.name -> name + executed_action + executed_action <= action + action.name }; END_ATTRIBUTE_MAPPING; -END_ENTITY_MAPPING; ---- diff --git a/sources/sections/05-validation.adoc b/sources/sections/05-validation.adoc index f5130cb..c040dc0 100644 --- a/sources/sections/05-validation.adoc +++ b/sources/sections/05-validation.adoc @@ -4,20 +4,26 @@ Validation of EXPRESS-Q files is crucial to ensure the correctness and consistency of mappings between ARM and MIM schemas. The following rules should be applied when validating EXPRESS-Q files. +=== EXPRESS link validation + +1. Each EXPRESS link shall conform to the syntax `<>`. +2. The `schema_name` shall identify a valid EXPRESS schema accessible to the mapping. +3. The `element_name` shall identify an entity, type, or attribute defined in or imported into the referenced schema. +4. The `display_name` shall match the `element_name`. + === Entity mapping validation -1. Each ENTITY_MAPPING shall correspond to an entity defined in the ARM schema. -2. The AIM_ELEMENT specified shall exist in the MIM schema. -3. The SOURCE referenced shall be a valid ISO standard or other recognized source. -4. All EXPRESS_REF entries shall refer to valid EXPRESS schemas. -5. The REFPATH shall form a valid path from the ARM entity to the specified AIM_ELEMENT. -6. If ALT_MAP is specified, all alternative mappings shall be valid MIM entities. +1. Each ENTITY_MAPPING shall correspond to an entity or type defined in the ARM schema. When the entity name is an EXPRESS link, the referenced entity shall exist in the referenced ARM schema. +2. The AIM_ELEMENT specified shall exist in the MIM schema or be a recognized keyword (`PATH`, `IDENTICAL MAPPING`, `NO MAPPING EXTENSION PROVIDED`, `/SUPERTYPE(...)/ `, `/SUBTYPE(...)/`). When the AIM element is an EXPRESS link, the referenced entity shall exist in the referenced MIM or resource schema. +3. All EXPRESS_REF entries shall refer to valid EXPRESS schemas. +4. The REFPATH shall form a valid path from the ARM entity to the specified AIM_ELEMENT. +5. If ALT_MAP is specified, all alternative mappings shall be valid MIM entities. === Attribute mapping validation 1. Each ATTRIBUTE_MAPPING shall correspond to an attribute of the ARM entity being mapped. -2. The ASSERTION_TO value shall be a valid type or entity in the MIM schema. -3. If specified, the AIM_ELEMENT shall exist in the MIM schema. +2. The ASSERTION_TO value shall be a valid type or entity in the ARM or MIM schema, as appropriate. When the value is an EXPRESS link, the referenced entity shall exist in the referenced schema. +3. If specified, the AIM_ELEMENT shall exist in the MIM schema or be a recognized keyword or dotted attribute path. 4. The REFPATH for an attribute shall form a valid path from the ARM attribute to the specified MIM element. === Reference path validation diff --git a/sources/sections/07-use-cases.adoc b/sources/sections/07-use-cases.adoc index 45fe0d5..a77f568 100644 --- a/sources/sections/07-use-cases.adoc +++ b/sources/sections/07-use-cases.adoc @@ -5,83 +5,105 @@ This section provides examples of how EXPRESS-Q can be used in various scenarios related to STEP application protocols. -=== Use case 1: Mapping a complex product structure +=== Use case 1: Mapping a module with cross-schema references -In this example, we'll demonstrate how EXPRESS-Q can be used to map a complex product structure from an ARM schema to a MIM schema. +In this example, we demonstrate how EXPRESS-Q maps the Activity module, where +the ARM entity `Activity` references `Activity_method` from a different module. +EXPRESS links enable cross-document reference resolution in the published +documentation. [example] ---- -ENTITY_MAPPING Product; -AIM_ELEMENT: "product"; -SOURCE: "ISO 10303-41"; +ENTITY_MAPPING <>; +AIM_ELEMENT: "<>"; +EXPRESS_REF: ["action_schema"]; REFPATH: { - product <= product_definition_formation - product_definition_formation.of_product -> product + executed_action <= action }; ATTRIBUTE_MAPPING id; ASSERTION_TO: "id"; -AIM_ELEMENT: "product.id"; +AIM_ELEMENT: "id_attribute.attribute_value"; +REFPATH: { + executed_action + executed_action <= action + action <- id_attribute.identified_item + id_attribute.attribute_value +}; END_ATTRIBUTE_MAPPING; ATTRIBUTE_MAPPING name; -ASSERTION_TO: "label"; -AIM_ELEMENT: "product.name"; +ASSERTION_TO: "name"; +AIM_ELEMENT: "action.name"; +REFPATH: { + executed_action + executed_action <= action + action.name +}; END_ATTRIBUTE_MAPPING; ATTRIBUTE_MAPPING description; -ASSERTION_TO: "text"; -AIM_ELEMENT: "product.description"; +ASSERTION_TO: "description"; +AIM_ELEMENT: "action.description"; +REFPATH: { + executed_action + executed_action <= action + action.description +}; END_ATTRIBUTE_MAPPING; -ATTRIBUTE_MAPPING components; -ASSERTION_TO: "SET OF Component"; +ATTRIBUTE_MAPPING chosen_method; +ASSERTION_TO: "<>"; +AIM_ELEMENT: "PATH"; REFPATH: { - product <- product_definition_formation - product_definition_formation <- product_definition - product_definition <- product_definition_relationship.relating_product_definition - product_definition_relationship -> - product_definition_relationship.related_product_definition - product_definition_relationship.related_product_definition -> product_definition - product_definition -> product_definition_formation - product_definition_formation -> product + executed_action + executed_action <= action + action.chosen_method -> action_method + action_method }; END_ATTRIBUTE_MAPPING; END_ENTITY_MAPPING; -ENTITY_MAPPING Component; -AIM_ELEMENT: "product"; -SOURCE: "ISO 10303-41"; -REFPATH: { - product <= product_definition_formation - product_definition_formation.of_product -> product -}; +ENTITY_MAPPING <>; +AIM_ELEMENT: "<>"; -ATTRIBUTE_MAPPING id; -ASSERTION_TO: "id"; -AIM_ELEMENT: "product.id"; +ATTRIBUTE_MAPPING name; +ASSERTION_TO: "name"; +AIM_ELEMENT: "action_relationship.name"; END_ATTRIBUTE_MAPPING; -ATTRIBUTE_MAPPING name; -ASSERTION_TO: "label"; -AIM_ELEMENT: "product.name"; +ATTRIBUTE_MAPPING description; +ASSERTION_TO: "description"; +AIM_ELEMENT: "action_relationship.description"; +END_ATTRIBUTE_MAPPING; + +ATTRIBUTE_MAPPING related_activity; +ASSERTION_TO: "<>"; +AIM_ELEMENT: "PATH"; +REFPATH: { + action_relationship + action_relationship.related_action -> action + action => executed_action +}; END_ATTRIBUTE_MAPPING; -ATTRIBUTE_MAPPING quantity; -ASSERTION_TO: "measure_with_unit"; +ATTRIBUTE_MAPPING relating_activity; +ASSERTION_TO: "<>"; +AIM_ELEMENT: "PATH"; REFPATH: { - product <- product_definition_formation - product_definition_formation <- product_definition - product_definition <- product_definition_relationship - product_definition_relationship.related_product_definition_quantity -> measure_with_unit + action_relationship + action_relationship.relating_action -> action + action => executed_action }; END_ATTRIBUTE_MAPPING; END_ENTITY_MAPPING; ---- -This example demonstrates how a product with multiple components can be mapped from an ARM schema to a MIM schema using EXPRESS-Q. It shows the use of complex reference paths to navigate relationships between entities in the MIM schema. +This example demonstrates how EXPRESS links in the entity name, AIM element, and +ASSERTION_TO fields enable the published document to generate cross-references +to other modules and resource schemas. === Use case 2: Mapping with alternative representations @@ -91,7 +113,6 @@ This example shows how EXPRESS-Q can handle cases where an ARM entity might be m ---- ENTITY_MAPPING GeometricRepresentation; ALT_MAP: ["shape_representation", "tessellated_shape_representation"]; -SOURCE: "ISO 10303-42"; REFPATH: { (shape_representation <= representation diff --git a/sources/sections/aa-example.adoc b/sources/sections/aa-example.adoc index e964c36..45583a7 100644 --- a/sources/sections/aa-example.adoc +++ b/sources/sections/aa-example.adoc @@ -1,141 +1,166 @@ [appendix,obligation=informative] == Complete EXPRESS-Q file example -This annex provides a complete example of an EXPRESS-Q file, demonstrating -various features of the language in a cohesive context. +This annex provides a complete example of an EXPRESS-Q file for the Activity +module, demonstrating EXPRESS links for cross-schema references. [source] ---- --- Example EXPRESS-Q file for a simplified product data model +-- EXPRESS-Q file for the Activity module (ISO 10303-1047) -ENTITY_MAPPING Product; +ENTITY_MAPPING <>; EXTENSIBLE: FALSE; -AIM_ELEMENT: "product"; -SOURCE: "ISO 10303-41"; -EXPRESS_REF: ["product_definition_schema"]; +AIM_ELEMENT: "<>"; +EXPRESS_REF: ["action_schema", "basic_attribute_schema"]; REFPATH: { - product <= product_definition_formation - product_definition_formation.of_product -> product + executed_action <= action }; ATTRIBUTE_MAPPING id; -ASSERTION_TO: "identifier"; -AIM_ELEMENT: "product.id"; +ASSERTION_TO: "id"; +AIM_ELEMENT: "id_attribute.attribute_value"; REFPATH: { - product.id -> id + executed_action + executed_action <= action + action <- id_attribute.identified_item + id_attribute.attribute_value }; END_ATTRIBUTE_MAPPING; ATTRIBUTE_MAPPING name; -ASSERTION_TO: "label"; -AIM_ELEMENT: "product.name"; +ASSERTION_TO: "name"; +AIM_ELEMENT: "action.name"; REFPATH: { - product.name -> name + executed_action + executed_action <= action + action.name }; END_ATTRIBUTE_MAPPING; ATTRIBUTE_MAPPING description; -ASSERTION_TO: "text"; -AIM_ELEMENT: "product.description"; +ASSERTION_TO: "description"; +AIM_ELEMENT: "action.description"; REFPATH: { - product.description -> description + executed_action + executed_action <= action + action.description }; END_ATTRIBUTE_MAPPING; -ATTRIBUTE_MAPPING category; -ASSERTION_TO: "product_category"; +ATTRIBUTE_MAPPING chosen_method; +ASSERTION_TO: "<>"; +AIM_ELEMENT: "PATH"; REFPATH: { - product <- product_category_assignment.products[i] - product_category_assignment -> product_category_assignment.assigned_category - product_category_assignment.assigned_category -> product_category + executed_action + executed_action <= action + action.chosen_method -> action_method + action_method }; END_ATTRIBUTE_MAPPING; END_ENTITY_MAPPING; -ENTITY_MAPPING Assembly; +ENTITY_MAPPING <>; EXTENSIBLE: FALSE; -AIM_ELEMENT: "product"; -SOURCE: "ISO 10303-44"; -EXPRESS_REF: ["product_structure_schema"]; +AIM_ELEMENT: "<>"; + +ATTRIBUTE_MAPPING name; +ASSERTION_TO: "name"; +AIM_ELEMENT: "action_relationship.name"; +END_ATTRIBUTE_MAPPING; + +ATTRIBUTE_MAPPING description; +ASSERTION_TO: "description"; +AIM_ELEMENT: "action_relationship.description"; +END_ATTRIBUTE_MAPPING; + +ATTRIBUTE_MAPPING related_activity; +ASSERTION_TO: "<>"; +AIM_ELEMENT: "PATH"; REFPATH: { - product <= product_definition_formation - product_definition_formation.of_product -> product - [product <- product_definition_formation - product_definition_formation <- product_definition - product_definition <- assembly_component_usage.relating_product_definition] + action_relationship + action_relationship.related_action -> action + action => executed_action }; +END_ATTRIBUTE_MAPPING; -ATTRIBUTE_MAPPING components; -ASSERTION_TO: "SET OF AssemblyComponent"; +ATTRIBUTE_MAPPING relating_activity; +ASSERTION_TO: "<>"; +AIM_ELEMENT: "PATH"; REFPATH: { - product <- product_definition_formation - product_definition_formation <- product_definition - product_definition <- assembly_component_usage.relating_product_definition - assembly_component_usage -> assembly_component_usage.related_product_definition - assembly_component_usage.related_product_definition -> product_definition - product_definition -> product_definition_formation - product_definition_formation -> product + action_relationship + action_relationship.relating_action -> action + action => executed_action }; END_ATTRIBUTE_MAPPING; END_ENTITY_MAPPING; -ENTITY_MAPPING AssemblyComponent; +ENTITY_MAPPING <>; EXTENSIBLE: FALSE; -AIM_ELEMENT: "product"; -SOURCE: "ISO 10303-44"; -EXPRESS_REF: ["product_structure_schema"]; -REFPATH: { - product <= product_definition_formation - product_definition_formation.of_product -> product -}; +AIM_ELEMENT: "<>"; -ATTRIBUTE_MAPPING quantity; -ASSERTION_TO: "measure_with_unit"; +ATTRIBUTE_MAPPING assigned_activity; +ASSERTION_TO: "<>"; +AIM_ELEMENT: "PATH"; REFPATH: { - product <- product_definition_formation - product_definition_formation <- product_definition - product_definition <- assembly_component_usage - assembly_component_usage.quantity -> measure_with_unit + action_status + action_status.assigned_action -> executed_action }; END_ATTRIBUTE_MAPPING; +ATTRIBUTE_MAPPING status; +ASSERTION_TO: "status"; +AIM_ELEMENT: "action_status.status"; +END_ATTRIBUTE_MAPPING; + END_ENTITY_MAPPING; -ENTITY_MAPPING GeometricRepresentation; -EXTENSIBLE: TRUE; -ALT_MAP: ["shape_representation", "tessellated_shape_representation"]; -SOURCE: "ISO 10303-42"; -EXPRESS_REF: ["geometric_model_schema"]; +ENTITY_MAPPING <>; +EXTENSIBLE: FALSE; +AIM_ELEMENT: "<>"; +EXPRESS_REF: ["management_resources_schema"]; +ATTRIBUTE_MAPPING assigned_activity; +ASSERTION_TO: "<>"; +AIM_ELEMENT: "PATH"; REFPATH: { - (shape_representation <= representation - [representation.context_of_items->geometric_representation_context]) | - (tessellated_shape_representation <= representation - [representation.context_of_items->geometric_representation_context]) + applied_action_assignment + applied_action_assignment <= action_assignment + action_assignment + action_assignment.assigned_action -> action + action => executed_action }; +END_ATTRIBUTE_MAPPING; ATTRIBUTE_MAPPING items; -ASSERTION_TO: "SET OF geometric_representation_item"; +ASSERTION_TO: "<>"; +AIM_ELEMENT: "PATH"; REFPATH: { - representation.items[i] -> geometric_representation_item + applied_action_assignment + applied_action_assignment.items[i] -> action_items +}; +END_ATTRIBUTE_MAPPING; + +ATTRIBUTE_MAPPING role; +ASSERTION_TO: "role"; +AIM_ELEMENT: "object_role.name"; +REFPATH: { + applied_action_assignment + applied_action_assignment <= action_assignment + action_assignment.role -> object_role + object_role.name }; END_ATTRIBUTE_MAPPING; END_ENTITY_MAPPING; ---- -This example demonstrates a simplified product data model, including mappings -for products, assemblies, assembly components, and geometric representations. It -showcases various features of EXPRESS-Q, including: - -- Entity and attribute mappings -- Reference paths with complex relationships -- Alternative mappings -- Constraints within reference paths -- Use of SELECT types (implied by the EXTENSIBLE: TRUE; in GeometricRepresentation) +This example demonstrates the complete mapping for the Activity module, +including: -This example is not exhaustive but provides a realistic scenario that -illustrates how EXPRESS-Q can be used to define mappings between ARM and MIM -schemas in a STEP application protocol context. +- EXPRESS links for entity names (`<>`) +- EXPRESS links for AIM elements (`<>`) +- EXPRESS links for cross-module assertions (`<>`) +- Plain string AIM elements for attribute paths (`action.name`) and keywords (`PATH`) +- Reference paths with subtype, supertype, and attribute relationships diff --git a/sources/sections/ab-yaml-serialization.adoc b/sources/sections/ab-yaml-serialization.adoc new file mode 100644 index 0000000..67f0aae --- /dev/null +++ b/sources/sections/ab-yaml-serialization.adoc @@ -0,0 +1,275 @@ +[appendix,obligation=normative] +== YAML serialization + +=== General + +This annex defines the YAML serialization format for EXPRESS-Q mapping +specifications. Each application module's mapping specification is stored as a +YAML file named `mapping.yaml` in the module's schema directory. + +The YAML serialization provides a machine-readable representation of the +EXPRESS-Q constructs defined in this specification, suitable for automated +processing, validation, and document generation. + +=== File structure + +A mapping YAML file has a single top-level key `ae` (application elements) +containing an ordered list of entity mappings. + +[source,yaml] +---- +--- +ae: +- entity: ... + aimelt: ... + aa: + - attribute: ... + ... +---- + +=== Schema + +The following describes each field in the YAML serialization. + +==== Entity mapping + +Each entry in the `ae` list represents an entity mapping and contains the +following fields: + +`entity`:: (required) The ARM entity being mapped. The value shall be an +EXPRESS link identifying the ARM schema and entity: +`<>`. + +For backward compatibility, a plain entity name is also accepted. + +`aimelt`:: (required) The corresponding MIM element. The value shall be one of: + +* An EXPRESS link for entity references: +`<>` +* A plain string for keywords: `PATH`, `IDENTICAL MAPPING`, +`NO MAPPING EXTENSION PROVIDED` +* A plain string for `/SUPERTYPE(...)/`, `/SUBTYPE(...)/`, or +`/MAPPING_OF(...)/` constructs +* A plain string for dotted attribute paths: `entity.attribute` +* A parenthesized or bracketed list of the above for multiple MIM elements + +`extensible`:: (optional) Boolean indicating whether the mapping is extensible. + +`alt_map`:: (optional) List of alternative MIM entity names. + +`original_module`:: (optional) Name of the module from which this mapping +originates (for inherited mappings). + +`description`:: (optional) Additional descriptive text. + +`aa`:: (optional) List of attribute mappings for this entity. + +==== Attribute mapping + +Each entry in the `aa` list represents an attribute mapping and contains the +following fields: + +`attribute`:: (required) The ARM attribute name being mapped. + +`aimelt`:: (optional) The corresponding MIM element. At the attribute level, +the value is a plain string (not an EXPRESS link). Typical values include: + +* A dotted attribute path: `action.name` +* The keyword `PATH` (when assertion_to is present) +* The keyword `IDENTICAL MAPPING` + +`assertion_to`:: (optional) The target entity or type that this attribute +refers to. When present, the value shall be an EXPRESS link: +`<>`. + +The special value `*` indicates any type. + +For backward compatibility, a plain entity name is also accepted. + +`refpath`:: (optional) The reference path specifying the detailed mapping +between ARM and MIM elements. + +==== Reference path + +The `refpath` field contains an object with a single key: + +`content`:: (required) A multi-line string containing the reference path +expression using the syntax defined in <>. +Lines are separated by newline characters. The YAML block scalar `|-` +is used to preserve line breaks and strip the trailing newline. + +[source,yaml] +---- +refpath: + content: |- + executed_action + executed_action <= action + action.chosen_method -> action_method + action_method +---- + +=== EXPRESS link format + +EXPRESS links in YAML values use the following syntax: + +[source] +---- +<> +---- + +Where: + +`schema_name`:: The name of the EXPRESS schema containing the element. +`element_name`:: The name of the entity, type, or function within the schema. +`display_name`:: The name displayed in rendered documentation (shall match +`element_name`). + +The schema name encodes the origin of the referenced element, eliminating the +need for a separate `source` field. + +=== Correspondence to EBNF constructs + +The following table shows the correspondence between EBNF constructs and YAML +keys: + +[cols="2,2,3",options="header"] +|=== +| EBNF construct | YAML key | Notes + +| `ENTITY_MAPPING entity_ref` +| `ae[].entity` +| EXPRESS link or plain name + +| `aim_element_decl` +| `ae[].aimelt` or `ae[].aa[].aimelt` +| Entity-level: EXPRESS link or string; attribute-level: plain string + +| `ASSERTION_TO` +| `ae[].aa[].assertion_to` +| EXPRESS link or plain string + +| `extensible_decl` +| `ae[].extensible` +| Boolean + +| `alt_map_decl` +| `ae[].alt_map` +| List of strings + +| `refpath_decl` +| `ae[].aa[].refpath.content` +| Multi-line string + +| `express_ref_decl` +| Not serialized +| Schema references are encoded in EXPRESS links + +| `source_decl` +| Not serialized +| Source is derived from EXPRESS links +|=== + +=== Complete example + +The following shows the complete YAML serialization of the Activity module +mapping specification: + +[source,yaml] +---- +--- +ae: +- entity: <> + aimelt: <> + aa: + - attribute: name + aimelt: action.name + refpath: + content: |- + executed_action + executed_action <= action + action.name + - attribute: description + aimelt: action.description + refpath: + content: |- + executed_action + executed_action <= action + action.description + - attribute: chosen_method + assertion_to: <> + aimelt: PATH + refpath: + content: |- + executed_action + executed_action <= action + action.chosen_method -> action_method + action_method + - attribute: id + aimelt: id_attribute.attribute_value + refpath: + content: |- + executed_action + executed_action <= action + action <- id_attribute.identified_item + id_attribute.attribute_value +- entity: <> + aimelt: <> + aa: + - attribute: description + aimelt: action_relationship.description + - attribute: name + aimelt: action_relationship.name + - attribute: related_activity + assertion_to: <> + aimelt: PATH + refpath: + content: |- + action_relationship + action_relationship.related_action -> action + action => executed_action + - attribute: relating_activity + assertion_to: <> + aimelt: PATH + refpath: + content: |- + action_relationship + action_relationship.relating_action -> action + action => executed_action +- entity: <> + aimelt: <> + aa: + - attribute: assigned_activity + assertion_to: <> + aimelt: PATH + refpath: + content: |- + action_status + action_status.assigned_action -> executed_action + - attribute: status + aimelt: action_status.status +- entity: <> + aimelt: <> + aa: + - attribute: assigned_activity + assertion_to: <> + aimelt: PATH + refpath: + content: |- + applied_action_assignment + applied_action_assignment <= action_assignment + action_assignment + action_assignment.assigned_action -> action + action => executed_action + - attribute: items + assertion_to: <> + aimelt: PATH + refpath: + content: |- + applied_action_assignment + applied_action_assignment.items[i] -> action_items + - attribute: role + aimelt: object_role.name + refpath: + content: |- + applied_action_assignment + applied_action_assignment <= action_assignment + action_assignment.role -> object_role + object_role.name +----