From 4e5ca70a2078f39dc509e4194ca776b1bc8f83bf Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Thu, 16 Oct 2025 10:25:07 +0800 Subject: [PATCH 1/5] feat: update 5005: use version instead of edition, use integer version instead of string --- .../schemas/mapping_changes.yaml | 21 +++++++-------- .../schemas/schema_changes.yaml | 21 +++++++-------- .../express-changes/sections/03-terms.adoc | 12 ++++++++- .../sections/04-structure.adoc | 10 +++---- .../sections/05-schema-change.adoc | 26 +++++++++---------- .../sections/06-mapping-change.adoc | 26 +++++++++---------- .../express-changes/sections/ab-schemas.adoc | 4 +-- 7 files changed, 64 insertions(+), 56 deletions(-) diff --git a/sources/express-changes/schemas/mapping_changes.yaml b/sources/express-changes/schemas/mapping_changes.yaml index 96cfa38..879364f 100644 --- a/sources/express-changes/schemas/mapping_changes.yaml +++ b/sources/express-changes/schemas/mapping_changes.yaml @@ -1,34 +1,33 @@ $schema: http://json-schema.org/draft-07/schema# title: EXPRESS Mapping Changes -description: Records modifications to EXPRESS schema mappings across editions +description: Records modifications to EXPRESS schema mappings across versions type: object required: - schema - - editions + - versions properties: schema: type: string description: Name of the EXPRESS schema - editions: + versions: type: array - description: Array of edition changes + description: Array of version changes items: - $ref: '#/definitions/edition_change' + $ref: '#/definitions/version_change' definitions: - edition_change: + version_change: type: object - description: Changes made to the mapping specification in a specific edition + description: Changes made to the mapping specification in a specific version required: - version properties: version: - type: string - description: Version number for this change edition - pattern: '^[1-9][0-9]*$' + type: integer + description: Version number for this change version description: type: string description: >- - Multi-line string describing the changes made in this edition. + Multi-line string describing the changes made in this version. Provides comprehensive overview of what changed and why. mappings: type: array diff --git a/sources/express-changes/schemas/schema_changes.yaml b/sources/express-changes/schemas/schema_changes.yaml index f73bd3c..2d5f14b 100644 --- a/sources/express-changes/schemas/schema_changes.yaml +++ b/sources/express-changes/schemas/schema_changes.yaml @@ -1,34 +1,33 @@ $schema: http://json-schema.org/draft-07/schema# title: EXPRESS Schema Changes -description: Records modifications to EXPRESS schema structure across editions +description: Records modifications to EXPRESS schema structure across versions type: object required: - schema - - editions + - versions properties: schema: type: string description: Name of the EXPRESS schema - editions: + versions: type: array - description: Array of edition changes + description: Array of version changes items: - $ref: '#/definitions/edition_change' + $ref: '#/definitions/version_change' definitions: - edition_change: + version_change: type: object - description: Changes made to the schema in a specific edition + description: Changes made to the schema in a specific version required: - version properties: version: - type: string - description: Version number for this change edition - pattern: '^[1-9][0-9]*$' + type: integer + description: Version number for this change version description: type: string description: >- - Multi-line string describing the changes made in this edition. + Multi-line string describing the changes made in this version. Provides comprehensive overview of what changed and why. additions: type: array diff --git a/sources/express-changes/sections/03-terms.adoc b/sources/express-changes/sections/03-terms.adoc index 9f63768..28367c9 100644 --- a/sources/express-changes/sections/03-terms.adoc +++ b/sources/express-changes/sections/03-terms.adoc @@ -1,7 +1,17 @@ == Terms and definitions -=== change +=== schema change modification to an EXPRESS schema that alters the structure or semantics of the schema + +=== schema version + +specific iteration of an EXPRESS schema, identified by its version number +in the schema identifier as a positive integer + +=== mapping change + +modification to the mapping of an EXPRESS schema + diff --git a/sources/express-changes/sections/04-structure.adoc b/sources/express-changes/sections/04-structure.adoc index 720d4e7..efe4714 100644 --- a/sources/express-changes/sections/04-structure.adoc +++ b/sources/express-changes/sections/04-structure.adoc @@ -1,7 +1,7 @@ == Structure An EXPRESS Changes document is a YAML file that records changes made to an -EXPRESS schema across different editions or versions. +EXPRESS schema across different versions or versions. There are two kinds of changes: @@ -15,11 +15,11 @@ specification. ---- schema: String (required) # Name of the EXPRESS schema -editions: +versions: - version: String (required) - # Version number for this change edition + # Version number for this change version description: String (optional) - # Description of changes in this edition + # Description of changes in this version {type_of_change}: - description: String (required) # Description of the change @@ -33,7 +33,7 @@ Fields: [example] `support_resource_schema` -`editions`:: An array of edition change objects (required). +`versions`:: An array of version change objects (required). `type_of_change`:: One of `additions`, `modifications`, `removals`, or `mapping`. diff --git a/sources/express-changes/sections/05-schema-change.adoc b/sources/express-changes/sections/05-schema-change.adoc index 9e6d7a3..2e8a6a0 100644 --- a/sources/express-changes/sections/05-schema-change.adoc +++ b/sources/express-changes/sections/05-schema-change.adoc @@ -5,15 +5,15 @@ === General The schema change structure is a record of modifications to the structure and -semantics of an EXPRESS schema across different editions. +semantics of an EXPRESS schema across different versions. 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: Changes made to the schema in a specific edition compared to -the previous edition. +* Version changes: Changes made to the schema in a specific version compared to +the previous version. * Item changes: Specific elements that were added, modified, or removed. @@ -23,24 +23,24 @@ Syntax: ---- schema: String (required) # Name of the EXPRESS schema -editions: - - {edition change 1} - - {edition change 2} +versions: + - {version change 1} + - {version change 2} ---- -=== Edition change +=== Version change -Each edition change object details changes between two editions of the schema. +Each version change object details changes between two versions of the schema. Syntax: [source,yaml] ---- version: String (required) -# Version number for this change edition +# Version number for this change version description: String (optional) -# Description of changes in this edition +# Description of changes in this version additions: - {item change 1} - {item change 2} @@ -60,7 +60,7 @@ Fields: `2`, `3`, `6`. `description`:: (optional) A multi-line string describing the changes made in -this edition. Should provide a comprehensive overview of what changed and why. +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. @@ -123,7 +123,7 @@ description array would have two entries, one for each change. ---- --- schema: Additive_manufacturing_part_and_build_information_arm -editions: +versions: - version: '2' modifications: - type: ENTITY @@ -145,7 +145,7 @@ specific items referenced or used. Not needed when in `deletions`. ---- --- schema: Document_and_version_identification_mim -editions: +versions: - version: '2' deletions: - type: USE_FROM diff --git a/sources/express-changes/sections/06-mapping-change.adoc b/sources/express-changes/sections/06-mapping-change.adoc index 57a34db..8aa1a4d 100644 --- a/sources/express-changes/sections/06-mapping-change.adoc +++ b/sources/express-changes/sections/06-mapping-change.adoc @@ -9,10 +9,10 @@ another schema or representation. The structure is built on the following constructs: -* Edition changes: Details changes made to this edition of the mapping specification +* Version changes: Details changes made to this version of the mapping specification against the previous version. -* Item changes: Specific elements in the mappings that were changed in this edition. +* Item changes: Specific elements in the mappings that were changed in this version. Syntax: @@ -20,24 +20,24 @@ Syntax: ---- schema: String (required) # Name of the EXPRESS schema -editions: - - {edition change 1} - - {edition change 2} +versions: + - {version change 1} + - {version change 2} ---- -=== Edition change +=== Version change -Each edition change represents a changes made to the mapping specification in a -specific edition compared to the previous edition. +Each version change represents a changes made to the mapping specification in a +specific version compared to the previous version. Syntax: [source,yaml] ---- version: String (required) -# Version number for this change edition +# Version number for this change version description: String (optional) -# Description of changes in this edition +# Description of changes in this version mappings: - {item change 1} - {item change 2} @@ -51,7 +51,7 @@ Fields: `2`, `3`, `6`. `description`:: (optional) A multi-line string describing the changes made in -this edition. Should provide a comprehensive overview of what changed and why. +this version. Should provide a comprehensive overview of what changed and why. If not provided, a publication may provide its own boilerplate or summary. `mappings`:: (optional) An array of mapping changes. @@ -60,7 +60,7 @@ If not provided, a publication may provide its own boilerplate or summary. === Mapping change Each mapping change represents a specific element whose mapping has changed in an -edition. +version. Syntax: @@ -85,7 +85,7 @@ Fields: ---- --- schema: product_as_individual_assembly_and_test -editions: +versions: - version: '2' mappings: - description: Applied_activity_assignment mapping updated diff --git a/sources/express-changes/sections/ab-schemas.adoc b/sources/express-changes/sections/ab-schemas.adoc index 638ea7c..3981835 100644 --- a/sources/express-changes/sections/ab-schemas.adoc +++ b/sources/express-changes/sections/ab-schemas.adoc @@ -12,7 +12,7 @@ generate documentation or tooling for working with EXPRESS change records. === Schema change schema The schema change schema defines the structure for recording modifications to -EXPRESS schema structure across editions, as described in <>. +EXPRESS schema structure across versions, as described in <>. The schema is defined in JSON Schema format (draft-07). @@ -24,7 +24,7 @@ include::../schemas/schema_changes.yaml[] === Mapping change schema The mapping change schema defines the structure for recording modifications to -EXPRESS schema mappings across editions, as described in <>. +EXPRESS schema mappings across versions, as described in <>. The schema is defined in JSON Schema format (draft-07). From 84e5f4d92bf6edfaa7d9a7c1d74f4e2a03fbf6cc Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Thu, 16 Oct 2025 10:25:23 +0800 Subject: [PATCH 2/5] feat: update 5005: add SUBTYPE_CONSTRAINT as acceptable type --- sources/express-changes/schemas/schema_changes.yaml | 1 + sources/express-changes/sections/05-schema-change.adoc | 1 + 2 files changed, 2 insertions(+) diff --git a/sources/express-changes/schemas/schema_changes.yaml b/sources/express-changes/schemas/schema_changes.yaml index 2d5f14b..0029e0b 100644 --- a/sources/express-changes/schemas/schema_changes.yaml +++ b/sources/express-changes/schemas/schema_changes.yaml @@ -63,6 +63,7 @@ definitions: - CONSTANT - REFERENCE_FROM - USE_FROM + - SUBTYPE_CONSTRAINT name: type: string description: Name of the EXPRESS construct diff --git a/sources/express-changes/sections/05-schema-change.adoc b/sources/express-changes/sections/05-schema-change.adoc index 2e8a6a0..9bc9d7d 100644 --- a/sources/express-changes/sections/05-schema-change.adoc +++ b/sources/express-changes/sections/05-schema-change.adoc @@ -103,6 +103,7 @@ are: `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. From 82e8530d711986f48c5c0a23da3427c68602cec2 Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Thu, 16 Oct 2025 10:25:52 +0800 Subject: [PATCH 3/5] feat: update 5005: update schemas --- sources/express-changes/schemas/mapping_changes.yaml | 3 +++ sources/express-changes/schemas/schema_changes.yaml | 3 +++ 2 files changed, 6 insertions(+) diff --git a/sources/express-changes/schemas/mapping_changes.yaml b/sources/express-changes/schemas/mapping_changes.yaml index 879364f..6f0026d 100644 --- a/sources/express-changes/schemas/mapping_changes.yaml +++ b/sources/express-changes/schemas/mapping_changes.yaml @@ -5,6 +5,7 @@ type: object required: - schema - versions +additionalProperties: false properties: schema: type: string @@ -20,6 +21,7 @@ definitions: description: Changes made to the mapping specification in a specific version required: - version + additionalProperties: false properties: version: type: integer @@ -37,6 +39,7 @@ definitions: mapping_change: type: object description: Represents a specific element whose mapping has changed + additionalProperties: false properties: name: type: string diff --git a/sources/express-changes/schemas/schema_changes.yaml b/sources/express-changes/schemas/schema_changes.yaml index 0029e0b..69d5326 100644 --- a/sources/express-changes/schemas/schema_changes.yaml +++ b/sources/express-changes/schemas/schema_changes.yaml @@ -5,6 +5,7 @@ type: object required: - schema - versions +additionalProperties: false properties: schema: type: string @@ -20,6 +21,7 @@ definitions: description: Changes made to the schema in a specific version required: - version + additionalProperties: false properties: version: type: integer @@ -47,6 +49,7 @@ definitions: item_change: type: object description: Represents a specific schema element change + additionalProperties: false required: - type - name From 1ce538e29130bb0b69573993187b0dbd7ea937af Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Thu, 16 Oct 2025 10:26:05 +0800 Subject: [PATCH 4/5] feat: update 5005: update document and provide schemas and new examples --- sources/express-changes/document.adoc | 2 + .../express-changes/examples/arm.changes.yaml | 6 + .../examples/mapping.changes.yaml | 17 +++ .../express-changes/examples/mim.changes.yaml | 15 +++ .../support_resource_schema.changes.yaml | 42 ++++++ .../express-changes/sections/aa-examples.adoc | 124 ++---------------- 6 files changed, 93 insertions(+), 113 deletions(-) create mode 100644 sources/express-changes/examples/arm.changes.yaml create mode 100644 sources/express-changes/examples/mapping.changes.yaml create mode 100644 sources/express-changes/examples/mim.changes.yaml create mode 100644 sources/express-changes/examples/support_resource_schema.changes.yaml diff --git a/sources/express-changes/document.adoc b/sources/express-changes/document.adoc index a744845..cd6e569 100644 --- a/sources/express-changes/document.adoc +++ b/sources/express-changes/document.adoc @@ -40,4 +40,6 @@ include::sections/06-mapping-change.adoc[] include::sections/aa-examples.adoc[] +include::sections/ab-schemas.adoc[] + include::sections/az-bibliography.adoc[] diff --git a/sources/express-changes/examples/arm.changes.yaml b/sources/express-changes/examples/arm.changes.yaml new file mode 100644 index 0000000..ac63574 --- /dev/null +++ b/sources/express-changes/examples/arm.changes.yaml @@ -0,0 +1,6 @@ +# yaml-language-server: $schema=https://www.expresslang.org/schemas/changes/v1/schema_changes.yaml +--- +schema: Document_and_version_identification_arm +editions: +- version: '2' +- version: '3' diff --git a/sources/express-changes/examples/mapping.changes.yaml b/sources/express-changes/examples/mapping.changes.yaml new file mode 100644 index 0000000..26b9c26 --- /dev/null +++ b/sources/express-changes/examples/mapping.changes.yaml @@ -0,0 +1,17 @@ +# yaml-language-server: $schema=https://www.expresslang.org/schemas/changes/v1/mapping_changes.yaml +--- +schema: dimension_tolerance +editions: +- version: '6' + mappings: + - description: Geometric_dimension entity and attributes mapping has been updated + - description: Angle_plus_minus_bounds and Length_plus_minus_bounds mappings was + added +- version: '7' + mappings: + - description: Angle_plus_minus_bounds mapping has been updated + - description: Length_plus_minus_bounds mapping has been updated + - description: Applied_activity_assignment ENTITY mapped +- version: '8' + mappings: + - description: Geometric_dimension entity and attributes mapping has been updated diff --git a/sources/express-changes/examples/mim.changes.yaml b/sources/express-changes/examples/mim.changes.yaml new file mode 100644 index 0000000..afa0c23 --- /dev/null +++ b/sources/express-changes/examples/mim.changes.yaml @@ -0,0 +1,15 @@ +# yaml-language-server: $schema=https://www.expresslang.org/schemas/changes/v1/schema_changes.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/examples/support_resource_schema.changes.yaml b/sources/express-changes/examples/support_resource_schema.changes.yaml new file mode 100644 index 0000000..ea5c1af --- /dev/null +++ b/sources/express-changes/examples/support_resource_schema.changes.yaml @@ -0,0 +1,42 @@ +# yaml-language-server: $schema=https://www.expresslang.org/schemas/changes/v1/schema_changes.yaml +--- +schema: support_resource_schema +editions: +- version: '2' + description: |- + The definitions of the following EXPRESS entity data types were modified: + + * identifier; + * label; + * text. + additions: + - type: FUNCTION + name: type_check_function + modifications: + - type: FUNCTION + name: bag_to_set +- version: '4' + description: |- + The following entity types had been introduced to support external element references outside the local population of entity instances: + + * component_path_shape_aspect; + * externally_defined_item_with_multiple_references; + * generic_product_definition_reference; + * product_definition_reference; + * product_definition_reference_with_local_representation. + + The following entity types had been introduced to support the the characterization of objects: + + * characterized_chain_based_item_within_representation; + * characterized_item_within_representation; + * characterized_product. + + The following select types from the basic_attribute_schema had been converted into extensible selects and then extended in several other schemas: + + * description_attribute_select; + * id_attribute_select; + * name_attribute_select; + * role_select. + modifications: + - type: FUNCTION + name: type_check_function diff --git a/sources/express-changes/sections/aa-examples.adoc b/sources/express-changes/sections/aa-examples.adoc index e472a97..5683944 100644 --- a/sources/express-changes/sections/aa-examples.adoc +++ b/sources/express-changes/sections/aa-examples.adoc @@ -7,138 +7,36 @@ This annex provides example of the EXPRESS Changes YAML format. === Schema change -This example shows schema changes made to a resource schema, -`support_resource_schema` across two editions: version 2 and version 4. +This example shows schema changes made to the `support_resource_schema`, a +resource schema. [source,yaml] ---- ---- -schema: support_resource_schema -editions: -- version: '2' - description: |- - The definitions of the following EXPRESS entity data types were modified: - - * identifier; - * label; - * text. - additions: - - type: FUNCTION - name: type_check_function - modifications: - - type: FUNCTION - name: bag_to_set -- version: '4' - description: |- - The following entity types had been introduced to support external element references outside the local population of entity instances: - - * component_path_shape_aspect; - * externally_defined_item_with_multiple_references; - * generic_product_definition_reference; - * product_definition_reference; - * product_definition_reference_with_local_representation. - - The following entity types had been introduced to support the the characterization of objects: - - * characterized_chain_based_item_within_representation; - * characterized_item_within_representation; - * characterized_product. - - The following select types from the basic_attribute_schema had been converted into extensible selects and then extended in several other schemas: - - * description_attribute_select; - * id_attribute_select; - * name_attribute_select; - * role_select. - modifications: - - type: FUNCTION - name: type_check_function +include::../examples/support_resource_schema.changes.yaml[] ---- -This example shows schema changes made to the ARM `Analytical_model_arm` schema -across several editions: version 2, version 3, version 4, and version 5. +This example shows schema changes made to the ARM +`Document_and_version_identification_arm` schema. [source,yaml] ---- ---- -schema: Analytical_model_arm -editions: -- version: '2' - additions: - - type: TYPE - name: am_property_assignment_select - modifications: - - type: TYPE - name: model_parameter_type - - type: ENTITY - name: Analytical_model - - type: ENTITY - name: Analytical_model_application - - type: ENTITY - name: Analytical_model_parameter - - type: ENTITY - name: Digital_analytical_model_port - - type: ENTITY - name: Digital_analytical_model_vector_port - deletions: - - type: USE_FROM - name: Specification_document_arm - - type: REFERENCE_FROM - name: product_identification_arm - interfaced_items: - - types_of_product -- version: '3' - additions: - - type: TYPE - name: am_parameter_assignment_select - modifications: - - type: ENTITY - name: Transform_port_variable -- version: '4' - description: The name of the Application Object Analog_port_variable was changed - to Port_variable. -- version: '5' - additions: - - type: USE_FROM - name: Part_template_arm - - type: ENTITY - name: reference_part_template_for_analytical_model +include::../examples/arm.changes.yaml[] ---- -This example shows schema changes made to the MIM `Analytical_model_mim` schema -across two editions: version 4 and version 5. +This example shows schema changes made to the MIM +`Document_and_version_identification_mim` schema. [source,yaml] ---- ---- -schema: Analytical_model_mim -change_edition: -- version: '4' - deletions: - - type: ENTITY - name: analog_port_variable -- version: '5' - additions: - - type: USE_FROM - name: Part_template_mim +include::../examples/mim.changes.yaml[] ---- === Mapping change -This example shows mapping changes made to the `product_as_individual_assembly_and_test` -schema across two editions: version 2 and version 5. +This example shows mapping changes made to the `dimension_tolerance` mapping. [source,yaml] ---- ---- -schema: product_as_individual_assembly_and_test -editions: -- version: '2' - mappings: - - 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. +include::../examples/mapping.changes.yaml[] ---- From 8e2bb176160fae2c607272e02a9951f04fbea0db Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Thu, 16 Oct 2025 10:28:38 +0800 Subject: [PATCH 5/5] fix: update 5005 fix name of deletions key --- sources/express-changes/sections/04-structure.adoc | 4 ++-- sources/express-changes/sections/05-schema-change.adoc | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/sources/express-changes/sections/04-structure.adoc b/sources/express-changes/sections/04-structure.adoc index efe4714..3da7f58 100644 --- a/sources/express-changes/sections/04-structure.adoc +++ b/sources/express-changes/sections/04-structure.adoc @@ -35,6 +35,6 @@ Fields: `versions`:: An array of version change objects (required). -`type_of_change`:: One of `additions`, `modifications`, `removals`, or -`mapping`. +`type_of_change`:: One of `additions`, `modifications`, `deletions`, or +`mappings`. diff --git a/sources/express-changes/sections/05-schema-change.adoc b/sources/express-changes/sections/05-schema-change.adoc index 9bc9d7d..8010b1f 100644 --- a/sources/express-changes/sections/05-schema-change.adoc +++ b/sources/express-changes/sections/05-schema-change.adoc @@ -7,7 +7,7 @@ The schema change structure is a record of modifications to the structure and semantics of an EXPRESS schema across different versions. -It records additions, modifications, and removals of schema elements such as +It records additions, modifications, and deletions of schema elements such as entities, types, functions, and rules. The structure is built on the following constructs: @@ -47,7 +47,7 @@ additions: modifications: - {item change 1} - {item change 2} -removals: +deletions: - {item change 1} - {item change 2} ---- @@ -67,7 +67,7 @@ If not provided, a publication may provide its own boilerplate or summary. `modifications`:: (optional) An array of modified elements as item changes. -`removals`:: (optional) An array of removed elements as item changes. +`deletions`:: (optional) An array of removed elements as item changes.