# Ifc Impl Version Migration

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

- Skill: `impertio-studio/ifc-impl-version-migration` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add impertio-studio/ifc-impl-version-migration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/impertio-studio/ifc-impl-version-migration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: Impertio-Studio (https://skillmd.com/u/impertio-studio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/impertio-studio/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)

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