| name | ifc-errors-version-mismatch |
| description | 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, OwnerHistory optional, IfcMaterialList, IfcSIUnit Dimensions DERIVED, schema downgrade, schema upgrade, "entity not in schema", "unknown entity type", "file rejected by validator", "wrong IFC version", "why does my IFC fail validation", how do I migrate IFC version, what schema is my IFC file.
|
| license | MIT |
| compatibility | Designed for Claude Code. Requires IFC IFC2x3,IFC4,IFC4.3. |
| metadata | {"author":"OpenAEC-Foundation","version":"1.0"} |
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:
- Read the
FILE_SCHEMA token. If it is not IFC2X3, IFC4, or an IFC4X3
identifier, the file cannot be loaded against a known schema.
- 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.
- Check attribute optionality: a missing
OwnerHistory in an IFC2X3 file is
a hard error; in IFC4 it is legal.
- Check enum-vs-label slots: an
IfcMonetaryUnit carrying an enum literal in
an IFC4 file is a type mismatch.
- 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):
