ifc-errors-schema-validation

name	ifc-errors-schema-validation
description	Use when an IFC file fails schema validation or a buildingSMART validation report shows errors, and the cause is a WHERE-rule break, a global-rule break, an abstract-entity instantiation, a cardinality violation, or a wrong attribute type. Prevents instantiating an abstract supertype, calling an IFC4.3 IfcBuiltElement instantiation a schema error, ignoring the warning-vs-error distinction, and reading a validation report as if hidden passes were missing checks. Covers EXPRESS WHERE rules and global RULEs, abstract supertypes per version, attribute cardinality and type errors, the buildingSMART validation pipeline and its severities, the Gherkin normative-rule layer, running a single Gherkin rule locally, and Implementer Agreements versus Informal Propositions. Keywords: IFC schema validation, WHERE rule violation, global rule, abstract entity, IfcBuildingElement, IfcBuiltElement, cardinality, wrong attribute type, buildingSMART validation service, Gherkin rules, implementer agreement, informal proposition, "file is invalid", "validation failed", "schema error", "cannot instantiate", "warning vs error", how do I fix an invalid IFC file, why does my IFC file fail validation.
license	MIT
compatibility	Designed for Claude Code. Requires IFC IFC2x3, IFC4, IFC4.3.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

IFC Schema Validation Errors

Diagnose and fix the errors raised by IFC schema validation : EXPRESS WHERE and global RULE violations, instantiation of abstract entities, cardinality and attribute-type errors, and the normative Gherkin-rule layer. Also : how to read a buildingSMART validation report without misinterpreting it.

For the validation MODEL (the conceptual three-tier hierarchy) see ifc-core-validation. For STEP syntax and character-encoding errors see ifc-errors-encoding-issues. For deprecated-entity errors see ifc-errors-version-mismatch.

Quick Reference

The validation pipeline (buildingSMART validation service)

Stage	Checks	Failure severity
1. STEP Syntax	ISO 10303-21 file structure, header, escaping	error (file rejected)
2. Schema : version check	schema id is IFC2X3, IFC4, or IFC4X3_ADD2	error
2. Schema : compliance check	attribute types, cardinalities, inverse cardinalities, WHERE rules, global rules, abstract instantiation	error
3. Normative : Implementer Agreements	ratified normative Gherkin rules	error
3. Normative : Informal Propositions	mandatory rules not yet ratified as agreements	error
4. Industry Practice	common-practice, sensible-default checks	warning only
5. bSDD Compliance	classification / property alignment with bSDD	error or warning

This skill covers stages 2 and 3. Stage 1 is ifc-errors-encoding-issues.

Outcome severities

pass, warning, error, not applicable, disabled. ALWAYS treat them precisely:

• error invalidates the file. The file is non-conformant.
• warning does NOT invalidate the file. Industry-practice checks only warn.
• pass results are HIDDEN by default in the report. A check absent from the visible report passed ; it was NOT skipped.

Core rules

• An entity whose EXPRESS declaration begins ABSTRACT SUPERTYPE OF MUST NEVER be instantiated. ALWAYS instantiate a concrete leaf subtype.
• A WHERE rule constrains ONE entity instance. A global RULE constrains the whole population. ALWAYS read which one failed before fixing.
• ALWAYS run BOTH the EXPRESS-level checks (stage 2) AND the Gherkin normative checks (stage 3). EXPRESS validity alone does NOT make a file conformant.

Decision Trees

Which validation stage raised this

What does the report category say ?
├─ "STEP Syntax"            -> ISO 10303-21 ; see ifc-errors-encoding-issues
├─ "Schema" / "Compliance"  -> stage 2 ; this skill, Patterns 1 to 4
├─ "Implementer Agreement"  -> stage 3, ratified normative rule ; Pattern 6
├─ "Informal Proposition"   -> stage 3, mandatory unratified rule ; Pattern 6
├─ "Industry Practice"      -> warning only ; file stays valid
└─ "bSDD"                   -> classification/property check vs bSDD

Is this an error or only a warning

Severity of the finding ?
├─ error    -> file is non-conformant. MUST fix before the file is valid.
├─ warning  -> file is still valid. Fix for quality, not for conformance.
└─ pass     -> hidden by default. The check ran and succeeded. Do nothing.

WHERE rule or global rule

The failing rule's scope ?
├─ named on ONE entity (e.g. IfcWall.CorrectPredefinedType)
│   -> WHERE rule. Fix that single instance. Pattern 1.
└─ a schema-level RULE (e.g. IfcSingleProjectInstance)
    -> global RULE. Fix the population (count, uniqueness). Pattern 2.

Abstract-entity instantiation : version check

The instantiated entity is a supertype. Is it ABSTRACT in the file's schema ?
├─ IfcBuildingElement, file schema IFC2x3 or IFC4
│   -> ABSTRACT. Instantiation is a SCHEMA ERROR. Replace with a concrete subtype.
├─ IfcBuiltElement, file schema IFC4.3
│   -> NON-abstract (renamed from IfcBuildingElement, made non-abstract in
│      IFC4.3.0.0). Instantiation is schema-VALID. Prefer a concrete subtype for
│      quality, but NEVER report it as a schema error.
└─ IfcElement, IfcRoot, IfcObjectDefinition, IfcProduct, IfcObject (any version)
    -> ABSTRACT. Instantiation is a SCHEMA ERROR.

