ifc-impl-version-migration

name	ifc-impl-version-migration
description	Use when migrating an IFC model between schema versions (IFC2x3, IFC4, IFC4.3) and the migrated file fails schema validation, opens with shifted or corrupt attributes, or still contains entities the target schema deleted. Prevents blind positional attribute copying, regex find-and-replace migration, leaving deleted entities in the file, confusing geometry conversion with schema migration, and trusting an unvalidated result. Covers the two-stage entity-then-attribute remap, the verified IFC2x3 to IFC4 and IFC4 to IFC4.3 entity and attribute changes, upgrade versus downgrade asymmetry, identity preservation, and the mandatory validation gate. Keywords: IFC version migration, schema migration, IFC2x3 to IFC4, IFC4 to IFC4.3, FILE_SCHEMA, IfcBuildingElement IfcBuiltElement rename, StandardCase removed, IfcProxy deleted, entity mapping, attribute mapping, ifcpatch Migrate, IfcConvert, upgrade downgrade, migrated file invalid, attributes shifted after migration, how do I convert IFC version, why does my migrated IFC not validate, entity does not exist in target schema.
license	MIT
compatibility	Designed for Claude Code. Requires IFC IFC2x3, IFC4, IFC4.3.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

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)

Fate	Meaning	Migrator action
Unchanged	same name in target schema	keep the entity keyword
Renamed	concept survives, name changes	rewrite the entity keyword
Deprecated	exists in target but marked for removal	keep, or rewrite to the recommended replacement
Deleted	does not exist in target at all	MUST remap to a surviving entity

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

Operation	Changes	Tool concept
Schema-version migration	the IFC schema version ; output is still an IFC file	ifcpatch Migrate
Geometry / format conversion	the file format ; output is OBJ, glTF, DAE, STEP, SVG	IfcConvert

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)

Change	Detail	Migrator action
*StandardCase deprecated	IfcWallStandardCase and siblings marked "DEPRECATED ... removed in a future major release"	keep (still valid), or rewrite to the base entity plus IfcMaterialLayerSetUsage
IfcMonetaryUnit.Currency	type changed from IfcCurrencyEnum to IfcLabel	convert the enum token to a string (an ISO 4217 code such as EUR, USD)
IfcSpace.InteriorOrExteriorSpace	attribute removed in IFC4	drop the slot ; interior/exterior moves to PredefinedType and Pset_SpaceCommon.IsExternal

IFC4 to IFC4.3 (upgrade)

Change	Detail	Migrator action
IfcBuildingElement deleted	renamed to IfcBuiltElement (abstract)	rewrite occurrences to a concrete subtype keyword
IfcBuildingSystem deprecated	replaced by IfcBuiltSystem	rewrite to IfcBuiltSystem
IfcCivilElement deprecated	still exists, not deleted	keep, or rewrite to a surviving entity
*StandardCase family deleted	the whole family is gone	collapse into the base entity
IfcProxy deleted	gone in IFC4.3	remap to a surviving entity
IfcDoorStyle / IfcWindowStyle deleted	style mechanism reworked	remap into the IfcDoorType / IfcWindowType model
IfcCountMeasure	defined type changed from NUMBER to INTEGER	coerce count values to integers
IfcGridPlacement	documented structural change	remap the placement structure

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/