ifc-agents-file-validator

name	ifc-agents-file-validator
description	Use when asked to validate an IFC file, check whether an IFC model is conformant, run a pre-delivery quality gate on an IFC file, decide if an IFC file is valid, or triage a buildingSMART validation report. Prevents skipping the STEP-syntax gate, treating a warning as a file-invalidating error, reading a hidden pass as a skipped check, validating against the wrong schema, and confusing schema conformance with project information requirements. Covers the buildingSMART five-stage validation pipeline (STEP syntax, schema, normative, industry practice, bSDD), the Gherkin functional-part coverage map, the fifteen-item anti-pattern checklist, finding triage by severity, and routing each fault class to the matching ifc-errors skill, across IFC2x3, IFC4 and IFC4.3. Keywords: validate IFC file, is my IFC file valid, IFC validation pipeline, buildingSMART validation service, IFC conformance check, validation report triage, pre-delivery quality gate, schema validation, Gherkin normative rules, implementer agreement, informal proposition, industry practice warning, "is this IFC file ok", "how do I check an IFC file", "my IFC file failed validation", error vs warning, validation checklist, IFC quality gate, what makes an IFC file valid.
license	MIT
compatibility	Designed for Claude Code. Requires IFC IFC2x3, IFC4, IFC4.3.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

IFC File Validator (Orchestration)

Drive a complete, ordered validation pass over an IFC file. This is an ORCHESTRATION skill : it sequences the buildingSMART five-stage validation pipeline, walks the fifteen-item anti-pattern catalog, triages every finding by severity, and routes each fault class to the matching ifc-errors-* skill that holds the detailed fix.

This skill answers one question : is this IFC file conformant, and if not, where is the fault and which skill fixes it. It does NOT itself teach the fixes. It is the conductor ; the ifc-errors-* skills are the instruments.

Scope boundary : this skill checks SCHEMA CONFORMANCE (the file obeys the IFC standard). It does NOT check PROJECT INFORMATION REQUIREMENTS (the file carries the data a specific project demanded). Information completeness beyond schema conformance belongs to ifc-agents-quality-checker. Project requirements are expressed in IDS, which is out of this package scope. For the conceptual validation MODEL see ifc-core-validation.

Quick Reference

The five-stage validation pipeline

The buildingSMART validation service runs these stages in order. ALWAYS run them in this order : a later stage assumes the earlier one passed.

Stage	Checks	Failure severity	Routes to
1. STEP Syntax	ISO 10303-21 file structure, header, string escaping	error : file rejected	ifc-errors-encoding-issues
2. Schema : version	schema id is IFC2X3, IFC4, or IFC4X3_ADD2	error	ifc-errors-version-mismatch
2. Schema : compliance	attribute types, cardinalities, inverse cardinalities, WHERE rules, global rules, abstract instantiation	error	ifc-errors-schema-validation
3. Normative : Implementer Agreements	ratified Gherkin normative rules	error	the fault-specific ifc-errors-* skill
3. Normative : Informal Propositions	mandatory rules not yet ratified	error	the fault-specific ifc-errors-* skill
4. Industry Practice	common-practice, sensible-default checks	warning only	ifc-agents-quality-checker
5. bSDD Compliance	classification and property alignment with bSDD	error or warning	ifc-errors-property-set-mistakes

Stage 5 (bSDD) is temporarily DISABLED in the public validation service as of service version v0.6.6. ALWAYS report it as disabled, NEVER as pass.

Outcome severities

Five severities : pass, warning, error, not applicable, disabled.

• error invalidates the file. The file is non-conformant.
• warning does NOT invalidate the file. Industry-practice checks only warn.
• pass, not applicable and disabled results are HIDDEN by default in the report. ALWAYS read a check absent from the visible report as PASSED or not run, NEVER as a missing or skipped requirement.

Orchestration rules

• ALWAYS run stage 1 first. If STEP syntax fails, STOP : no later stage can run on a file that does not parse.
• ALWAYS confirm the declared schema version before stage 2 compliance : a compliance check is meaningless against the wrong schema.
• NEVER report a file as "valid" while any stage 1, 2, or 3 finding is an error. NEVER report a file as "invalid" when the only findings are stage 4 warning results.
• ALWAYS route each finding to the owning ifc-errors-* skill rather than improvising a fix here.

Decision Trees

Tree A : "Validate this IFC file"

