From aaa383146184d534908039deb51b2efd7ecd8ff6 Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Tue, 14 Oct 2025 18:59:26 +0800 Subject: [PATCH 1/4] feat: update changes yaml spec for latest ISO 10303 --- sources/express-changes/document.adoc | 10 +- sources/express-changes/sections/04-spec.adoc | 105 ------------- .../sections/04-structure.adoc | 40 +++++ .../sections/05-schema-change.adoc | 101 +++++++++++++ .../sections/06-mapping-change.adoc | 104 +++++++++++++ .../express-changes/sections/aa-example.adoc | 7 - .../express-changes/sections/aa-examples.adoc | 143 ++++++++++++++++++ 7 files changed, 396 insertions(+), 114 deletions(-) delete mode 100644 sources/express-changes/sections/04-spec.adoc create mode 100644 sources/express-changes/sections/04-structure.adoc create mode 100644 sources/express-changes/sections/05-schema-change.adoc create mode 100644 sources/express-changes/sections/06-mapping-change.adoc delete mode 100644 sources/express-changes/sections/aa-example.adoc create mode 100644 sources/express-changes/sections/aa-examples.adoc 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/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..b2e6581 --- /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 (required) + # 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..efc69f9 --- /dev/null +++ b/sources/express-changes/sections/05-schema-change.adoc @@ -0,0 +1,101 @@ + +== Schema change + +=== 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 +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. + +* Item changes: Specific elements that were added, modified, or removed in an +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 specific version of the schema and details +the changes made in that version. + +Syntax: + +[source,yaml] +---- +version: String (required) +# Version number for this change edition +description: String (required) +# 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`:: The version number (string) (required). ++ +[example] +`2`, `3.1`, `2024-06`. + +`description`:: A multi-line string describing the changes made in this edition +(required). Should provide a comprehensive overview of what changed and why. + +`additions`:: An array of added elements as item changes (optional). + +`modifications`:: An array of modified elements as item changes (optional). + +`removals`:: An array of removed elements as item changes (optional). + + + +=== Item change + +Each item change represents a specific schema element that was added, modified, +or removed. + +Syntax: + +[source,yaml] +---- +type: String (required) +# Type of the EXPRESS construct (e.g., ENTITY, TYPE, FUNCTION) +name: String (required) +# Name of the EXPRESS construct +---- + +Fields: + +`type`:: The type of the EXPRESS construct (string) (required). Allowed values +are: + +`ENTITY`::: Entity definitions +`TYPE`::: Type definitions (including SELECT, ENUMERATION) +`FUNCTION`::: Function definitions +`RULE`::: Rule definitions +`PROCEDURE`::: Procedure definitions +`CONSTANT`::: Constant definitions + +`name`:: The name of the EXPRESS construct (string) (required). + 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..880437e --- /dev/null +++ b/sources/express-changes/sections/06-mapping-change.adoc @@ -0,0 +1,104 @@ +== 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: Each edition or version of the schema, detailing what +changed. + +* Item changes: Specific elements that had mappings changed in an 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 specific version of the schema and details +the mapping changes made in that version. + +Syntax: + +[source,yaml] +---- +version: String (required) +# Version number for this change edition +description: String (required) +# Description of changes in this edition +mapping: + - {item change 1} + - {item change 2} +---- + +Fields: + +`version`:: The version number (string) (required). ++ +[example] +`2`, `3.1`, `2024-06`. + +`description`:: A multi-line string describing the changes made in this edition +(required). Should provide a comprehensive overview of what changed and why. + +`mappings`:: An array of mapping changes (optional). + + +=== Mapping change + +Each mapping change represents a specific element whose mapping has changed in an +edition. + +Syntax: + +[source,yaml] +---- +name: String (required) +# 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). + + +.Mapping change file from ISO 10303 SRL altered_package +[example] +==== +[source,yaml] +---- +--- +schema: altered_package +change_edition: +- 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.' +---- +==== + 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..10d9bfa --- /dev/null +++ b/sources/express-changes/sections/aa-examples.adoc @@ -0,0 +1,143 @@ +[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 +change_edition: +- 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 +change_edition: +- 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. +---- From 1b748724261c4507e4393a8ec184697eaf135eb0 Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Wed, 15 Oct 2025 15:57:40 +0800 Subject: [PATCH 2/4] feat: update content per @TRThurman and make interfaced_items and description more granular --- .../sections/04-structure.adoc | 2 +- .../sections/05-schema-change.adoc | 105 ++++++++++++++---- .../sections/06-mapping-change.adoc | 55 ++++----- .../express-changes/sections/aa-examples.adoc | 7 +- 4 files changed, 111 insertions(+), 58 deletions(-) diff --git a/sources/express-changes/sections/04-structure.adoc b/sources/express-changes/sections/04-structure.adoc index b2e6581..720d4e7 100644 --- a/sources/express-changes/sections/04-structure.adoc +++ b/sources/express-changes/sections/04-structure.adoc @@ -18,7 +18,7 @@ schema: String (required) editions: - version: String (required) # Version number for this change edition - description: String (required) + description: String (optional) # Description of changes in this edition {type_of_change}: - description: String (required) diff --git a/sources/express-changes/sections/05-schema-change.adoc b/sources/express-changes/sections/05-schema-change.adoc index efc69f9..5ffd55f 100644 --- 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,8 +30,7 @@ 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: @@ -39,7 +38,7 @@ Syntax: ---- 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 index 880437e..581e697 100644 --- 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,8 +26,8 @@ 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: @@ -35,24 +35,25 @@ Syntax: ---- 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,7 +65,7 @@ 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 @@ -72,33 +73,25 @@ description: String (optional) 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 index 10d9bfa..e472a97 100644 --- 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 From 53e17b2e7ee2e73f204c9f0a524f28db61acd65a Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Wed, 15 Oct 2025 15:57:51 +0800 Subject: [PATCH 3/4] chore: add gitignore --- .gitignore | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 .gitignore 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/ From 4779e567aaca0a3a9c1da0f6736a7019e8e4fe72 Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Wed, 15 Oct 2025 16:44:58 +0800 Subject: [PATCH 4/4] feat: add YAML schemas for schema changes and mapping changes --- .../schemas/mapping_changes.yaml | 47 +++++++++++ .../schemas/schema_changes.yaml | 83 +++++++++++++++++++ .../sections/05-schema-change.adoc | 1 + .../sections/06-mapping-change.adoc | 2 +- .../express-changes/sections/ab-schemas.adoc | 34 ++++++++ 5 files changed, 166 insertions(+), 1 deletion(-) create mode 100644 sources/express-changes/schemas/mapping_changes.yaml create mode 100644 sources/express-changes/schemas/schema_changes.yaml create mode 100644 sources/express-changes/sections/ab-schemas.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/05-schema-change.adoc b/sources/express-changes/sections/05-schema-change.adoc index 5ffd55f..9e6d7a3 100644 --- a/sources/express-changes/sections/05-schema-change.adoc +++ b/sources/express-changes/sections/05-schema-change.adoc @@ -1,4 +1,5 @@ +[[schema-change]] == Schema change === General diff --git a/sources/express-changes/sections/06-mapping-change.adoc b/sources/express-changes/sections/06-mapping-change.adoc index 581e697..57a34db 100644 --- a/sources/express-changes/sections/06-mapping-change.adoc +++ b/sources/express-changes/sections/06-mapping-change.adoc @@ -1,3 +1,4 @@ +[[mapping-change]] == Mapping change === General @@ -94,4 +95,3 @@ editions: 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[] +----