Ifc Impl Version Migration

ifc-impl-version-migration

This skill is the workflow for migrating an IFC model from one schema version to another (IFC2x3, IFC4, IFC4.3). Migration is a structural transformation of the instance graph, NEVER a textual find-and-replace and NEVER a geometry or file-format conversion.

This skill teaches the concept and mechanics. It does NOT teach any library API. The reference implementation (ifcpatch Migrate) and the geometry tool (IfcConvert) are named only as pointers ; their API belongs to the Blender-Bonsai-ifcOpenShell package.

For the schema-evolution background see ifc-core-version-evolution. For diagnosing a version-mismatch failure see ifc-errors-version-mismatch.

Quick Reference

Migration is two ordered stages

Stage 1 : ENTITY MAPPING
   For every instance, map its source entity name to the target schema.
   Each name is one of : unchanged | renamed | deprecated | deleted.
   |
   v
Stage 2 : ATTRIBUTE MAPPING
   For every surviving instance, remap its positional attribute list to the
   target entity's attribute list : insert, drop, reorder, handle DERIVED.

ALWAYS run Stage 1 before Stage 2 : the attribute map depends on knowing the target entity. NEVER skip Stage 2 : EXPRESS records are positional, so a blind copy corrupts data the moment any attribute was added, removed, or reordered.

The four entity fates (Stage 1)

The 7-step migration strategy

A. Detect the source schema     read FILE_SCHEMA from the STEP header
B. Choose target and direction  flag the run lossy if it is a downgrade
C. Build the entity map         Stage 1, every source entity name
D. Build the attribute map      Stage 2, every surviving instance
E. Preserve identity and refs   keep GlobalId; no dangling #id references
F. Rewrite the STEP header      update FILE_SCHEMA and the MVD string
G. Validate the result          buildingSMART validation pipeline, mandatory

Migration is NOT geometry conversion

NEVER use IfcConvert to change an IFC schema version : it re-renders geometry into another file format and does not remap the entity graph.

Hard rules

• ALWAYS read the source schema from the FILE_SCHEMA header record. NEVER assume a version.
• ALWAYS complete Stage 1 exhaustively : a file declaring FILE_SCHEMA(('IFC4X3_ADD2')) that still contains IfcBuildingElement, IfcWallStandardCase, or IfcProxy is internally inconsistent and is rejected by a strict importer.
• ALWAYS keep each instance's GlobalId across the migration. Identity, change tracking, and federation depend on stable GUIDs.
• ALWAYS validate the migrated file before handing it downstream. "It opened in a viewer" is NOT proof of a correct migration.
• NEVER migrate by regex-renaming entity keywords : that handles renames only and leaves attribute lists misaligned and deleted entities un-remapped.
• NEVER assume a downgrade is lossless : the older schema is a subset.

Decision Trees

Migrate the schema, or convert the geometry?

What does the downstream tool need?
|
+-- A different IFC schema VERSION (it reads only IFC2x3, or needs IFC4.3)
|   --> schema-version migration : the subject of this skill
|
+-- A 3D mesh or a non-IFC file (OBJ, glTF/GLB, DAE, STEP, SVG)
    --> geometry/format conversion : use IfcConvert, NOT this workflow

Upgrade or downgrade?

Compare source and target version numbers.
|
+-- Target is NEWER (IFC2x3->IFC4, IFC4->IFC4.3)  --> UPGRADE
|   The newer schema is broadly a superset. Every source concept still has a
|   home : remap deleted/renamed names, fill new optional slots with $.
|   Information is rarely lost. This is the stable, preferred direction.
|
+-- Target is OLDER (IFC4.3->IFC4, IFC4->IFC2x3)  --> DOWNGRADE
    The older schema is a subset. Concepts with no equivalent (infrastructure
    entities, IfcFacility breakdown, tessellated and NURBS geometry) cannot
    be represented and are dropped or approximated. Best-effort and LOSSY.
    Flag the run lossy up front; re-validate the result.

ALWAYS prefer an upgrade path. The reference implementation states it directly: "Upgrading to IFC4 is more stable than downgrading to IFC2X3."

What is the fate of this entity? (Stage 1)

Look the source entity name up in the target schema's change log.
|
+-- Present, not flagged                 --> unchanged : keep the keyword
+-- Present under a new name             --> renamed : rewrite the keyword
+-- Present but marked deprecated        --> deprecated : keep or rewrite to
|                                            the recommended replacement
+-- Absent from the target schema        --> deleted : MUST remap to a
                                             surviving entity, and update
                                             every #id reference to it

