feat: update content per @TRThurman and make interfaced_items and description more granular

ronaldtse · ronaldtse · commit 6c815a049c34 · 2025-10-15T15:57:40.000+08:00
diff --git a/sources/express-changes/sections/05-schema-change.adoc b/sources/express-changes/sections/05-schema-change.adoc
@@ -3,18 +3,18 @@
 
 === General
 
-The schema change structure captures modifications to the structure and
-semantics of an EXPRESS schema across different editions or versions. It
-captures additions, modifications, and removals of schema elements such as
+The schema change structure is a record of modifications to the structure and
+semantics of an EXPRESS schema across different editions.
+
+It records additions, modifications, and removals of schema elements such as
 entities, types, functions, and rules.
 
 The structure is built on the following constructs:
 
-* Edition changes: Each edition or version of the schema, detailing what
-changed.
+* Edition changes: Changes made to the schema in a specific edition compared to
+the previous edition.
 
-* Item changes: Specific elements that were added, modified, or removed in an
-edition.
+* Item changes: Specific elements that were added, modified, or removed.
 
 Syntax:
 
@@ -30,16 +30,15 @@ editions:
 
 === Edition change
 
-Each edition change represents a specific version of the schema and details
-the changes made in that version.
+Each edition change object details changes between two editions of the schema.
 
 Syntax:
 
 [source,yaml]
 ----
 version: String (required)
 # Version number for this change edition
-description: String (required)
+description: String (optional)
 # Description of changes in this edition
 additions:
   - {item change 1}
@@ -54,40 +53,47 @@ removals:
 
 Fields:
 
-`version`:: The version number (string) (required).
+`version`:: (required) The version number (integer). Must be positive.
 +
 [example]
-`2`, `3.1`, `2024-06`.
+`2`, `3`, `6`.
 
-`description`:: A multi-line string describing the changes made in this edition
-(required). Should provide a comprehensive overview of what changed and why.
+`description`:: (optional) A multi-line string describing the changes made in
+this edition. Should provide a comprehensive overview of what changed and why.
+If not provided, a publication may provide its own boilerplate or summary.
 
-`additions`:: An array of added elements as item changes (optional).
+`additions`:: (optional) An array of added elements as item changes.
 
-`modifications`:: An array of modified elements as item changes (optional).
+`modifications`:: (optional) An array of modified elements as item changes.
 
-`removals`:: An array of removed elements as item changes (optional).
+`removals`:: (optional) An array of removed elements as item changes.
 
 
 
 === Item change
 
 Each item change represents a specific schema element that was added, modified,
-or removed.
+or removed, and when applicable, references to other EXPRESS constructs.
 
 Syntax:
 
 [source,yaml]
 ----
-type: String (required)
 # Type of the EXPRESS construct (e.g., ENTITY, TYPE, FUNCTION)
-name: String (required)
+type: String (required)
 # Name of the EXPRESS construct
+name: String (required)
+# Description of the change
+description: Array (optional)
+- String
+# For USE_FROM or REFERENCE_FROM, list of specific items referenced or used
+interfaced_items: Array (optional)
+- String
 ----
 
 Fields:
 
-`type`:: The type of the EXPRESS construct (string) (required). Allowed values
+`type`:: (required) The type of the EXPRESS construct (string). Allowed values
 are:
 
 `ENTITY`::: Entity definitions
@@ -96,6 +102,59 @@ are:
 `RULE`::: Rule definitions
 `PROCEDURE`::: Procedure definitions
 `CONSTANT`::: Constant definitions
+`REFERENCE_FROM`::: A reference from another schema, with an additional field
+`interfaced_items` listing the specific items referenced when in `additions`.
+When used in `deletions`, no `interfaced_items` is needed.
+`USE_FROM`::: A use from another schema, with an additional field `interfaced_items`
+listing the specific items used when in `additions`. When used in `deletions`, no
+`interfaced_items` is needed.
+
+`name`:: (required) The name of the EXPRESS construct (string).
+
+`description`:: (optional) An array of strings describing the change. Each
+string represents a description for a single change in the named target.
+For instance, if an entity had an attribute removed and a WHERE rule added, the
+description array would have two entries, one for each change.
++
+[example]
+====
+[source,yaml]
+----
+---
+schema: Additive_manufacturing_part_and_build_information_arm
+editions:
+- version: '2'
+  modifications:
+  - type: ENTITY
+    name: Additive_manufacturing_build_direction_element
+    description:
+    - Remove Attribute 'identified_item'
+    - Remove DERIVE 'element_name'
+    - Add WHERE 'WR1'
+    - Figure updated
+----
+====
 
