Don’t panic, EXPRESS.

Foreword

The EXPRESS Language Foundation (“ELF”) is a registered public charity in the US that facilitates the education, standardization, research, promotion, definition, and usage of information modelling and programming languages, with a focus on the EXPRESS language family.

ELF works with international partners and experts across the globe, reflecting the international nature of its mission. More information about ELF is available on the official website (https://www.expresslang.org).

The procedures used to develop this document and those intended for its further maintenance are described in the ELF Directives.

In particular, the different approval criteria needed for the different types of ELF documents should be noted. This document was drafted in accordance with the editorial rules of the ELF Directives.

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. ELF shall not be held responsible for identifying any or all such patent rights. Details of any patent rights identified during the development of the document will be provided in the Introduction.

Any trade name used in this document is information given for the convenience of users and does not constitute an endorsement.

This document was prepared by Technical Committee EXPRESS.

Introduction

This document specifies the YAML format used to track changes in EXPRESS schema files.

EXPRESS changes model in YAML

1 Scope

This document specifies the YAML format used to track changes in EXPRESS schema files.

2 Normative references

The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

ISO 10303-1:2024, Industrial automation systems and integration — Product data representation and exchange — Part 1: Overview and fundamental principles

ISO 10303-11:2004, Industrial automation systems and integration — Product data representation and exchange — Part 11: Description methods: The EXPRESS language reference manual

3 Terms and definitions

For the purposes of this document, the following terms and definitions apply.

ISO and IEC maintain terminology databases for use in standardization at the following addresses:

ISO Online browsing platform: available at https://www.iso.org/obp
IEC Electropedia: available at https://www.electropedia.org

3.1

schema change

modification to an EXPRESS schema that alters the structure or semantics of the schema

3.2

schema version

specific iteration of an EXPRESS schema, identified by its version number in the schema identifier as a positive integer

3.3

mapping change

modification to the mapping of an EXPRESS schema

4 Structure

An EXPRESS Changes document is a YAML file that records changes made to an EXPRESS schema across different versions 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.

schema: String (required)
  # Name of the EXPRESS schema
versions:
  - version: Integer (required)
    # Version number for this change version
    description: String (optional)
    # Description of changes in this version
    {type_of_change}:
      - description: String (required)
        # Description of the change
        # ... additional fields depending on type_of_change

Figure 1

Fields:

schema: The name of the EXPRESS schema (string) (required).

EXAMPLE support_resource_schema
versions: An array of version change objects (required).
type_of_change: One of additions, modifications, deletions, or mappings.

5 Schema change

5.1 General

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 deletions of schema elements such as entities, types, functions, and rules.

The structure is built on the following constructs:

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.

Syntax:

schema: String (required)
  # Name of the EXPRESS schema
versions:
  - {version change 1}
  - {version change 2}

Figure 2

5.2 Version change

Each version change object details changes between two versions of the schema.

Syntax:

version: Integer (required)
# Version number for this change version
description: String (optional)
# Description of changes in this version
additions:
  - {addition change 1}
  - {addition change 2}
modifications:
  - {modification change 1}
  - {modification change 2}
deletions:
  - {deletion change 1}
  - {deletion change 2}

Figure 3

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 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 addition changes.
modifications: (optional) An array of modified elements as modification changes.
deletions: (optional) An array of removed elements as deletion changes.

5.3 Item changes

5.3.1 General

Item changes represent specific schema elements that were added, modified, or removed.

There are three types of item changes:

Addition change
Modification change
Deletion change

5.3.2 Modification change

Each modification change represents a specific schema element that was added, modified, or removed, and when applicable, references to other EXPRESS constructs.

Syntax:

# 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

Figure 4

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
SUBTYPE_CONSTRAINT: Subtype constraints
REFERENCE_FROM: A reference from another schema, with an additional field interfaced_items listing the specific items referenced when in additions. When used in deletions, no interfaced_items is needed.
USE_FROM: A use from another schema, with an additional field interfaced_items listing the specific items used when in additions. When used in deletions, no interfaced_items is needed.

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 1

---
schema: Additive_manufacturing_part_and_build_information_arm
versions:
- 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 2

---
schema: Document_and_version_identification_mim
versions:
- 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

5.3.3 Addition change

An addition change is a modification change representing an addition to the schema.

It uses the same structure as a modification change except it provides an additional property for denoting if the addition was due to a move from another schema.

Each modification change represents a specific schema element that was added, modified, or removed, and when applicable, references to other EXPRESS constructs.

Syntax:

{ modification change fields }
moved_from: (optional)
  - schema: String (required)
    version: Integer (optional)

Figure 5

Fields:

moved_from: (optional) If the addition was due to a move from another schema, this field specifies the name of that schema.

Fields within moved_from:

schema: (required) The name of the source schema from which the item was moved.
version: (optional) The version number in the source schema from which the item was moved.

NOTE The moved_from field is the inverse of moved_to of the deletion change, allowing for tracking the movement of schema elements between different versions and schemas.

5.3.4 Deletion change

A deletion change is a modification change representing a removal from the schema.

It uses the same structure as a modification change except it provides an additional property for denoting if the deletion was due to a move to another schema.

Syntax:

{ modification change fields }
moved_to: (optional)
  - schema: String (required)
    version: Integer (optional)

Figure 6

Fields:

moved_to: (optional) If the deletion was due to a move to another schema, this field specifies the name of that schema.

Fields within moved_to:

schema: (required) The name of the target schema to which the item was moved.
version: (optional) The version number in the target schema to which the item was moved.

NOTE The moved_from field accommodates semantics of the moved-to-resource and moved-to-module attributes used internally in the STEPmod Resource Library’s XML files.

6 Mapping change

6.1 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:

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 version.

Syntax:

schema: String (required)
  # Name of the EXPRESS schema
versions:
  - {version change 1}
  - {version change 2}

Figure 7

6.2 Version change

Each version change represents a changes made to the mapping specification in a specific version compared to the previous version.

Syntax:

version: String (required)
# Version number for this change version
description: String (optional)
# Description of changes in this version
mappings:
  - {item change 1}
  - {item change 2}

Figure 8

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 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.

6.3 Mapping change

Each mapping change represents a specific element whose mapping has changed in an version.

Syntax:

name: String (optional)
# Name of the EXPRESS construct whose mapping changed
description: String (optional)
# Description of the mapping change

Figure 9

Fields:

name: (optional) The name of the EXPRESS construct whose mapping changed (string).
description: (optional) A description of the mapping change (string).

EXAMPLE — Mapping change file from ISO 10303 SRL module product_as_individual_assembly_and_test

---
schema: product_as_individual_assembly_and_test
versions:
- 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.

Annex A
(informative)

Schemas

A.1 General

This annex provides the YAML 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.

The schemas are defined in YAML Schema format that follows the JSON Schema format (draft-07).

A.2 Schema change schema

The schema change schema defines the structure for recording modifications to EXPRESS schema structure across versions, as described in Clause 5.

$schema: http://json-schema.org/draft-04/schema#
title: EXPRESS Schema Changes
description: Records modifications to EXPRESS schema structure across versions
type: object
required:
  - schema
  - versions
additionalProperties: false
properties:
  schema:
    type: string
    description: Name of the EXPRESS schema
  versions:
    type: array
    description: Array of version changes
    items:
      $ref: '#/definitions/version_change'
definitions:
  version_change:
    type: object
    description: Changes made to the schema in a specific version
    required:
      - version
    additionalProperties: false
    properties:
      version:
        type: integer
        description: Version number for this change version
      description:
        type: string
        description: >-
          Multi-line string describing the changes made in this version.
          Provides comprehensive overview of what changed and why.
      additions:
        type: array
        description: Array of addition changes representing added elements
        items:
          $ref: '#/definitions/addition_change'
      modifications:
        type: array
        description: Array of modification changes representing modifications
        items:
          $ref: '#/definitions/modification_change'
      deletions:
        type: array
        description: Array of deletion changes representing removed elements
        items:
          $ref: '#/definitions/deletion_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
          - SUBTYPE_CONSTRAINT
      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
  modification_change:
    description: Represents a modification to the schema
    $ref: '#/definitions/item_change'
  addition_change:
    description: Represents an addition to the schema
    allOf:
      - $ref: '#/definitions/item_change'
      - properties:
          moved_from:
            type: object
            description: >-
              If the addition was due to a move from another schema, provides
              the resource and module where it was moved from.
            required:
              - schema
            properties:
              schema:
                type: string
                description: Name of the schema where the item was moved from
              version:
                type: integer
                description: Version number in the source schema
  deletion_change:
    description: Represents a deletion from the schema
    allOf:
      - $ref: '#/definitions/item_change'
      - properties:
          moved_to:
            type: object
            description: >-
              If the deletion was due to a move to another schema, provides
              the resource and module where it was moved to.
            required:
              - schema
            properties:
              schema:
                type: string
                description: Name of the schema where the item was moved to
              version:
                type: integer
                description: Version number in the target schema

Figure A.1

This schema can be used for validation by inserting the following comment line at the beginning of the EXPRESS changes YAML file.

# yaml-language-server: $schema=https://www.expresslang.org/schemas/changes/v1/schema_changes.yaml

Figure A.2

A.3 Mapping change schema

The mapping change schema defines the structure for recording modifications to EXPRESS schema mappings across versions, as described in Clause 6.

$schema: http://json-schema.org/draft-07/schema#
title: EXPRESS Mapping Changes
description: Records modifications to EXPRESS schema mappings across versions
type: object
required:
  - schema
  - versions
additionalProperties: false
properties:
  schema:
    type: string
    description: Name of the EXPRESS schema
  versions:
    type: array
    description: Array of version changes
    items:
      $ref: '#/definitions/version_change'
definitions:
  version_change:
    type: object
    description: Changes made to the mapping specification in a specific version
    required:
      - version
    additionalProperties: false
    properties:
      version:
        type: integer
        description: Version number for this change version
      description:
        type: string
        description: >-
          Multi-line string describing the changes made in this version.
          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
    additionalProperties: false
    properties:
      name:
        type: string
        description: Name of the EXPRESS construct whose mapping changed
      description:
        type: string
        description: Description of the mapping change

Figure A.3

This schema can be used for validation by inserting the following comment line at the beginning of the EXPRESS changes YAML file.

# yaml-language-server: $schema=https://www.expresslang.org/schemas/changes/v1/mapping_changes.yaml

Figure A.4

Annex B
(informative)

Examples

B.1 General

This annex provides examples of the EXPRESS Changes YAML format.

B.2 Schema change

This example shows schema changes made to the support_resource_schema, a resource schema.

# yaml-language-server: $schema=https://www.expresslang.org/schemas/changes/v1/schema_changes.yaml
---
schema: support_resource_schema
versions:
- 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

Figure B.1

This example shows schema changes made to the ARM Document_and_version_identification_arm schema.

# yaml-language-server: $schema=https://www.expresslang.org/schemas/changes/v1/schema_changes.yaml
---
schema: Document_and_version_identification_arm
versions:
- version: 2
- version: 3

Figure B.2

This example shows schema changes made to the ARM Extended_basic_geometry_arm schema, where an ENTITY is moved to another ARM schema.

# yaml-language-server: $schema=https://www.expresslang.org/schemas/changes/v1/schema_changes.yaml
---
schema: Extended_basic_geometry_arm
versions:
- version: 2
  modifications:
  - type: SUBTYPE_CONSTRAINT
    name: alternate_extended_geometry_item
  deletions:
  - type: SUBTYPE_CONSTRAINT
    name: axis_placement_subtype
  - type: ENTITY
    name: Axis_placement_2d
    moved_to:
      schema: Elemental_geometric_shape_arm
  - type: ENTITY
    name: Axis_placement_3d
    moved_to:
      schema: Elemental_geometric_shape_arm
- version: 3
  additions:
  - type: USE_FROM
    name: Geometric_model_relationship_arm
  modifications:
  - type: REFERENCE_FROM
    name: alternate_extended_geometry_item
  deletions:
  - type: SUBTYPE_CONSTRAINT
    name: Characterizable_object_arm
    interfaced_items:
    - bag_to_set
  - type: ENTITY
    name: Definitional_representation_relationship
    moved_to:
      schema: Geometric_model_relationship_arm
  - type: ENTITY
    name: Geometric_model_relationship
    moved_to:
      schema: Geometric_model_relationship
  - type: FUNCTION
    name: acyclic_representation_relationship
    moved_to:
      schema: Geometric_model_relationship
- version: 4
  modifications:
  - type: SUBTYPE_CONSTRAINT
    name: alternate_extended_geometry_item

Figure B.3

This example shows schema changes made to the MIM Document_and_version_identification_mim schema.

# yaml-language-server: $schema=https://www.expresslang.org/schemas/changes/v1/schema_changes.yaml
---
schema: Document_and_version_identification_mim
versions:
- 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

Figure B.4

This example shows schema changes made to the MIM Associative_draughting_elements_mim schema, where an TYPE is moved to another resource schema.

# yaml-language-server: $schema=https://www.expresslang.org/schemas/changes/v1/schema_changes.yaml
---
schema: Associative_draughting_elements_mim
versions:
- version: 3
  additions:
  - type: TYPE
    name: draughting_model_item_definition
  modifications:
  - type: ENTITY
    name: draughting_model_item_association
- version: 4
  additions:
  - type: USE_FROM
    name: geometric_model_schema
    interfaced_items:
    - geometric_set
  - type: USE_FROM
    name: draughting_element_schema
    interfaced_items:
    - annotation_plane
  - type: USE_FROM
    name: draughting_element_schema
    interfaced_items:
    - des_annotation_representation_select
  - type: USE_FROM
    name: draughting_element_schema
    interfaced_items:
    - draughting_model_item_association
  - type: USE_FROM
    name: draughting_element_schema
    interfaced_items:
    - draughting_model_item_definition
  - type: USE_FROM
    name: draughting_element_schema
    interfaced_items:
    - tessellated_annotation_occurence
  - type: USE_FROM
    name: presentation_definition_schema
    interfaced_items:
    - annotation_curve_occurrence
  - type: USE_FROM
    name: presentation_definition_schema
    interfaced_items:
    - annotation_fill_area_occurrence
  - type: USE_FROM
    name: presentation_definition_schema
    interfaced_items:
    - annotation_point_occurrence
  - type: USE_FROM
    name: presentation_definition_schema
    interfaced_items:
    - annotation_symbol_occurrence
  - type: USE_FROM
    name: presentation_definition_schema
    interfaced_items:
    - annotation_text_occurrence
  - type: USE_FROM
    name: product_property_definitin_schema
    interfaced_items:
    - product_definition_shape
  - type: USE_FROM
    name: product_property_definitin_schema
    interfaced_items:
    - property_definition
  - type: USE_FROM
    name: product_property_definitin_schema
    interfaced_items:
    - shape_aspect
  - type: USE_FROM
    name: product_property_definitin_schema
    interfaced_items:
    - shape_aspect_relationship
  deletions:
  - type: TYPE
    name: draughting_model_item_association_select
    moved_to:
      schema: draughting_element_schema
  - type: TYPE
    name: draughting_model_item_definition
    moved_to:
      schema: draughting_element_schema
  - type: ENTITY
    name: draughting_model_item_assocation
    moved_to:
      schema: draughting_element_schema

Figure B.5

B.3 Mapping change

This example shows mapping changes made to the dimension_tolerance mapping.

# yaml-language-server: $schema=https://www.expresslang.org/schemas/changes/v1/mapping_changes.yaml
---
schema: dimension_tolerance
versions:
- 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

Figure B.6

Bibliography

[1] ISO 10303-21:2016, Industrial automation systems and integration — Product data representation and exchange — Part 21: Implementation methods: Clear text encoding of the exchange structure