| name | ifc-agents-migration-orchestrator |
| description | Use when asked to migrate an IFC file to another schema version, upgrade an IFC2x3 model to IFC4 or IFC4.3, downgrade an IFC4 model, or plan a schema-version conversion of an IFC dataset end to end. Prevents copying attributes blindly across a version boundary, silently dropping non-migratable entities, downgrading when an upgrade was the real goal, confusing geometry conversion with schema migration, and declaring a migration done without revalidating the result. Covers the migration workflow as an orchestration : source-schema detection, direction choice, the two-stage entity-then-attribute remap, the non-migratable-entity ledger, the ifcpatch Migrate recipe, and post-migration validation, across IFC2x3, IFC4 and IFC4.3. Keywords: IFC version migration, migrate IFC file, upgrade IFC2x3 to IFC4, IFC4 to IFC4.3, downgrade IFC, schema conversion, ifcpatch Migrate recipe, entity map, attribute map, IfcWallStandardCase deprecated, IfcBuildingElement renamed IfcBuiltElement, IfcBuildingSystem IfcBuiltSystem, non-migratable entity, data loss on migration, "convert my IFC file to IFC4", "which IFC version should I target", "migration dropped my data", how do I change the IFC schema version of a model.
|
| license | MIT |
| compatibility | Designed for Claude Code. Requires IFC IFC2x3, IFC4, IFC4.3. |
| metadata | {"author":"OpenAEC-Foundation","version":"1.0"} |
IFC Migration Orchestrator
Drive a complete schema-version migration of an IFC dataset. This is an
ORCHESTRATION skill : it sequences the migration workflow, detects the source
schema, plans the entity map and the attribute map, flags entities that cannot
be migrated, runs the conversion, and routes the result to post-migration
validation.
This skill answers one question : how is this model moved from its current IFC
schema version to a target version, and what is lost on the way. It does NOT
itself hold the entity-level rename and attribute detail : that is
ifc-impl-version-migration. It does NOT teach what changed between versions
and why : that is ifc-core-version-evolution. It is the conductor ; those two
skills are the score, and ifc-agents-file-validator is the final check.
Migration is inherently LOSSY and BEST-EFFORT. There is no official
buildingSMART document that prescribes a single correct migration path. ALWAYS
treat a migration as a planned, audited transformation, NEVER as a guaranteed
round-trip.
Quick Reference
The IFC version timeline
| Schema | Release | FILE_SCHEMA identifier | ISO status |
|---|
| IFC2x3 TC1 | 2007 (2.3.0.1) | IFC2X3 | ISO/PAS, then ISO 16739:2013 lineage |
| IFC4 ADD2 TC1 | (4.0.2.1) | IFC4 | ISO 16739:2013 / ISO 16739-1:2018 |
| IFC4.3 | IFC4.3.2 | IFC4X3_ADD2 (also seen as IFC4X3) | ISO 16739-1:2024 |
The validation service accepts IFC2X3, IFC4 and IFC4X3_ADD2. ALWAYS read
the FILE_SCHEMA entry in the STEP header to learn the source schema ; NEVER
infer the version from the entities used.
Migration is a two-stage remap
A schema-version migration is ALWAYS two stages, in this order :
- Entity map : map each source entity to its target-version equivalent.
Handles renames, deprecations and deletions.
- Attribute map : for each mapped entity, map its attributes. Handles
attributes that were added, removed, reordered, or that differ in their
DERIVED versus explicit status between versions.
NEVER collapse the two stages into a blind attribute copy : an attribute at
position N in the source entity is not guaranteed to be the same attribute at
position N in the target entity.
Migration is not geometry conversion
| Concern | Tool | What it does |
|---|
| Schema-version migration | ifcpatch Migrate recipe (IfcOpenShell) | Re-maps entities and attributes to a target IFC schema. Experimental. |
| Geometry export | IfcConvert (IfcOpenShell) | Converts IFC geometry to OBJ, glTF, etc. NOT a schema migration. |
ALWAYS use the ifcpatch Migrate recipe for a schema-version change. NEVER use
IfcConvert for it : IfcConvert produces a geometry file, not a migrated IFC
model.
Upgrade over downgrade
ALWAYS prefer an UPGRADE (older schema to newer) over a DOWNGRADE. Upgrading to
IFC4 is more stable than downgrading to IFC2x3 : a newer schema is a superset in
most areas, so an upgrade adds capability while a downgrade must discard the
entities and attributes the older schema lacks. ONLY downgrade when a receiving
system genuinely cannot read the newer schema, and ALWAYS record the discarded
data in the migration report.
Decision Trees
Tree A : "Migrate this IFC file to version X"
A migration is requested.
|
+-- Step 1 : Detect the source schema from FILE_SCHEMA in the STEP header.
| Source schema unknown or unreadable -> STOP. Fix the header first
| (route to ifc-errors-encoding-issues). No migration without a known source.
|
+-- Step 2 : Confirm the target schema and the direction.
| Target newer than source -> UPGRADE (preferred).
| Target older than source -> DOWNGRADE. Confirm with the user WHY a
| downgrade is needed (see Tree B). Warn that data will be discarded.
| Target equals source -> no migration needed. STOP.
|
+-- Step 3 : Plan the entity map. For every distinct entity type in the source,
| resolve its target-version status against the official change log
| (Appendix F of the IFC4.3 documentation) : unchanged, renamed, deprecated,
| or deleted. Hand the detail to ifc-impl-version-migration.
|
+-- Step 4 : Plan the attribute map. For every mapped entity, resolve attribute
| additions, removals, reordering, and DERIVED-versus-explicit differences.
|
+-- Step 5 : Build the non-migratable ledger. List every source entity with no
| target equivalent. NEVER drop one silently.
|
+-- Step 6 : Execute the migration with the ifcpatch Migrate recipe, target
| schema as argument.
|
+-- Step 7 : Validate the migrated file. Route to ifc-agents-file-validator and
| run the full five-stage pipeline against the TARGET schema.
|
+-- Step 8 : Report. Deliver the migration report : direction, entity map
summary, attribute hazards handled, non-migratable ledger, validation
verdict.
Tree B : Decide the direction
A target version is being chosen.
|
+-- Is the goal to use newer capability, or to satisfy a modern receiver?
| -> UPGRADE to the newest schema the receiver accepts. Preferred path.
|
+-- Is the goal forced by a receiver that only reads an older schema?
| -> DOWNGRADE, but ONLY this far : the newest schema the receiver accepts.
| -> ALWAYS produce the non-migratable ledger first, so the user sees what
| the downgrade discards BEFORE it runs.
|
+-- Is the source already the version the receiver wants?
-> No migration. Validate as-is and STOP.
Patterns
Pattern 1 : Detect the source schema before anything else
ALWAYS read FILE_SCHEMA from the STEP HEADER section first. It is the single
authoritative statement of the source schema, for example
FILE_SCHEMA(('IFC2X3')); or FILE_SCHEMA(('IFC4'));.
NEVER guess the version from the entities present : a file using only entities
common to several versions gives no version signal, and a file with a wrong
FILE_SCHEMA is a header fault to fix (route to ifc-errors-encoding-issues),
not a migration input to assume around. If the header and the entities
disagree, STOP and resolve the disagreement before migrating.
Pattern 2 : Run the two-stage entity-then-attribute remap
ALWAYS plan the entity map fully before the attribute map. The attribute map
depends on knowing the target entity.
Known transformation classes the orchestrator ALWAYS checks against the change
log (ifc-impl-version-migration holds the full matrix) :
- Rename : the entity exists under a new name.
IfcBuildingElement
(IFC2x3, IFC4) is renamed IfcBuiltElement in IFC4.3, and is non-abstract in
IFC4.3. A rename is a hard, file-breaking change : the old name is unknown in
the target schema.
- Deprecation : the entity still exists in the target but is flagged for
removal.
IfcWallStandardCase carries "DEPRECATED This definition will be
removed in a future major release" ; the migration target SHOULD be IfcWall
with an IfcMaterialLayerSetUsage. IfcBuildingSystem carries
"IFC4.3.0.0-DEPRECATION Use IfcBuiltSystem instead." IfcCivilElement is
deprecated in IFC4.3.
- Deletion : the entity does not exist in the target at all. It MUST be
re-expressed with a different entity or recorded as non-migratable.
For the attribute map, the key hazard is a DERIVED attribute. IfcSIUnit.Dimensions
is a DERIVED attribute in IFC2x3 and in IFC4.3 (computed by the schema function
IfcDimensionsForSIUnit). A DERIVED attribute is never stored : its STEP slot
holds *. A migrator that copies attribute slots positionally and writes a
literal into a derived slot produces a malformed line. ALWAYS preserve the *
token in a derived slot ; NEVER copy a value into it.
Pattern 3 : Build the non-migratable ledger, never drop silently
Some source entities have no target equivalent. A rarely-used representation
entity such as IfcAnnotationFillAreaOccurrence cannot be migrated by the
reference tool at all. ALWAYS list every such entity in a non-migratable ledger
with : the entity type, how many instances, and what data is lost.
NEVER let a migration discard an entity without recording it. A silent drop
turns a lossy-but-known migration into an undetectable data loss. The ledger is
a required section of the migration report (Pattern 6).
Pattern 4 : Prefer upgrade, downgrade only on a hard constraint
ALWAYS upgrade unless a receiving system cannot read the newer schema. An
upgrade adds the target schema's new entities and predefined types as available
capability and rarely discards data. A downgrade MUST discard every entity and
attribute the older schema lacks, for example the 62 occurrence entities and
294 predefined types added for infrastructure in IFC4.3.
When a downgrade is unavoidable : downgrade to the NEWEST schema the receiver
accepts, never further ; produce the non-migratable ledger BEFORE running it ;
and get explicit user confirmation of the discarded data.
Pattern 5 : Validate the migrated file against the target schema
A migration is NEVER complete at the moment the converter finishes. ALWAYS
route the migrated file to ifc-agents-file-validator and run the full
five-stage validation pipeline against the TARGET schema.
A migration can produce a file that is valid against neither schema : entities
half-mapped, attributes in the wrong slot, derived slots filled. ALWAYS treat a
post-migration validation failure as a migration defect, NEVER as a pre-existing
fault. NEVER report a migration as successful while the migrated file is
non-conformant.
Pattern 6 : The migration report
A migration ALWAYS ends with a structured report, never a verdict word. ALWAYS
produce these sections :
- Header : file name, source schema, target schema, direction.
- Entity map summary : counts of unchanged, renamed, deprecated-and-remapped,
and deleted-and-re-expressed entity types.
- Attribute hazards handled : DERIVED-slot cases and reordered-attribute cases.
- Non-migratable ledger : every entity with no target equivalent, instance
count, and data lost.
- Validation verdict : the
ifc-agents-file-validator result on the migrated
file against the target schema.
- Next actions : any manual re-authoring the ledger requires.
A worked report is in references/examples.md.
Version Notes
IfcBuildingElement (IFC2x3, IFC4) is renamed IfcBuiltElement in IFC4.3
and made non-abstract. Any upgrade to IFC4.3 MUST apply this rename ; any
downgrade from IFC4.3 MUST reverse it.IfcWallStandardCase and the *StandardCase family are deprecated. ALWAYS
verify each *StandardCase entity's exact status per target version against
the change log : deprecation and deletion did not all happen in one release.IfcBuildingSystem is deprecated in IFC4.3 in favour of IfcBuiltSystem ;
IfcCivilElement is deprecated in IFC4.3.- The
ifcpatch Migrate recipe is documented as EXPERIMENTAL and "will try to
preserve as much data as possible." ALWAYS pair it with Pattern 5 validation ;
NEVER trust its output unverified.
- The authoritative per-version change log is Appendix F ("Change Logs") of the
official IFC4.3 documentation. ALWAYS resolve a specific entity or attribute
against it rather than assuming.
Reference Links
references/methods.md : the migration workflow step by step, the ifcpatch
Migrate recipe invocation, the schema-identifier table, and the entity-status
classes with their change-log lookup procedure.references/examples.md : a worked IFC2x3-to-IFC4 upgrade run and a worked
migration report.references/anti-patterns.md : mistakes in the migration PROCESS itself.
Official sources (see SOURCES.md) :
