| name | ifc-errors-property-set-mistakes |
| description | Use when an IFC file fails validation on a property set, quantity set or material association, or when a custom property set is rejected, ignored, or collides with the standard library, or a layered-material assignment breaks a WHERE rule. Prevents naming a custom property set with the reserved Pset_ prefix, pointing IfcRelDefinesByProperties at a type object, attaching IfcMaterialLayerSetUsage to a type instead of an occurrence, hand-writing the derived TotalThickness, putting a length unit on an area quantity, and leaving IfcMaterialList in a new IFC4 file. Covers the Pset_ and Qto_ naming conventions, the NoRelatedTypeObject WHERE rule, the occurrence-only rule for material usage entities, derived attributes, quantity unit-type WHERE rules, and the IfcMaterialList legacy smell, across IFC2x3, IFC4 and IFC4.3. Keywords: property set error, Pset_ prefix, custom property set, IfcPropertySet, IfcRelDefinesByProperties, NoRelatedTypeObject, attach Pset to type, quantity set, IfcElementQuantity, Qto_ prefix, IfcQuantityArea wrong unit, WR21, TotalThickness derived, IfcMaterialLayerSetUsage on type, IfcMaterialList, "property set rejected", "Pset not showing", "custom properties ignored", "validation fails on quantity", how do I name a property set, why is my property set invalid, what is the Pset_ convention.
|
| license | MIT |
| compatibility | Designed for Claude Code. Requires IFC IFC2x3, IFC4, IFC4.3. |
| metadata | {"author":"OpenAEC-Foundation","version":"1.0"} |
IFC Property Set Mistakes
Diagnose and fix the six recurring mistakes in IFC property sets, quantity sets
and material associations : a reserved-prefix name collision, a property set
attached to a type through the wrong relationship, a material-usage entity on a
type, a hand-written derived attribute, a quantity carrying the wrong unit type,
and the legacy IfcMaterialList in a modern file.
Two of these are schema-valid but wrong (a "smell") ; three break a WHERE
rule (a hard error) ; one is a derived-attribute violation. ALWAYS classify the
mistake before fixing it.
For the property and quantity entity model see ifc-syntax-property-sets. For
the material entity model see ifc-syntax-materials. For units see
ifc-syntax-units. For schema-validation mechanics see
ifc-errors-schema-validation.
Quick Reference
The six mistakes
| # | Mistake | Severity | Rule or mechanism | Fix |
|---|
| 1 | Custom property set named Pset_... | Smell : schema-valid, collides with the standard library | Pset_ is reserved for published sets | Rename without the Pset_ prefix |
| 2 | IfcRelDefinesByProperties RelatedObjects holds an IfcTypeObject | Hard error (IFC4+) | WHERE rule NoRelatedTypeObject | Use IfcTypeObject.HasPropertySets for types |
| 3 | IfcMaterialLayerSetUsage / IfcMaterialProfileSetUsage assigned to an element type | Hard error | Usage entities are occurrence-only | Put the bare set on the type, the usage on the occurrence |
| 4 | A literal value written into the derived IfcMaterialLayerSet.TotalThickness | Hard error : derived slot | The value is computed by IfcMlsTotalThickness | Write * in the STEP slot ; never a number |
| 5 | A length unit on IfcQuantityArea (or any quantity unit mismatch) | Hard error | WHERE rule WR21 : the unit must match the quantity type | Use an AREAUNIT, or omit Unit to inherit the project unit |
| 6 | IfcMaterialList in a new IFC4 / IFC4.3 file | Smell : schema-valid, legacy mechanism | Superseded by IfcMaterialConstituentSet | Replace with IfcMaterialConstituentSet |
Severity, restated
- Hard error : a schema validator rejects the file (mistakes 2, 3, 5) or the
STEP line is malformed (mistake 4). The file does not pass validation.
- Smell : the file passes validation, but the model is wrong by convention
and breaks downstream tools or data exchange (mistakes 1, 6). NEVER read
"validation passed" as "the property data is correct."
Property set versus quantity set : same attachment, different content
IfcPropertySet (named properties) and IfcElementQuantity (measured
quantities) are both subtypes of IfcPropertySetDefinition. Both attach to an
occurrence through IfcRelDefinesByProperties, and to a type through
IfcTypeObject.HasPropertySets. The naming conventions are parallel : Pset_
for property sets, Qto_ for quantity sets. Every rule in this skill that names
Pset_ applies equally to Qto_.
The reserved prefixes
| Prefix | Reserved for | A custom name MUST |
|---|
Pset_ | buildingSMART published property sets | NEVER start with Pset_ |
Qto_ | buildingSMART published quantity sets | NEVER start with Qto_ |
A published set name is an exact identifier, for example Pset_WallCommon
("properties common to all occurrences of IfcWall") or Qto_WallBaseQuantities.
A custom set uses a project or vendor prefix instead, for example
ACME_WallThermal.
Decision Trees
Naming a property set or quantity set
You are naming an IfcPropertySet or IfcElementQuantity.
|
+-- Is the name an EXACT published Pset_ / Qto_ identifier for this element,
| verified against the buildingSMART property library?
| YES -> use it as-is. The content must match the published template.
| NO -> continue.
|
+-- Does the name start with Pset_ or Qto_ ?
YES -> COLLISION (mistake 1). Rename with a project / vendor prefix.
NO -> custom set, correctly named. Proceed.
Attaching a property set to the right host
You are attaching an IfcPropertySet (or IfcElementQuantity).
|
+-- Is the host an occurrence (IfcWall, IfcSlab, ... an IfcObject) ?
| -> create IfcRelDefinesByProperties
| RelatedObjects = the occurrence(s),
| RelatingPropertyDefinition = the set.
|
+-- Is the host a type object (IfcWallType, ... an IfcTypeObject) ?
-> add the set to IfcTypeObject.HasPropertySets directly.
-> NEVER put the type into IfcRelDefinesByProperties.RelatedObjects
(mistake 2 : WHERE rule NoRelatedTypeObject, IFC4+).
Associating a structured material
You are associating a material that has internal structure.
|
+-- Layered element (wall, slab, roof, plate) ?
| type -> IfcRelAssociatesMaterial.RelatingMaterial = IfcMaterialLayerSet
| occurrence-> IfcRelAssociatesMaterial.RelatingMaterial = IfcMaterialLayerSetUsage
| (the usage ForLayerSet points back at the same set)
|
+-- Profiled element (beam, column, member, pile) ? [IFC4+ only]
| type -> RelatingMaterial = IfcMaterialProfileSet
| occurrence-> RelatingMaterial = IfcMaterialProfileSetUsage
|
+-- Non-layered, non-profiled composite (window, door) ?
IFC4+ -> IfcMaterialConstituentSet
IFC2x3 -> IfcMaterialList (the only option in 2x3)
NEVER put a *Usage entity on a type : it is occurrence-only (mistake 3).
Patterns
Pattern 1 : Name a custom property set
ALWAYS reserve Pset_ and Qto_ for buildingSMART published sets. A custom
set ALWAYS uses a distinguishing project or vendor prefix.
- Correct published use :
Pset_WallCommon, content matching the published
template (each property name, type and value type as specified).
- Correct custom use :
ACME_WallAcoustics, ProjectX_CostData.
- NEVER :
Pset_WallAcoustics for a custom set. It is schema-valid, so no
validator stops it, but it shadows or collides with the standard library and
receiving software cannot tell custom data from standard data.
A custom Pset_ name is mistake 1. The fix is a rename ; see
references/examples.md Example 1.
Pattern 2 : Attach a property set to a type, not through the wrong relationship
IfcRelDefinesByProperties attaches a set to occurrences. In IFC4 and
IFC4.3 its RelatedObjects is SET [1:?] OF IfcObjectDefinition, which
syntactically admits an IfcTypeObject ; the WHERE rule NoRelatedTypeObject
("There shall be no related object being of type IfcTypeObject") forbids it.
ALWAYS attach a type's property sets through the HasPropertySets aggregation
on IfcTypeObject itself. NEVER list a type in
IfcRelDefinesByProperties.RelatedObjects. See references/examples.md
Example 2.
Version note : in IFC2x3 RelatedObjects is SET [1:?] OF IfcObject, and
IfcTypeObject is not an IfcObject, so the schema type alone blocks the
mistake and no WHERE rule is needed. The widening to IfcObjectDefinition in
IFC4 is exactly why NoRelatedTypeObject was added.
Pattern 3 : Bare set on the type, usage on the occurrence
IfcMaterialLayerSet and IfcMaterialProfileSet are the bare structured sets.
IfcMaterialLayerSetUsage and IfcMaterialProfileSetUsage add placement and
are occurrence-only : the IFC4.3 specification states the usage "is always
assigned to an individual occurrence object (and only to relevant subtypes of
IfcElement)."
ALWAYS associate the element TYPE (IfcWallType, IfcBeamType) with the bare
IfcMaterialLayerSet / IfcMaterialProfileSet. ALWAYS associate each
OCCURRENCE with a ...SetUsage whose ForLayerSet / ForProfileSet points
back at that same bare set. NEVER associate a ...SetUsage with a type. See
references/examples.md Example 3.
Pattern 4 : Leave TotalThickness derived
IfcMaterialLayerSet.TotalThickness is a derived attribute : its value is
computed from the layer thicknesses by the schema function IfcMlsTotalThickness.
A derived attribute is never stored. In a STEP file its positional slot ALWAYS
holds the token *. Writing a literal number there is mistake 4 : the value is
either rejected as malformed or silently recomputed and discarded.
ALWAYS write * in the TotalThickness slot. To change the total thickness,
change the LayerThickness of the layers. See references/examples.md
Example 4.
Pattern 5 : Match the quantity unit to the quantity type
IfcQuantityArea carries WHERE rule WR21 : "If a unit is given, the unit
type shall be area unit" (Unit.UnitType = IfcUnitEnum.AREAUNIT). It also
carries WR22 : AreaValue >= 0. The sibling quantities behave the same way :
IfcQuantityLength needs a LENGTHUNIT, IfcQuantityVolume a VOLUMEUNIT,
and so on.
The Unit attribute of every IfcPhysicalSimpleQuantity is OPTIONAL. ALWAYS
EITHER omit Unit, so the quantity inherits the matching unit from the project
IfcUnitAssignment, OR supply a unit whose UnitType matches the quantity
entity. NEVER put a LENGTHUNIT on IfcQuantityArea. See
references/examples.md Example 5.
Pattern 6 : Replace IfcMaterialList in IFC4 and IFC4.3
IfcMaterialList (single attribute Materials : LIST [1:?] OF IfcMaterial) is
a bare ordered list with no per-part semantics, fractions or geometry. It is the
IFC2x3 mechanism for a non-layered composite. It remains in IFC4 and IFC4.3
ONLY for round-tripping IFC2x3 data.
ALWAYS use IfcMaterialConstituentSet for a non-layered, non-profiled composite
in a new IFC4 or IFC4.3 file : each IfcMaterialConstituent names a part, its
Material, an optional Fraction and Category. An IfcMaterialList in a new
IFC4+ file is mistake 6 : schema-valid, but a smell that loses constituent
semantics. See references/examples.md Example 6.
Version Notes
| Entity / rule | IFC2x3 | IFC4 / IFC4.3 |
|---|
IfcRelDefinesByProperties.RelatedObjects | SET [1:?] OF IfcObject ; no WHERE rule needed | SET [1:?] OF IfcObjectDefinition ; WHERE rule NoRelatedTypeObject |
IfcMaterialProfileSet family | does not exist | introduced in IFC4 |
IfcMaterialConstituentSet family | does not exist | introduced in IFC4 |
IfcMaterialList | the standard non-layered mechanism | legacy ; superseded by IfcMaterialConstituentSet |
| Quantity-set prefix | BaseQuantities convention | Qto_ prefix (IFC4+) |
IfcQuantityNumber | does not exist | introduced in IFC4 |
IfcMaterialProperties | split into typed subtypes (IfcMechanicalMaterialProperties, ...) | one consolidated non-abstract entity |
Material usage entities (IfcMaterialLayerSetUsage, IfcMaterialProfileSetUsage)
are occurrence-only in every version that defines them. The element-supertype
rename IfcBuildingElement to IfcBuiltElement (IFC4.3) does not affect any
entity in this skill : property sets, quantities and materials attach through
IfcObject / IfcObjectDefinition and IfcTypeObject, whose names are stable.
Reference Links
references/methods.md : entity and attribute signatures for IfcPropertySet,
IfcRelDefinesByProperties, IfcElementQuantity, the quantity subtypes, the
material set and usage entities, with cardinalities and WHERE rules.references/examples.md : the wrong STEP and the corrected STEP for each of
the six mistakes, plus ifcopenshell detection snippets.references/anti-patterns.md : the mistakes in detail, why each fails, and
the deterministic rule.
Official sources (verified 2026-05-20)
