From 5ea22f22c4f15f75139dc156dbbaa27cb046844b Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Thu, 23 Oct 2025 17:15:57 +0800 Subject: [PATCH] feat: schema changes: support moved_to and moved_From --- sources/express-changes/document.adoc | 4 +- .../examples/arm.changes.moved.yaml | 47 +++++++ .../examples/mim.changes.moved.yaml | 86 ++++++++++++ .../schemas/schema_changes.yaml | 56 ++++++-- .../sections/04-structure.adoc | 2 +- .../sections/05-schema-change.adoc | 127 +++++++++++++++--- .../{ab-schemas.adoc => aa-schemas.adoc} | 0 .../{aa-examples.adoc => ab-examples.adoc} | 16 +++ 8 files changed, 311 insertions(+), 27 deletions(-) create mode 100644 sources/express-changes/examples/arm.changes.moved.yaml create mode 100644 sources/express-changes/examples/mim.changes.moved.yaml rename sources/express-changes/sections/{ab-schemas.adoc => aa-schemas.adoc} (100%) rename sources/express-changes/sections/{aa-examples.adoc => ab-examples.adoc} (65%) diff --git a/sources/express-changes/document.adoc b/sources/express-changes/document.adoc index cd6e569..ca573b5 100644 --- a/sources/express-changes/document.adoc +++ b/sources/express-changes/document.adoc @@ -38,8 +38,8 @@ include::sections/05-schema-change.adoc[] include::sections/06-mapping-change.adoc[] -include::sections/aa-examples.adoc[] +include::sections/aa-schemas.adoc[] -include::sections/ab-schemas.adoc[] +include::sections/ab-examples.adoc[] include::sections/az-bibliography.adoc[] diff --git a/sources/express-changes/examples/arm.changes.moved.yaml b/sources/express-changes/examples/arm.changes.moved.yaml new file mode 100644 index 0000000..6c2cb46 --- /dev/null +++ b/sources/express-changes/examples/arm.changes.moved.yaml @@ -0,0 +1,47 @@ +# yaml-language-server: $schema=https://www.expresslang.org/schemas/changes/v1/schema_changes.yaml +--- +schema: Extended_basic_geometry_arm +versions: +- version: 2 + modifications: + - type: SUBTYPE_CONSTRAINT + name: alternate_extended_geometry_item + deletions: + - type: SUBTYPE_CONSTRAINT + name: axis_placement_subtype + - type: ENTITY + name: Axis_placement_2d + moved_to: + schema: Elemental_geometric_shape_arm + - type: ENTITY + name: Axis_placement_3d + moved_to: + schema: Elemental_geometric_shape_arm +- version: 3 + additions: + - type: USE_FROM + name: Geometric_model_relationship_arm + modifications: + - type: REFERENCE_FROM + name: alternate_extended_geometry_item + deletions: + - type: SUBTYPE_CONSTRAINT + name: Characterizable_object_arm + interfaced_items: + - bag_to_set + - type: ENTITY + name: Definitional_representation_relationship + moved_to: + schema: Geometric_model_relationship_arm + - type: ENTITY + name: Geometric_model_relationship + moved_to: + schema: Geometric_model_relationship + - type: FUNCTION + name: acyclic_representation_relationship + moved_to: + schema: Geometric_model_relationship +- version: 4 + modifications: + - type: SUBTYPE_CONSTRAINT + name: alternate_extended_geometry_item diff --git a/sources/express-changes/examples/mim.changes.moved.yaml b/sources/express-changes/examples/mim.changes.moved.yaml new file mode 100644 index 0000000..e58673c --- /dev/null +++ b/sources/express-changes/examples/mim.changes.moved.yaml @@ -0,0 +1,86 @@ +# yaml-language-server: $schema=https://www.expresslang.org/schemas/changes/v1/schema_changes.yaml +--- +schema: Associative_draughting_elements_mim +versions: +- version: 3 + additions: + - type: TYPE + name: draughting_model_item_definition + modifications: + - type: ENTITY + name: draughting_model_item_association +- version: 4 + additions: + - type: USE_FROM + name: geometric_model_schema + interfaced_items: + - geometric_set + - type: USE_FROM + name: draughting_element_schema + interfaced_items: + - annotation_plane + - type: USE_FROM + name: draughting_element_schema + interfaced_items: + - des_annotation_representation_select + - type: USE_FROM + name: draughting_element_schema + interfaced_items: + - draughting_model_item_association + - type: USE_FROM + name: draughting_element_schema + interfaced_items: + - draughting_model_item_definition + - type: USE_FROM + name: draughting_element_schema + interfaced_items: + - tessellated_annotation_occurence + - type: USE_FROM + name: presentation_definition_schema + interfaced_items: + - annotation_curve_occurrence + - type: USE_FROM + name: presentation_definition_schema + interfaced_items: + - annotation_fill_area_occurrence + - type: USE_FROM + name: presentation_definition_schema + interfaced_items: + - annotation_point_occurrence + - type: USE_FROM + name: presentation_definition_schema + interfaced_items: + - annotation_symbol_occurrence + - type: USE_FROM + name: presentation_definition_schema + interfaced_items: + - annotation_text_occurrence + - type: USE_FROM + name: product_property_definitin_schema + interfaced_items: + - product_definition_shape + - type: USE_FROM + name: product_property_definitin_schema + interfaced_items: + - property_definition + - type: USE_FROM + name: product_property_definitin_schema + interfaced_items: + - shape_aspect + - type: USE_FROM + name: product_property_definitin_schema + interfaced_items: + - shape_aspect_relationship + deletions: + - type: TYPE + name: draughting_model_item_association_select + moved_to: + schema: draughting_element_schema + - type: TYPE + name: draughting_model_item_definition + moved_to: + schema: draughting_element_schema + - type: ENTITY + name: draughting_model_item_assocation + moved_to: + schema: draughting_element_schema diff --git a/sources/express-changes/schemas/schema_changes.yaml b/sources/express-changes/schemas/schema_changes.yaml index 9076ca9..ae79705 100644 --- a/sources/express-changes/schemas/schema_changes.yaml +++ b/sources/express-changes/schemas/schema_changes.yaml @@ -1,4 +1,4 @@ -$schema: http://json-schema.org/draft-07/schema# +$schema: http://json-schema.org/draft-04/schema# title: EXPRESS Schema Changes description: Records modifications to EXPRESS schema structure across versions type: object @@ -33,23 +33,22 @@ definitions: Provides comprehensive overview of what changed and why. additions: type: array - description: Array of added elements + description: Array of addition changes representing added elements items: - $ref: '#/definitions/item_change' + $ref: '#/definitions/addition_change' modifications: type: array - description: Array of modified elements + description: Array of modification changes representing modifications items: - $ref: '#/definitions/item_change' + $ref: '#/definitions/modification_change' deletions: type: array - description: Array of deleted elements + description: Array of deletion changes representing removed elements items: - $ref: '#/definitions/item_change' + $ref: '#/definitions/deletion_change' item_change: type: object description: Represents a specific schema element change - additionalProperties: false required: - type - name @@ -84,3 +83,44 @@ definitions: or used. Not needed when in deletions. items: type: string + modification_change: + description: Represents a modification to the schema + $ref: '#/definitions/item_change' + addition_change: + description: Represents an addition to the schema + allOf: + - $ref: '#/definitions/item_change' + - properties: + moved_from: + type: object + description: >- + If the addition was due to a move from another schema, provides + the resource and module where it was moved from. + required: + - schema + properties: + schema: + type: string + description: Name of the schema where the item was moved from + version: + type: integer + description: Version number in the source schema + deletion_change: + description: Represents a deletion from the schema + allOf: + - $ref: '#/definitions/item_change' + - properties: + moved_to: + type: object + description: >- + If the deletion was due to a move to another schema, provides + the resource and module where it was moved to. + required: + - schema + properties: + schema: + type: string + description: Name of the schema where the item was moved to + version: + type: integer + description: Version number in the target schema diff --git a/sources/express-changes/sections/04-structure.adoc b/sources/express-changes/sections/04-structure.adoc index 3da7f58..4c72a9f 100644 --- a/sources/express-changes/sections/04-structure.adoc +++ b/sources/express-changes/sections/04-structure.adoc @@ -16,7 +16,7 @@ specification. schema: String (required) # Name of the EXPRESS schema versions: - - version: String (required) + - version: Integer (required) # Version number for this change version description: String (optional) # Description of changes in this version diff --git a/sources/express-changes/sections/05-schema-change.adoc b/sources/express-changes/sections/05-schema-change.adoc index 8010b1f..244357b 100644 --- a/sources/express-changes/sections/05-schema-change.adoc +++ b/sources/express-changes/sections/05-schema-change.adoc @@ -37,19 +37,19 @@ Syntax: [source,yaml] ---- -version: String (required) +version: Integer (required) # Version number for this change version description: String (optional) # Description of changes in this version additions: - - {item change 1} - - {item change 2} + - {addition change 1} + - {addition change 2} modifications: - - {item change 1} - - {item change 2} + - {modification change 1} + - {modification change 2} deletions: - - {item change 1} - - {item change 2} + - {deletion change 1} + - {deletion change 2} ---- Fields: @@ -63,18 +63,32 @@ Fields: this version. Should provide a comprehensive overview of what changed and why. If not provided, a publication may provide its own boilerplate or summary. -`additions`:: (optional) An array of added elements as item changes. +`additions`:: (optional) An array of added elements as addition changes. -`modifications`:: (optional) An array of modified elements as item changes. +`modifications`:: (optional) An array of modified elements as modification +changes. -`deletions`:: (optional) An array of removed elements as item changes. +`deletions`:: (optional) An array of removed elements as deletion changes. +=== Item changes -=== Item change +==== General -Each item change represents a specific schema element that was added, modified, -or removed, and when applicable, references to other EXPRESS constructs. +Item changes represent specific schema elements that were added, modified, or +removed. + +There are three types of item changes: + +* Addition change +* Modification change +* Deletion change + +==== Modification change + +Each modification change represents a specific schema element that was added, +modified, or removed, and when applicable, references to other EXPRESS +constructs. Syntax: @@ -98,15 +112,23 @@ Fields: are: `ENTITY`::: Entity definitions + `TYPE`::: Type definitions (including SELECT, ENUMERATION) + `FUNCTION`::: Function definitions + `RULE`::: Rule definitions + `PROCEDURE`::: Procedure definitions + `CONSTANT`::: Constant definitions + `SUBTYPE_CONSTRAINT`::: Subtype constraints + `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. @@ -125,7 +147,7 @@ description array would have two entries, one for each change. --- schema: Additive_manufacturing_part_and_build_information_arm versions: -- version: '2' +- version: 2 modifications: - type: ENTITY name: Additive_manufacturing_build_direction_element @@ -147,11 +169,11 @@ specific items referenced or used. Not needed when in `deletions`. --- schema: Document_and_version_identification_mim versions: -- version: '2' +- version: 2 deletions: - type: USE_FROM name: Product_identification_mim -- version: '3' +- version: 3 additions: - type: USE_FROM name: product_definition_schema @@ -160,3 +182,76 @@ versions: - product_related_product_category ---- ==== + +==== Addition change + +An addition change is a modification change representing an addition to the +schema. + +It uses the same structure as a modification change except it provides an +additional property for denoting if the addition was due to a move from another +schema. + +Each modification change represents a specific schema element that was added, +modified, or removed, and when applicable, references to other EXPRESS +constructs. + +Syntax: + +[source,yaml] +---- +{ modification change fields } +moved_from: (optional) + - schema: String (required) + version: Integer (optional) +---- + +Fields: + +`moved_from`:: (optional) If the addition was due to a move from another schema, +this field specifies the name of that schema. + +Fields within `moved_from`: + +`schema`:: (required) The name of the source schema from which the item was moved. + +`version`:: (optional) The version number in the source schema from which the item was moved. + +NOTE: The `moved_from` field is the inverse of `moved_to` of the deletion +change, allowing for tracking the movement of schema elements between different +versions and schemas. + + +==== Deletion change + +A deletion change is a modification change representing a removal from the +schema. + +It uses the same structure as a modification change except it provides an +additional property for denoting if the deletion was due to a move to another +schema. + +Syntax: + +[source,yaml] +---- +{ modification change fields } +moved_to: (optional) + - schema: String (required) + version: Integer (optional) +---- + +Fields: + +`moved_to`:: (optional) If the deletion was due to a move to another schema, +this field specifies the name of that schema. + +Fields within `moved_to`: + +`schema`:: (required) The name of the target schema to which the item was moved. + +`version`:: (optional) The version number in the target schema to which the item was moved. + +NOTE: The `moved_from` field accommodates semantics of the `moved-to-resource` +and `moved-to-module` attributes used internally in the STEPmod Resource +Library's XML files. diff --git a/sources/express-changes/sections/ab-schemas.adoc b/sources/express-changes/sections/aa-schemas.adoc similarity index 100% rename from sources/express-changes/sections/ab-schemas.adoc rename to sources/express-changes/sections/aa-schemas.adoc diff --git a/sources/express-changes/sections/aa-examples.adoc b/sources/express-changes/sections/ab-examples.adoc similarity index 65% rename from sources/express-changes/sections/aa-examples.adoc rename to sources/express-changes/sections/ab-examples.adoc index 72bf568..df24fa0 100644 --- a/sources/express-changes/sections/aa-examples.adoc +++ b/sources/express-changes/sections/ab-examples.adoc @@ -23,6 +23,14 @@ This example shows schema changes made to the ARM include::../examples/arm.changes.yaml[] ---- +This example shows schema changes made to the ARM `Extended_basic_geometry_arm` +schema, where an ENTITY is moved to another ARM schema. + +[source,yaml] +---- +include::../examples/arm.changes.moved.yaml[] +---- + This example shows schema changes made to the MIM `Document_and_version_identification_mim` schema. @@ -31,6 +39,14 @@ This example shows schema changes made to the MIM include::../examples/mim.changes.yaml[] ---- +This example shows schema changes made to the MIM +`Associative_draughting_elements_mim` schema, where an TYPE is moved to +another resource schema. + +[source,yaml] +---- +include::../examples/mim.changes.moved.yaml[] +---- === Mapping change