# Ifc Errors Version Mismatch

> Use when an IFC file fails validation because the declared FILE_SCHEMA does not match the entities used, when a file written for one schema is read with another schema's expectations, or when a model uses an entity that is deprecated or removed for its declared version. Prevents writing IfcBuildingElement into an IFC4.3 file, declaring IFC4 in the header while using IFC2x3-only entities, assuming OwnerHistory is mandatory in IFC4, copying DERIVED attribute slots blindly during migration, and treating a legacy IfcMaterialList as a hard error. Covers the FILE_SCHEMA token per version, the hard renames between IFC2x3, IFC4 and IFC4.3, deprecated and removed entities per version, attribute optionality and type changes across versions, the DERIVED attribute asterisk trap, and how to detect version inconsistency in an existing file. Keywords: IFC version mismatch, FILE_SCHEMA, IFC2X3, IFC4, IFC4X3_ADD2, deprecated entity, removed entity, IfcBuildingElement, IfcBuiltElement, IfcWallStandardCase, StandardCase removed

- Skill: `impertio-studio/ifc-errors-version-mismatch` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add impertio-studio/ifc-errors-version-mismatch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/impertio-studio/ifc-errors-version-mismatch/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-errors-version-mismatch

---


# IFC Version Mismatch

A version mismatch is when the IFC schema a file claims (its `FILE_SCHEMA`
header) disagrees with the schema the file's entities and attributes actually
belong to. The file is then internally inconsistent: a validator rejects it, or
a reader silently misinterprets it.

ALWAYS treat the declared `FILE_SCHEMA` token as a contract. Every entity name,
attribute slot, attribute optionality and enum value in the file MUST be legal
for that exact schema.

## Quick Reference

### FILE_SCHEMA token per version

| Version | `FILE_SCHEMA` token | ISO |
|---------|---------------------|-----|
| IFC2x3 TC1 | `('IFC2X3')` | ISO/PAS 16739:2005 |
| IFC4 ADD2 TC1 | `('IFC4')` | ISO 16739-1:2018 |
| IFC4.3 ADD2 | `('IFC4X3_ADD2')` | ISO 16739-1:2024 |

The IFC4.3 token tracks the exact release: the current ISO 16739-1:2024 schema
identifier is `IFC4X3_ADD2`. Earlier IFC4.3 development builds emitted `IFC4X3`.
ALWAYS verify the token against the schema identifier of the target release.

### Hard renames (a wrong name fails validation)

| IFC2x3 / IFC4 name | IFC4.3 name | Note |
|--------------------|-------------|------|
| `IfcBuildingElement` | `IfcBuiltElement` | renamed AND made non-abstract in IFC4.3 |
| `IfcBuildingSystem` | `IfcBuiltSystem` | `IfcBuildingSystem` deprecated in IFC4.3 |

| IFC2x3 attribute | IFC4+ attribute | Entity |
|------------------|-----------------|--------|
| `Location` | `Specification` | `IfcClassification` (renamed in IFC4.3) |
| `InteriorOrExteriorSpace` | (removed) | `IfcSpace`, see Pattern 3 |

### Attribute and type changes

| Item | IFC2x3 | IFC4 / IFC4.3 |
|------|--------|---------------|
| `IfcRoot.OwnerHistory` | mandatory | OPTIONAL (changed in IFC4) |
| `IfcMonetaryUnit.Currency` | `IfcCurrencyEnum` | `IfcLabel` (changed in IFC4) |
| `IfcSIUnit.Dimensions` | DERIVED | DERIVED (unchanged, see Pattern 4) |

### Symptom to cause

| Symptom | Likely cause |
|---------|--------------|
| "Unknown entity type" / "entity not in schema" | entity removed or renamed for declared schema |
| Validator: abstract entity instantiated | `IfcBuiltElement` used directly in IFC4.3 (it is non-abstract there, but still typically wrong) |
| Reader drops OwnerHistory or crashes on missing it | IFC2x3 reader assumptions applied to IFC4 file |
| Currency reads as blank or enum error | `IfcCurrencyEnum` value in an IFC4 file |
| Attribute values shifted by one slot | DERIVED slot mis-handled during migration |
| File rejected before any element check | `FILE_SCHEMA` token unparseable or unknown |

## Decision Trees

### Is this file's version self-consistent?

