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/schemas/mapping_changes.yaml b/sources/express-changes/schemas/mapping_changes.yaml index 96cfa38..6f0026d 100644 --- a/sources/express-changes/schemas/mapping_changes.yaml +++ b/sources/express-changes/schemas/mapping_changes.yaml @@ -1,34 +1,35 @@ $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 +additionalProperties: false 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 + additionalProperties: false 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 @@ -38,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 f73bd3c..69d5326 100644 --- a/sources/express-changes/schemas/schema_changes.yaml +++ b/sources/express-changes/schemas/schema_changes.yaml @@ -1,34 +1,35 @@ $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 +additionalProperties: false 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 + additionalProperties: false 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 @@ -48,6 +49,7 @@ definitions: item_change: type: object description: Represents a specific schema element change + additionalProperties: false required: - type - name @@ -64,6 +66,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/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..3da7f58 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,8 +33,8 @@ 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`. +`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 9e6d7a3..8010b1f 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 +It records additions, modifications, and deletions 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,31 +23,31 @@ 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} modifications: - {item change 1} - {item change 2} -removals: +deletions: - {item change 1} - {item change 2} ---- @@ -60,14 +60,14 @@ 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. `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. @@ -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. @@ -123,7 +124,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 +146,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/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[] ---- 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).