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

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)

Attribute and type changes

Symptom to cause

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/