Patterns

Pattern 1 : fix a WHERE-rule violation

A WHERE rule is an entity-local boolean expression every instance must satisfy. The report names it as Entity.RuleName. Verified example, the IfcWall rule CorrectPredefinedType (IFC4, IFC4.3) :

WHERE
  CorrectPredefinedType : NOT(EXISTS(PredefinedType)) OR
    (PredefinedType <> IfcWallTypeEnum.USERDEFINED) OR
    ((PredefinedType = IfcWallTypeEnum.USERDEFINED) AND
     EXISTS (SELF\IfcObject.ObjectType));

This rule fails when PredefinedType = USERDEFINED but ObjectType is unset. To fix : either set ObjectType to the user-defined type name, or change PredefinedType to a non-USERDEFINED enum value. ALWAYS read the rule expression : it states the exact condition. NEVER guess the fix.

Pattern 2 : fix a global-rule violation

A global RULE constrains the whole instance population. Verified example, IfcSingleProjectInstance (IFC4, IFC4.3) :

RULE IfcSingleProjectInstance FOR (IfcProject);
  WHERE
    WR1 : SIZEOF(IfcProject) <= 1;
END_RULE;

This rule fails when a file contains more than one IfcProject. To fix : keep exactly one IfcProject and re-parent all spatial structure under it. Global rules are about counts and cross-instance uniqueness ; ALWAYS fix the population, NEVER a single instance in isolation.

Pattern 3 : fix abstract-entity instantiation

The schema forbids instantiating an ABSTRACT SUPERTYPE. The compliance check flags #id=IFCELEMENT(...) or, in IFC2x3 and IFC4, #id=IFCBUILDINGELEMENT(...).

To fix : replace the abstract entity with the concrete leaf subtype that matches the real object. A generic wall becomes IfcWall ; an unclassifiable physical element becomes IfcBuildingElementProxy, NOT the abstract supertype.

Version trap : IfcBuiltElement (IFC4.3) is NOT abstract. Instantiating IfcBuiltElement in an IFC4.3 file is schema-valid. NEVER carry the IFC4 "IfcBuildingElement is abstract" rule into IFC4.3 by renaming it ; verify the declaration for the ABSTRACT keyword in the file's actual schema.

Pattern 4 : fix a cardinality or attribute-type error

The compliance check verifies each attribute against its EXPRESS declaration:

• Cardinality : an aggregate SET [1:?] with zero members fails ; a LIST [2:3] with one member fails. A missing non-OPTIONAL attribute fails.
• Type : an attribute declared IfcLabel carrying an IfcInteger, or a reference pointing to the wrong entity type, fails.
• Inverse cardinality : an inverse declared SET [0:1] resolving to two forward references fails.

To fix : open the entity's EXPRESS declaration, read the exact type and bounds of the failing attribute, and correct the instance to match. ALWAYS supply every non-OPTIONAL attribute ; use $ only where the declaration says OPTIONAL.

Pattern 5 : read a buildingSMART validation report

1. Confirm the schema version check passed. If the schema id is unsupported,
   every later stage is meaningless.
2. Read ERROR findings first. Each error invalidates the file.
3. Read WARNING findings second. They do NOT invalidate the file.
4. A check that does not appear in the report PASSED (passes are hidden by
   default). NEVER read an absent check as skipped or missing.
5. Group errors by stage (schema vs normative) and fix stage 2 before stage 3 :
   a malformed instance can mask a normative finding.

Pattern 6 : run a single Gherkin normative rule locally

Normative rules that cannot be expressed in EXPRESS are Gherkin behaviour specs in buildingSMART/ifc-gherkin-rules. Each rule is a .feature file under features/rules/<PREFIX>/, classified by tags and a 3-letter functional-part prefix. Verified example, SPS001 :

@implementer-agreement
@SPS
Feature: SPS001 - Basic spatial structure for buildings
  Scenario: Agreement141 - maximum of one IfcSite
    Then There must be at most 1 instance(s) of .IfcSite.

To debug one rule against a file, run the rule by its code, for example python test/test_main.py alb001. ALWAYS check the rule tag : an @implementer-agreement failure is a ratified normative error ; an Informal Proposition is mandatory but not yet ratified. Both invalidate the file.

Reference Links

• references/methods.md : the five validation stages in detail, severity table, the abstract-entity list per version, the Gherkin functional-part prefixes.
• references/examples.md : concrete failing instances and their fixes.
• references/anti-patterns.md : validation mistakes and why each one is wrong.

Related skills

• ifc-core-validation : the conceptual three-tier validation model.
• ifc-syntax-express : WHERE rules, global RULEs, ABSTRACT, cardinality.
• ifc-errors-encoding-issues : stage-1 STEP syntax and escaping errors.
• ifc-errors-version-mismatch : deprecated and removed-entity errors.
• ifc-errors-broken-references : dangling #id and missing INVERSE links.
• ifc-agents-file-validator : the automated validation pipeline agent.

Verified sources

All entity declarations, rules, severities, and the Gherkin format verified 2026-05-20 via WebFetch against the buildingSMART sources in SOURCES.md : the IFC 4.3.2 and IFC4 ADD2 TC1 specifications, the validation service user guide, and the buildingSMART/ifc-gherkin-rules repository.