| 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.
- 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.
- Run stage 2 version check, then stage 2 compliance.
- Run stage 3 normative checks (Implementer Agreements, then Informal
Propositions).
- Run stage 4 industry-practice checks. These never stop the pipeline.
- Report stage 5 (bSDD) as
disabled.
- 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 :
- Header : file name, declared schema, declared MVD (from
FILE_DESCRIPTION).
- Verdict : CONFORMANT or NON-CONFORMANT, derived strictly from Pattern 1
step 6.
- Errors : one row per error : stage, anti-pattern number, owning skill,
one-line description.
- Warnings : one row per industry-practice warning.
- Not checked : stages and checks that were
disabled or not applicable,
stated explicitly so the reader never assumes silent coverage.
- 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) :
