| 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
- For each source instance, resolve its entity fate (Stage 1). Rewrite renamed
keywords ; choose a surviving target entity for every deleted keyword.
- 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.
- 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) :
