# Ifc Agents Migration Orchestrator > 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- - Skill: `impertio-studio/ifc-agents-migration-orchestrator` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add impertio-studio/ifc-agents-migration-orchestrator` - Raw SKILL.md: https://api.skillmd.com/api/skills/impertio-studio/ifc-agents-migration-orchestrator/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-agents-migration-orchestrator --- # 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/