A validation pass is requested on an IFC file.
|
+-- Stage 1 : Does the file parse as ISO 10303-21 STEP?
|   No : header malformed, string escaping broken, encoding wrong.
|     -> ERROR. STOP the pipeline. Route to ifc-errors-encoding-issues.
|        Report : file rejected before schema check.
|   Yes : continue.
|
+-- Stage 2a : Is FILE_SCHEMA one of IFC2X3, IFC4, IFC4X3_ADD2?
|   No, or it disagrees with the entities used.
|     -> ERROR. Route to ifc-errors-version-mismatch. Continue with the
|        version actually declared.
|
+-- Stage 2b : Schema compliance. Walk anti-patterns 3, 5, 6, 14, 15.
|   Abstract instantiation, WHERE-rule break, cardinality, wrong type,
|   deprecated entity, derived attribute set by hand.
|     -> Each is an ERROR. Route per the anti-pattern map (Pattern 2).
|
+-- Stage 3 : Normative Gherkin rules. Walk anti-patterns 1, 4, 7, 11, 12.
|   Missing spatial containment, geometry with no context, dangling
|   reference, MVD-inconsistent geometry, degenerate geometry.
|     -> Each is an ERROR. Route per the anti-pattern map.
|
+-- Stage 4 : Industry practice. Walk anti-patterns 8, 9.
|   Missing material association, missing project property sets.
|     -> WARNING only. The file stays valid. Route to
|        ifc-agents-quality-checker for the completeness audit.
|
+-- Stage 5 : bSDD. Report as disabled (service v0.6.6+).
|
+-- Aggregate : any stage 1 to 3 error -> file is NON-CONFORMANT.
      No error, warnings only -> file is CONFORMANT with warnings.

Tree B : "Triage a buildingSMART validation report"

A validation report is in hand and the question is what it means.
|
+-- Read the severity of each visible result.
|
+-- Any result with severity error?
|   Yes -> The file is non-conformant. List every error, route each to its
|          ifc-errors-* skill. The file is NOT deliverable.
|   No  -> continue.
|
+-- Only warning results visible?
|     -> The file IS conformant. Warnings are industry-practice advice. Decide
|        with the user whether to address them ; do not block delivery on them.
|
+-- A check the user expected is not in the report at all?
|     -> It passed (pass is hidden by default), or it is not applicable, or it
|        is disabled. NEVER read absence as "the checker skipped my file".
|
+-- The report says the file is valid but the user reports a real defect?
      -> The defect is a PROJECT INFORMATION gap, not a schema fault. Route to
         ifc-agents-quality-checker. Schema validity never proves completeness.

Patterns

Pattern 1 : Run the pipeline as a stop-on-syntax gate

ALWAYS treat the five stages as a gate, not a parallel scan.

1. Run stage 1 (STEP syntax). On any error, STOP and report. A file that does not parse cannot be schema-checked : reporting later-stage results would be fabricated.
2. Run stage 2 version check, then stage 2 compliance.
3. Run stage 3 normative checks (Implementer Agreements, then Informal Propositions).
4. Run stage 4 industry-practice checks. These never stop the pipeline.
5. Report stage 5 (bSDD) as disabled.
6. Aggregate : the file is conformant if and only if no stage 1 to 3 finding is an error.

The public validation service at https://validate.buildingsmart.org/ runs exactly this pipeline. When a file cannot be uploaded to the service, ALWAYS reproduce the same ORDER locally and state which stages were checked by which tool.

Pattern 2 : The fifteen-item anti-pattern checklist

ALWAYS walk all fifteen. Each maps to a pipeline stage and an owning skill. The full catalog with detection cues is in references/methods.md.

#	Anti-pattern	Stage	Owning skill
1	Missing spatial containment	3	ifc-errors-spatial-structure
2	Wrong unit assignment, model off by 1000x	2	ifc-errors-property-set-mistakes
3	Invalid or duplicated GlobalId	2	ifc-errors-schema-validation
4	Geometry without a representation context	3	ifc-errors-geometry-issues
5	Direct instantiation of an abstract entity	2	ifc-errors-schema-validation
6	Deprecated or removed entity for the schema	2	ifc-errors-version-mismatch
7	Broken reference or missing INVERSE link	2, 3	ifc-errors-broken-references
8	Broken or missing material association	4	ifc-errors-property-set-mistakes
9	Missing project-defined property sets	4	ifc-errors-property-set-mistakes
10	STEP encoding or header error	1	ifc-errors-encoding-issues
11	Geometry inconsistent with the declared MVD	3	ifc-errors-geometry-issues
12	Duplicated or degenerate geometry	3	ifc-errors-geometry-issues
13	Custom Pset using the reserved Pset_ prefix	2, 5	ifc-errors-property-set-mistakes
14	MaterialLayerSetUsage attached to a type object	2	ifc-errors-property-set-mistakes
15	Manually set derived TotalThickness	2	ifc-errors-property-set-mistakes