```
Read FILE_SCHEMA token from the STEP header
  |
  +-- token is IFC2X3 / IFC4 / IFC4X3_ADD2 ?
  |     NO  -> unknown schema. Reader cannot load. Fix the token first.
  |     YES -> continue
  |
  +-- any entity name not legal in that schema ?
  |     IfcBuiltElement in IFC2X3/IFC4 file        -> MISMATCH (use IFC4.3 or rename)
  |     IfcBuildingElement subtype in IFC4X3 file  -> check: subtypes still valid,
  |     |                                             only the supertype was renamed
  |     *StandardCase entity in a schema that removed it -> MISMATCH
  |     YES -> MISMATCH. Fix entity or fix declared schema.
  |     NO  -> continue
  |
  +-- any attribute count / optionality wrong for that schema ?
  |     mandatory OwnerHistory missing in IFC2X3   -> MISMATCH
  |     IfcCurrencyEnum value in IFC4 file         -> MISMATCH
  |     YES -> MISMATCH
  |     NO  -> file is version-consistent
```

### Which schema should I declare?

```
Does the model use infrastructure entities (rail, road, alignment, earthworks) ?
  YES -> IFC4.3 (IFC4X3_ADD2). No earlier schema has them.
  NO  -> continue

Does the model use tessellation, NURBS, IfcMaterialConstituentSet, or
       IfcMapConversion ?
  YES -> IFC4 minimum. NEVER declare IFC2x3.
  NO  -> continue

Is the receiving software IFC2x3-only ?
  YES -> declare IFC2x3 AND downgrade entities (see Pattern 5). Downgrade is lossy.
  NO  -> declare IFC4. IFC4 is the safe modern default for building models.
```

### Upgrade or downgrade?

```
ALWAYS prefer upgrade (older -> newer) over downgrade.
  Upgrade  : renames + new optional attributes. Mostly mechanical.
  Downgrade: must drop entities the target schema lacks. Always lossy.

Target schema decided ?
  +-- map every source entity to a target-version entity   (entity map)
  +-- map every attribute slot, honouring added/removed/DERIVED (attribute map)
  +-- entity with no target equivalent ? -> drop it, log it. NEVER fabricate one.
  +-- re-validate the result against the buildingSMART pipeline.
```

## Patterns

### Pattern 1: FILE_SCHEMA must match the entities used

The declared schema is a contract. An IFC4.3-declared file that instantiates
`IfcBuildingElement` is internally inconsistent and fails validation, because
`IfcBuildingElement` does not exist in IFC4.3 (it was renamed to
`IfcBuiltElement`).

ALWAYS pick the schema first, then use only that schema's vocabulary.
NEVER change the `FILE_SCHEMA` token to "fix" a validation error without
checking that every entity is legal for the new token: relabelling the header
does not migrate the body.

```
ISO-10303-21;
HEADER;
FILE_DESCRIPTION(('ViewDefinition [ReferenceView_V1.2]'),'2;1');
FILE_NAME('example.ifc','2026-05-20T00:00:00',(''),(''),'','','');
FILE_SCHEMA(('IFC4'));          /* contract: IFC4 vocabulary only */
ENDSEC;
DATA;
/* every entity below MUST be an IFC4 entity */
ENDSEC;
END-ISO-10303-21;
```

### Pattern 2: deprecated and removed entities per declared schema

Three states, distinct consequences:

- **Removed**: the entity does not exist in the schema. Using it is a hard
  validation failure ("unknown entity type"). Example: `IfcBuildingElement` in
  any IFC4.3 file.
