ifc-agents-migration-orchestrator

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 :

1. Entity map : map each source entity to its target-version equivalent. Handles renames, deprecations and deletions.
2. 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 :

1. Header : file name, source schema, target schema, direction.
2. Entity map summary : counts of unchanged, renamed, deprecated-and-remapped, and deleted-and-re-expressed entity types.
3. Attribute hazards handled : DERIVED-slot cases and reordered-attribute cases.
4. Non-migratable ledger : every entity with no target equivalent, instance count, and data lost.
5. Validation verdict : the ifc-agents-file-validator result on the migrated file against the target schema.
6. 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) :

• IFC 4.3 specification and Appendix F change logs : 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/
• ifcpatch Migrate recipe : https://docs.ifcopenshell.org/autoapi/ifcpatch/recipes/Migrate/index.html
• buildingSMART validation service : https://validate.buildingsmart.org/