Items 1 to 12 are hard faults : 1, 4, 7, 11, 12 invalidate at stage 3 ; 3, 5, 6, 14, 15 invalidate at stage 2 ; 10 invalidates at stage 1. Items 8 and 9 are stage-4 warnings : real defects, but they do NOT invalidate the file.

Pattern 3 : The Gherkin functional-part coverage map

Stage 3 normative rules are buildingSMART Gherkin rules, grouped under three-letter functional-part prefixes. ALWAYS use the prefix to know which domain a rule code touches and which skill owns it.

Prefix	Functional part	Owning skill
PJS	Project definition (context, directory of objects)	ifc-errors-schema-validation
GRF	Georeferencing	ifc-errors-geometry-issues
BLT	Built elements (walls, slabs, columns)	ifc-errors-schema-validation
GEM	Geometry representation	ifc-errors-geometry-issues
OJP	Object placement	ifc-errors-geometry-issues
SPS	Spatial breakdown	ifc-errors-spatial-structure
MAT	Materials	ifc-errors-property-set-mistakes
PSE	Properties for objects	ifc-errors-property-set-mistakes
QTY	Quantities for objects	ifc-errors-property-set-mistakes
CLS	Classification reference	ifc-errors-property-set-mistakes
POR	Port connectivity and nesting	ifc-errors-broken-references

A rule code is its prefix plus a number, for example GEM051, SPS001. The prefix is the routing key. The full prefix list and detail are in references/methods.md.

Pattern 4 : Triage findings by severity

ALWAYS classify every finding into exactly one of three buckets before reporting.

• ERROR : a stage 1, 2, or 3 error. The file is non-conformant. It is NOT deliverable until fixed. Route to the owning skill.
• WARNING : a stage 4 industry-practice warning. The file is conformant. The warning is advice. Surface it, do not block on it.
• INFORMATIONAL : a pass, not applicable, or disabled result, usually hidden. It carries no action. NEVER escalate an informational result to a warning or error.

NEVER collapse the three buckets. Treating a warning as an error blocks a valid deliverable ; treating an error as a warning ships a broken file.

Pattern 5 : The validation report structure

A validation pass ALWAYS ends with a structured report, not a verdict word. ALWAYS produce these sections :

1. Header : file name, declared schema, declared MVD (from FILE_DESCRIPTION).
2. Verdict : CONFORMANT or NON-CONFORMANT, derived strictly from Pattern 1 step 6.
3. Errors : one row per error : stage, anti-pattern number, owning skill, one-line description.
4. Warnings : one row per industry-practice warning.
5. Not checked : stages and checks that were disabled or not applicable, stated explicitly so the reader never assumes silent coverage.
6. Next actions : the ordered list of owning skills to invoke.

A worked report is in references/examples.md.

Version Notes

• The validation pipeline, severities, and Gherkin rule layer apply to IFC2x3, IFC4 and IFC4.3 files. The validation service accepts schema identifiers IFC2X3, IFC4 and IFC4X3_ADD2.
• Gherkin rules carry version tags (for example @version2) and an MVD Background. ALWAYS check that a rule applies to the file's schema and MVD before treating its result as binding.
• Anti-pattern 6 (deprecated entities) is version-specific : IfcWallStandardCase and the *StandardCase family are removed after IFC4 ; IfcBuildingElement is renamed IfcBuiltElement in IFC4.3. Route version faults to ifc-errors-version-mismatch, which holds the rename matrix.
• Stage 5 (bSDD) is disabled in the public service as of v0.6.6. This is a service state, not a schema-version property.

Reference Links

• references/methods.md : the five-stage pipeline in full, the fifteen-item anti-pattern catalog with detection cues, the complete Gherkin functional-part prefix table, severity semantics, and how to run a single Gherkin rule.
• references/examples.md : a worked validation run and a worked report.
• references/anti-patterns.md : mistakes in the validation PROCESS itself.

Official sources (see SOURCES.md) :

• buildingSMART validation service : https://validate.buildingsmart.org/
• Validation service user guide : https://buildingsmart.github.io/validate/
• IFC Gherkin normative rules : https://github.com/buildingSMART/ifc-gherkin-rules
• IFC 4.3 specification : https://ifc43-docs.standards.buildingsmart.org/