-`name`:: The name of the EXPRESS construct (string) (required).
-
+`interfaced_items`:: (optional) For `USE_FROM` or `REFERENCE_FROM`, an array of
+specific items referenced or used. Not needed when in `deletions`.
++
+[example]
+====
+[source,yaml]
+----
+---
+schema: Document_and_version_identification_mim
+editions:
+- version: '2'
+  deletions:
+  - type: USE_FROM
+    name: Product_identification_mim
+- version: '3'
+  additions:
+  - type: USE_FROM
+    name: product_definition_schema
+    interfaced_items:
+    - product_category
+    - product_related_product_category
+----
+====
diff --git a/sources/express-changes/sections/06-mapping-change.adoc b/sources/express-changes/sections/06-mapping-change.adoc
@@ -8,10 +8,10 @@ another schema or representation.
 
 The structure is built on the following constructs:
 
-* Edition changes: Each edition or version of the schema, detailing what
-changed.
+* Edition changes: Details changes made to this edition of the mapping specification
+against the previous version.
 
-* Item changes: Specific elements that had mappings changed in an edition.
+* Item changes: Specific elements in the mappings that were changed in this edition.
 
 Syntax:
 
@@ -26,33 +26,34 @@ editions:
 
 === Edition change
 
-Each edition change represents a specific version of the schema and details
-the mapping changes made in that version.
+Each edition change represents a changes made to the mapping specification in a
+specific edition compared to the previous edition.
 
 Syntax:
 
 [source,yaml]
 ----
 version: String (required)
 # Version number for this change edition
-description: String (required)
+description: String (optional)
 # Description of changes in this edition
-mapping:
+mappings:
   - {item change 1}
   - {item change 2}
 ----
 
 Fields:
 
-`version`:: The version number (string) (required).
+`version`:: (required) The version number (integer). Must be positive.
 +
 [example]
-`2`, `3.1`, `2024-06`.
+`2`, `3`, `6`.
 
-`description`:: A multi-line string describing the changes made in this edition
-(required). Should provide a comprehensive overview of what changed and why.
+`description`:: (optional) A multi-line string describing the changes made in
+this edition. Should provide a comprehensive overview of what changed and why.
+If not provided, a publication may provide its own boilerplate or summary.
 
-`mappings`:: An array of mapping changes (optional).
+`mappings`:: (optional) An array of mapping changes.
 
 
 === Mapping change
@@ -64,41 +65,33 @@ Syntax:
 
 [source,yaml]
 ----
-name: String (required)
+name: String (optional)
 # Name of the EXPRESS construct whose mapping changed
 description: String (optional)
 # Description of the mapping change
 ----
 
 Fields:
 
-`name`:: The name of the EXPRESS construct whose mapping changed (string) (required).
-
-`description`:: A description of the mapping change (string) (optional).
+`name`:: (optional) The name of the EXPRESS construct whose mapping changed (string).
 
+`description`:: (optional) A description of the mapping change (string).
 
-.Mapping change file from ISO 10303 SRL altered_package
+.Mapping change file from ISO 10303 SRL module product_as_individual_assembly_and_test
 [example]
 ====
 [source,yaml]
 ----
 ---
-schema: altered_package
-change_edition:
+schema: product_as_individual_assembly_and_test
+editions:
 - version: '2'
   mappings:
-  - name: Altered_package.modified_terminal_separation
-  - description: Altered_package.of_geometric_status mapping has been updated.
-- version: '3'
-  description: |-
-    Minor editorial changes.
-
-    The definitions of the following MIM EXPRESS declarations and interface specifications were modified:
-
-    * ENTITY surface_prepped_terminal.
-- version: '4'
-  description: 'Minor editorial change: the HTML link of Layered_assembly_module_design_view
-    in Surface_prepped_terminal''s description has been fixed.'
+  - description: Applied_activity_assignment mapping updated
+  - description: Applied_process_operation_occurrence mapping updated
+  - description: Applied_test_activity mapping updated
+- version: '5'
+  description: Mapping specifications updated.
 ----
 ====
 
diff --git a/sources/express-changes/sections/aa-examples.adoc b/sources/express-changes/sections/aa-examples.adoc
@@ -14,7 +14,7 @@ This example shows schema changes made to a resource schema,
 ----
 ---
 schema: support_resource_schema
-change_edition:
+editions:
 - version: '2'
   description: |-
     The definitions of the following EXPRESS entity data types were modified:
@@ -62,7 +62,7 @@ across several editions: version 2, version 3, version 4, and version 5.
 ----
 ---
 schema: Analytical_model_arm
-change_edition:
+editions:
 - version: '2'
   additions:
   - type: TYPE
@@ -85,7 +85,8 @@ change_edition:
     name: Specification_document_arm
   - type: REFERENCE_FROM
     name: product_identification_arm
-    interfaced_items: types_of_product
+    interfaced_items:
+    - types_of_product
 - version: '3'
   additions:
   - type: TYPE
