diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..0fc23b3 --- /dev/null +++ b/.gitignore @@ -0,0 +1,7 @@ +*.abort +Gemfile.lock +*.log.* +*.err +relaton/ +iev/ +_site/ diff --git a/sources/express-changes/document.adoc b/sources/express-changes/document.adoc index d17d75b..a744845 100644 --- a/sources/express-changes/document.adoc +++ b/sources/express-changes/document.adoc @@ -2,7 +2,7 @@ :docnumber: 5005 :edition: 1 :copyright-year: 2025 -:revdate: 2025-02-06 +:revdate: 2025-10-14 :language: en :title-main-en: EXPRESS changes model in YAML :doctype: standard @@ -32,6 +32,12 @@ include::sections/02-normrefs.adoc[] include::sections/03-terms.adoc[] -include::sections/04-spec.adoc[] +include::sections/04-structure.adoc[] + +include::sections/05-schema-change.adoc[] + +include::sections/06-mapping-change.adoc[] + +include::sections/aa-examples.adoc[] include::sections/az-bibliography.adoc[] diff --git a/sources/express-changes/schemas/mapping_changes.yaml b/sources/express-changes/schemas/mapping_changes.yaml new file mode 100644 index 0000000..96cfa38 --- /dev/null +++ b/sources/express-changes/schemas/mapping_changes.yaml @@ -0,0 +1,47 @@ +$schema: http://json-schema.org/draft-07/schema# +title: EXPRESS Mapping Changes +description: Records modifications to EXPRESS schema mappings across editions +type: object +required: + - schema + - editions +properties: + schema: + type: string + description: Name of the EXPRESS schema + editions: + type: array + description: Array of edition changes + items: + $ref: '#/definitions/edition_change' +definitions: + edition_change: + type: object + description: Changes made to the mapping specification in a specific edition + required: + - version + properties: + version: + type: string + description: Version number for this change edition + pattern: '^[1-9][0-9]*$' + description: + type: string + description: >- + Multi-line string describing the changes made in this edition. + Provides comprehensive overview of what changed and why. + mappings: + type: array + description: Array of mapping changes + items: + $ref: '#/definitions/mapping_change' + mapping_change: + type: object + description: Represents a specific element whose mapping has changed + properties: + name: + type: string + description: Name of the EXPRESS construct whose mapping changed + description: + type: string + description: Description of the mapping change diff --git a/sources/express-changes/schemas/schema_changes.yaml b/sources/express-changes/schemas/schema_changes.yaml new file mode 100644 index 0000000..f73bd3c --- /dev/null +++ b/sources/express-changes/schemas/schema_changes.yaml @@ -0,0 +1,83 @@ +$schema: http://json-schema.org/draft-07/schema# +title: EXPRESS Schema Changes +description: Records modifications to EXPRESS schema structure across editions +type: object +required: + - schema + - editions +properties: + schema: + type: string + description: Name of the EXPRESS schema + editions: + type: array + description: Array of edition changes + items: + $ref: '#/definitions/edition_change' +definitions: + edition_change: + type: object + description: Changes made to the schema in a specific edition + required: + - version + properties: + version: + type: string + description: Version number for this change edition + pattern: '^[1-9][0-9]*$' + description: + type: string + description: >- + Multi-line string describing the changes made in this edition. + Provides comprehensive overview of what changed and why. + additions: + type: array + description: Array of added elements + items: + $ref: '#/definitions/item_change' + modifications: + type: array + description: Array of modified elements + items: + $ref: '#/definitions/item_change' + removals: + type: array + description: Array of removed elements + items: + $ref: '#/definitions/item_change' + item_change: + type: object + description: Represents a specific schema element change + required: + - type + - name + properties: + type: + type: string + description: Type of the EXPRESS construct + enum: + - ENTITY + - TYPE + - FUNCTION + - RULE + - PROCEDURE + - CONSTANT + - REFERENCE_FROM + - USE_FROM + name: + type: string + description: Name of the EXPRESS construct + description: + type: array + description: >- + Array of strings describing the change. Each string represents + a description for a single change in the named target. + items: + type: string + interfaced_items: + type: array + description: >- + For USE_FROM or REFERENCE_FROM, list of specific items referenced + or used. Not needed when in deletions. + items: + type: string diff --git a/sources/express-changes/sections/04-spec.adoc b/sources/express-changes/sections/04-spec.adoc deleted file mode 100644 index 2798409..0000000 --- a/sources/express-changes/sections/04-spec.adoc +++ /dev/null @@ -1,105 +0,0 @@ -== Format structure - -The EXPRESS Changes YAML format follows this basic structure: - -[source,yaml] ----- -path: String (required) - # Relative path to the EXPRESS file -changes: - - type: String (required) - # Type of change: add, remove, modify - entity: String (required) - # Name of the entity being changed - details: String (required) - # Description of the change - original: String (optional) - # Original content (for modify/remove) - new: String (optional) - # New content (for add/modify) ----- - -== Change types - -=== Add - -Used when adding new elements to the schema. - -.Example -[example] -==== -[source,yaml] ----- -path: data/schema.exp -changes: - - type: add - entity: PERSON - details: Add new entity for representing individuals - new: | - ENTITY PERSON; - name: STRING; - age: INTEGER; - END_ENTITY; ----- -==== - -=== Remove - -Used when removing elements from the schema. - -.Example -[example] -==== -[source,yaml] ----- -path: data/schema.exp -changes: - - type: remove - entity: OBSOLETE_TYPE - details: Remove deprecated type definition - original: | - TYPE OBSOLETE_TYPE = INTEGER; - END_TYPE; ----- -==== - -=== Modify - -Used when modifying existing elements. - -.Example -[example] -==== -[source,yaml] ----- -path: data/schema.exp -changes: - - type: modify - entity: PERSON - details: Add email attribute to PERSON entity - original: | - ENTITY PERSON; - name: STRING; - END_ENTITY; - new: | - ENTITY PERSON; - name: STRING; - email: STRING; - END_ENTITY; ----- -==== - -== Validation rules - -1. The `path` field must be a valid relative path to an EXPRESS file -2. Each change must have a `type`, `entity`, and `details` field -3. `original` is required for `remove` and `modify` types -4. `new` is required for `add` and `modify` types -5. Multiple changes can be specified for the same file - -== Usage guidelines - -1. Keep change descriptions clear and specific -2. Include context in the details field -3. Maintain proper EXPRESS syntax in original/new content -4. Use consistent indentation in YAML structure diff --git a/sources/express-changes/sections/04-structure.adoc b/sources/express-changes/sections/04-structure.adoc new file mode 100644 index 0000000..720d4e7 --- /dev/null +++ b/sources/express-changes/sections/04-structure.adoc @@ -0,0 +1,40 @@ +== Structure + +An EXPRESS Changes document is a YAML file that records changes made to an +EXPRESS schema across different editions or versions. + +There are two kinds of changes: + +* Schema changes +* Mapping changes + +The top-level structure of an EXPRESS Changes document has the following +specification. + +[source,yaml] +---- +schema: String (required) + # Name of the EXPRESS schema +editions: + - version: String (required) + # Version number for this change edition + description: String (optional) + # Description of changes in this edition + {type_of_change}: + - description: String (required) + # Description of the change + # ... additional fields depending on type_of_change +---- + +Fields: + +`schema`:: The name of the EXPRESS schema (string) (required). ++ +[example] +`support_resource_schema` + +`editions`:: An array of edition 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 new file mode 100644 index 0000000..9e6d7a3 --- /dev/null +++ b/sources/express-changes/sections/05-schema-change.adoc @@ -0,0 +1,161 @@ + +[[schema-change]] +== Schema change + +=== General + +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: Changes made to the schema in a specific edition compared to +the previous edition. + +* Item changes: Specific elements that were added, modified, or removed. + +Syntax: + +[source,yaml] +---- +schema: String (required) + # Name of the EXPRESS schema +editions: + - {edition change 1} + - {edition change 2} +---- + + +=== Edition change + +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 (optional) +# Description of changes in this edition +additions: + - {item change 1} + - {item change 2} +modifications: + - {item change 1} + - {item change 2} +removals: + - {item change 1} + - {item change 2} +---- + +Fields: + +`version`:: (required) The version number (integer). Must be positive. ++ +[example] +`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. +If not provided, a publication may provide its own boilerplate or summary. + +`additions`:: (optional) An array of added elements as item changes. + +`modifications`:: (optional) An array of modified elements as item changes. + +`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, and when applicable, references to other EXPRESS constructs. + +Syntax: + +[source,yaml] +---- +# Type of the EXPRESS construct (e.g., ENTITY, TYPE, FUNCTION) +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`:: (required) The type of the EXPRESS construct (string). Allowed values +are: + +`ENTITY`::: Entity definitions +`TYPE`::: Type definitions (including SELECT, ENUMERATION) +`FUNCTION`::: Function definitions +`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 +---- +==== + +`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 new file mode 100644 index 0000000..57a34db --- /dev/null +++ b/sources/express-changes/sections/06-mapping-change.adoc @@ -0,0 +1,97 @@ +[[mapping-change]] +== Mapping change + +=== General + + +A mapping change records modifications to the mapping of an EXPRESS schema to +another schema or representation. + +The structure is built on the following constructs: + +* Edition changes: Details changes made to this edition of the mapping specification +against the previous version. + +* Item changes: Specific elements in the mappings that were changed in this edition. + +Syntax: + +[source,yaml] +---- +schema: String (required) + # Name of the EXPRESS schema +editions: + - {edition change 1} + - {edition change 2} +---- + +=== Edition change + +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 (optional) +# Description of changes in this edition +mappings: + - {item change 1} + - {item change 2} +---- + +Fields: + +`version`:: (required) The version number (integer). Must be positive. ++ +[example] +`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. +If not provided, a publication may provide its own boilerplate or summary. + +`mappings`:: (optional) An array of mapping changes. + + +=== Mapping change + +Each mapping change represents a specific element whose mapping has changed in an +edition. + +Syntax: + +[source,yaml] +---- +name: String (optional) +# Name of the EXPRESS construct whose mapping changed +description: String (optional) +# Description of the mapping change +---- + +Fields: + +`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 module product_as_individual_assembly_and_test +[example] +==== +[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. +---- +==== diff --git a/sources/express-changes/sections/aa-example.adoc b/sources/express-changes/sections/aa-example.adoc deleted file mode 100644 index 443f96c..0000000 --- a/sources/express-changes/sections/aa-example.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[appendix,obligation=informative] -== Changes YAML example - -This annex provides an example of the EXPRESS Changes YAML format. - -TODO. - diff --git a/sources/express-changes/sections/aa-examples.adoc b/sources/express-changes/sections/aa-examples.adoc new file mode 100644 index 0000000..e472a97 --- /dev/null +++ b/sources/express-changes/sections/aa-examples.adoc @@ -0,0 +1,144 @@ +[appendix,obligation=informative] +== Examples + +=== General + +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. + +[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 +---- + +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. + +[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 +---- + +This example shows schema changes made to the MIM `Analytical_model_mim` schema +across two editions: version 4 and version 5. + +[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 +---- + + +=== 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. + +[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. +---- diff --git a/sources/express-changes/sections/ab-schemas.adoc b/sources/express-changes/sections/ab-schemas.adoc new file mode 100644 index 0000000..638ea7c --- /dev/null +++ b/sources/express-changes/sections/ab-schemas.adoc @@ -0,0 +1,34 @@ +[appendix,obligation=informative] +== Schemas + +=== General + +This annex provides the JSON Schema definitions for the EXPRESS Changes YAML +formats defined in this document. + +These schemas can be used to validate EXPRESS Changes YAML files and to +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 <>. + +The schema is defined in JSON Schema format (draft-07). + +[source,yaml] +---- +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 <>. + +The schema is defined in JSON Schema format (draft-07). + +[source,yaml] +---- +include::../schemas/mapping_changes.yaml[] +----