Skip to content

Add EXPRESS links and YAML serialization annex #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TRThurman merged 1 commit into from
Apr 22, 2026
Merged

Add EXPRESS links and YAML serialization annex #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions sources/document.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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[]
22 changes: 14 additions & 8 deletions sources/resources/express-q.ebnf
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 ]
Expand All @@ -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 ;

Expand All @@ -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 ;
Expand All @@ -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 = "<<express:" schema_name "." element_name "," display_name ">>" ;

schema_name = identifier ;

element_name = identifier ;

display_name = identifier ;

identifier = letter { letter | digit | "_" } ;

boolean = "TRUE" | "FALSE" ;
Expand Down
170 changes: 114 additions & 56 deletions sources/sections/04-spec.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 = "<<express:" schema_name "." element_name "," display_name ">>" ;
----

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]
----
<<express:Activity_arm.Activity,Activity>>
<<express:action_schema.executed_action,executed_action>>
<<express:Activity_method_arm.Activity_method,Activity_method>>
----

==== 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 ]
Expand All @@ -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 <<express:Activity_arm.Activity,Activity>>;
EXTENSIBLE: FALSE;
AIM_ELEMENT: "product";
SOURCE: "ISO 10303-41";
EXPRESS_REF: ["product_definition_schema"];
AIM_ELEMENT: "<<express:action_schema.executed_action,executed_action>>";
EXPRESS_REF: ["action_schema"];
REFPATH: {
product <= product_definition_formation
product_definition_formation.of_product -> product
executed_action <= action
};
ATTRIBUTE_MAPPING chosen_method;
ASSERTION_TO: "<<express:Activity_method_arm.Activity_method,Activity_method>>";
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;
----
Expand All @@ -88,7 +125,7 @@ Usage::

[example]
----
ENTITY_MAPPING ProductCategory;
ENTITY_MAPPING <<express:Activity_arm.activity_item,activity_item>>;
EXTENSIBLE: TRUE;
...
END_ENTITY_MAPPING;
Expand All @@ -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 <<express:Activity_arm.Activity,Activity>>;
AIM_ELEMENT: "<<express:action_schema.executed_action,executed_action>>";
...
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: "<<express:Activity_method_arm.Activity_method,Activity_method>>";
AIM_ELEMENT: "PATH";
REFPATH: {
executed_action
executed_action <= action
action.chosen_method -> action_method
action_method
};
END_ATTRIBUTE_MAPPING;
----


==== EXPRESS reference declaration

[source,ebnf]
Expand All @@ -149,8 +199,8 @@ Usage::

[example]
----
ENTITY_MAPPING Product;
EXPRESS_REF: ["product_definition_schema", "management_resources_schema"];
ENTITY_MAPPING <<express:Activity_arm.Activity,Activity>>;
EXPRESS_REF: ["action_schema", "management_resources_schema"];
...
END_ENTITY_MAPPING;
----
Expand Down Expand Up @@ -182,12 +232,10 @@ Usage::

[example]
----
ENTITY_MAPPING Product;
ENTITY_MAPPING <<express:Activity_arm.Activity,Activity>>;
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;
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -364,41 +412,51 @@ 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 ;
----

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 <<express:Activity_arm.Activity,Activity>>;
ATTRIBUTE_MAPPING chosen_method;
ASSERTION_TO: "<<express:Activity_method_arm.Activity_method,Activity_method>>";
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;
----
22 changes: 14 additions & 8 deletions sources/sections/05-validation.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<<express:schema_name.element_name,display_name>>`.
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
Expand Down
Loading