- **Deprecated**: the entity still exists and still validates, but MUST NOT be
  exported by new software. Example: `IfcWallStandardCase` (deprecated in IFC4,
  status changed in 4.0.2.1: "This definition may be imported, but shall not be
  exported by applications"). Example: `IfcMaterialList` ("IFC4-CHANGE The
  entity IfcMaterialList is deprecated and shall no longer be used"), and
  `IfcBuildingSystem` in IFC4.3 ("IFC4.3.0.0-DEPRECATION Use IfcBuiltSystem
  instead"), and `IfcCivilElement` in IFC4.3.
- **Renamed**: the old name is gone, a new name exists. The body of the file
  must use the new name. Example: `IfcBuildingElement` -> `IfcBuiltElement`.

ALWAYS treat a deprecated entity in an existing file as a WARNING, not a hard
error: the file still validates. NEVER write a deprecated entity into a newly
authored file.

The `*StandardCase` pattern (`IfcWallStandardCase`, `IfcBeamStandardCase`,
`IfcColumnStandardCase`, `IfcSlabStandardCase`, and siblings) was deprecated and
then removed across the IFC4.x line. ALWAYS replace a `*StandardCase` element
with its plain base entity (`IfcWall`, `IfcBeam`, `IfcColumn`, `IfcSlab`) plus
the appropriate material or profile usage. See `references/methods.md` for the
full per-version inventory.

### Pattern 3: reading an IFC2x3 file with IFC4 expectations

A reader tuned for IFC4 makes assumptions that break on an IFC2x3 file, and the
reverse.

- **OwnerHistory optionality**: in IFC2x3 `IfcRoot.OwnerHistory` is mandatory;
  in IFC4 and IFC4.3 it is OPTIONAL ("IFC4-CHANGE The attribute has been changed
  to be OPTIONAL"). A reader that assumes `OwnerHistory` is always present
  crashes on a valid IFC4 file. A writer that omits `OwnerHistory` from an
  IFC2x3 file produces an invalid file.
- **Material structures**: IFC2x3 uses `IfcMaterialList`. IFC4 introduced
  `IfcMaterialConstituentSet` and consolidated material-property subtypes
  (`IfcMechanicalMaterialProperties` and siblings) into `IfcMaterialProperties`.
  A reader expecting `IfcMaterialConstituentSet` finds none in an IFC2x3 file.
- **IfcSpace classification**: IFC2x3 `IfcSpace` carries
  `InteriorOrExteriorSpace` (`IfcInternalOrExternalEnum`). IFC4 removed that
  attribute; an IFC4 `IfcSpace` uses `PredefinedType` (`IfcSpaceTypeEnum`) and
  the `IsExternal` property in `Pset_SpaceCommon`. A reader looking for
  `InteriorOrExteriorSpace` in an IFC4 file finds nothing.
- **Currency**: IFC2x3 `IfcMonetaryUnit.Currency` is `IfcCurrencyEnum`; IFC4
  changed it to `IfcLabel` (a free ISO 4217 string such as `EUR`). An enum
  literal in an IFC4 file is a type error.

ALWAYS branch reader logic on the `FILE_SCHEMA` token before assuming an
attribute is present, mandatory, or of a given type.

### Pattern 4: the DERIVED attribute asterisk trap

A DERIVED attribute is computed from other attributes and is NEVER stored in
the file: it serializes as an asterisk `*` placeholder that holds its slot
position. `IfcSIUnit.Dimensions` is the canonical example. It is DERIVED in
IFC2x3, IFC4 and IFC4.3 alike (the official specification gives
`Dimensions := IfcDimensionsForSiUnit(SELF.Name)` in every version). It always
serializes as `*`:

```
#10 = IFCSIUNIT(*, .LENGTHUNIT., $, .METRE.);
/*          ^ Dimensions = DERIVED -> always *                        */
/*               ^ UnitType    ^ Prefix (unset = $)   ^ Name           */
```

The trap during migration: a migrator that copies attribute slots positionally
must keep `*` in every DERIVED slot. If it copies a literal value into a DERIVED
slot, or drops the slot entirely, every following attribute shifts by one
position and the entity is silently corrupted.

ALWAYS keep `*` for a DERIVED slot when copying an entity between schemas.
NEVER assume `IfcSIUnit.Dimensions` switched between DERIVED and explicit
between versions: per the official specification it is DERIVED in all three.

### Pattern 5: detecting version inconsistency in an existing file

To audit a file you did not write:

1. Read the `FILE_SCHEMA` token. If it is not `IFC2X3`, `IFC4`, or an `IFC4X3`
   identifier, the file cannot be loaded against a known schema.
2. Scan every entity name. Flag any name not present in the declared schema:
   `IfcBuiltElement` in an `IFC2X3`/`IFC4` file, a `*StandardCase` entity in a
   schema that removed it, an infrastructure entity in a pre-IFC4.3 file.
3. Check attribute optionality: a missing `OwnerHistory` in an `IFC2X3` file is
   a hard error; in `IFC4` it is legal.
4. Check enum-vs-label slots: an `IfcMonetaryUnit` carrying an enum literal in
   an `IFC4` file is a type mismatch.
5. Classify each finding: removed entity = error, deprecated entity = warning,
   renamed entity = error if the old name appears.

See `references/examples.md` for a runnable detection checklist and
`references/anti-patterns.md` for the failure cases in full.

## Reference Links

- `references/methods.md` : FILE_SCHEMA tokens, the full rename and
  deprecation inventory per version, attribute-change signatures.
- `references/examples.md` : verified STEP snippets, consistent versus
  inconsistent headers, the detection checklist.
- `references/anti-patterns.md` : every version-mismatch failure mode, what
  breaks, and why.

Cross-references:

- `ifc-core-version-evolution` : the full version ledger and what each release
  added.
- `ifc-impl-version-migration` : the step-by-step migration workflow.
- `ifc-errors-schema-validation` : abstract-entity and WHERE-rule errors.
- `ifc-agents-migration-orchestrator` : orchestrated full-schema migration.

Official sources (verify before asserting any entity or attribute):

- IFC4.3 specification: https://ifc43-docs.standards.buildingsmart.org/
- IFC4 ADD2 TC1: https://standards.buildingsmart.org/IFC/RELEASE/IFC4/ADD2_TC1/HTML/
- IFC2x3 TC1: https://standards.buildingsmart.org/IFC/RELEASE/IFC2x3/TC1/HTML/
- IFC release notes: https://technical.buildingsmart.org/standards/ifc/ifc-schema-specifications/ifc-release-notes/