Authoritative change-log sources : for IFC4 to IFC4.3, Appendix F ("Change Logs") of the IFC4.3 documentation plus the IFC4.3 introduction page. For IFC2x3 to IFC4, the IFC4 ADD2 TC1 specification and the per-entity version history blocks on the lexical pages.

Patterns

Pattern : the two-stage remap

1. For each source instance, resolve its entity fate (Stage 1). Rewrite renamed keywords ; choose a surviving target entity for every deleted keyword.
2. For each surviving instance, build the attribute map (Stage 2) against the TARGET entity's attribute list : append $ for new optional attributes, drop removed attributes and re-pack the remaining values, reorder where the sequence changed.
3. Account for DERIVED attributes. A DERIVED attribute is written * in the STEP record and occupies no settable slot. If an attribute changes between DERIVED and explicit across versions, the count of settable slots changes and every following value shifts. Verify each entity's derivation status in both schemas before copying its attribute list.

See references/methods.md for the verified entity and attribute changes, and references/examples.md for before/after STEP fragments.

Pattern : collapse the deleted *StandardCase family

The entire *StandardCase family (IfcWallStandardCase, IfcBeamStandardCase, IfcColumnStandardCase, IfcMemberStandardCase, IfcPlateStandardCase, IfcSlabStandardCase, IfcDoorStandardCase, IfcWindowStandardCase, IfcOpeningStandardCase) was deprecated in IFC4 and DELETED in IFC4.3. When migrating to IFC4.3, collapse every *StandardCase instance into its base entity (IfcWall, IfcBeam, IfcColumn, IfcMember, IfcPlate, IfcSlab, IfcDoor, IfcWindow, IfcOpeningElement). The "standard" semantics are then expressed by attaching an IfcMaterialLayerSetUsage through IfcRelAssociatesMaterial.

Pattern : apply the IFC4.3 hard renames

When the target is IFC4.3, rewrite every deleted/renamed name : IfcBuildingElement becomes IfcBuiltElement (in practice a concrete subtype, since IfcBuiltElement is abstract) ; IfcBuildingSystem becomes IfcBuiltSystem ; IfcProxy, IfcDoorStyle, IfcWindowStyle, and the *StandardCase family are removed. IfcCivilElement is deprecated, not deleted : it stays valid but is rewritten to a surviving entity in clean migrations.

Pattern : preserve identity and the reference graph

Every instance keeps its GlobalId, so element identity survives the migration. Every #id reference in the source must still resolve in the target : when a deleted entity is remapped, every record that pointed at it must be updated to point at the replacement. NEVER delete an entity without re-wiring its references ; a dangling #id fails validation.

Pattern : the mandatory validation gate

A migrated file is NOT trusted until validated. Run it through the buildingSMART validation pipeline : STEP syntax check, then schema check (version plus compliance), then normative rules. The schema compliance check catches exactly the failure modes a sloppy migration produces : wrong attribute types or cardinalities from a bad attribute map, instantiation of an entity the target schema does not define, dangling #id references, and use of a deleted entity. See ifc-core-validation for the pipeline.

Verified Version Changes

IFC2x3 to IFC4 (upgrade)

IFC4 to IFC4.3 (upgrade)

The full, authoritative IFC4 to IFC4.3 change log is Appendix F of the IFC4.3 documentation. NEVER assert a single deprecated-entity count : the release-notes page and the introduction page summarise the deprecation set differently. Cite Appendix F as the enumerated source.

Reference Links

• references/methods.md : the verified entity and attribute change catalogue, the entity-fate categories, the ifcpatch Migrate concept, source URLs.
• references/examples.md : before/after STEP fragments for the renames and the *StandardCase collapse, the 7-step strategy walkthrough, a downgrade loss example.
• references/anti-patterns.md : the migration mistakes that produce an invalid file, and why each one fails.

Related skills : ifc-core-version-evolution, ifc-errors-version-mismatch, ifc-core-validation, ifc-agents-migration-orchestrator, ifc-impl-format-transcoding.

Authoritative sources (see SOURCES.md) :

• IFC release notes : https://technical.buildingsmart.org/standards/ifc/ifc-schema-specifications/ifc-release-notes/
• IFC 4.3.2 specification and Appendix F : https://ifc43-docs.standards.buildingsmart.org/
• IFC 4 ADD2 TC1 specification : https://standards.buildingsmart.org/IFC/RELEASE/IFC4/ADD2_TC1/HTML/
• IFC 2x3 TC1 specification : https://standards.buildingsmart.org/IFC/RELEASE/IFC2x3/TC1/HTML/