Use when wiring IFC objects together: aggregating parts into a whole, containing elements in a storey, attaching property sets or a type, assigning a material, cutting an opening, or filling it with a door. Prevents pointing a relationship the wrong way, using IfcRelAggregates where IfcRelContainedInSpatialStructure is required, putting an element in two spatial parents, swapping the void and fill anchors, and treating a relationship as a plain pointer attribute. Covers the objectified relationship pattern, the six IfcRelationship families, the Relating versus Related direction convention, the full IfcRel star reference table, the IfcRelVoidsElement then IfcRelFillsElement door-in-wall pattern, and traversal through INVERSE attributes. Keywords: IfcRel, IfcRelationship, IfcRelAggregates, IfcRelNests, IfcRelContainedInSpatialStructure, IfcRelDefinesByProperties, IfcRelDefinesByType, IfcRelAssociatesMaterial, IfcRelConnectsElements, IfcRelVoidsElement, IfcRelFillsElement, IfcRelSpaceBoundary, objectified relati
Use when wiring IFC objects together: aggregating parts into a whole, containing elements in a storey, attaching property sets or a type, assigning a material, cutting an opening, or filling it with a door. Prevents pointing a relationship the wrong way, using IfcRelAggregates where IfcRelContainedInSpatialStructure is required, putting an element in two spatial parents, swapping the void and fill anchors, and treating a relationship as a plain pointer attribute. Covers the objectified relationship pattern, the six IfcRelationship families, the Relating versus Related direction convention, the full IfcRel star reference table, the IfcRelVoidsElement then IfcRelFillsElement door-in-wall pattern, and traversal through INVERSE attributes. Keywords: IfcRel, IfcRelationship, IfcRelAggregates, IfcRelNests, IfcRelContainedInSpatialStructure, IfcRelDefinesByProperties, IfcRelDefinesByType, IfcRelAssociatesMaterial, IfcRelConnectsElements, IfcRelVoidsElement, IfcRelFillsElement, IfcRelSpaceBoundary, objectified relationship, Relating, Related, RelatingObject, RelatedObjects, INVERSE attribute, door in wall, how do I connect two IFC elements, how do I add a property set, element appears twice, property set not showing, opening not cutting, which IFC relationship do I use, what links a wall to a storey.
license
MIT
compatibility
Designed for Claude Code. Requires IFC IFC2x3,IFC4,IFC4.3.
metadata
{"author":"OpenAEC-Foundation","version":"1.0"}
IFC Relationships
IFC does not connect objects with plain pointer attributes. Every
connection between objects is a separate, identifiable entity: an
IfcRelationship. This is the objectified relationship pattern. This
skill covers why IFC objectifies relationships, the six relationship
families, the Relating versus Related direction convention, the
concrete IfcRel* entities, and how to traverse them.
Verified against the IFC 4.3.2 specification (ISO 16739-1:2024) with
IFC4 and IFC2x3 deltas noted inline. Applies to IFC2x3, IFC4, IFC4.3.
Quick Reference
The objectified relationship pattern
IfcRelationship is a direct subtype of IfcRoot, so every relationship
instance carries its own GlobalId, OwnerHistory, Name, and
Description. A relationship is a node in the model, not an attribute on
the connected objects.
Consequences that drive every rule in this skill:
A relationship can carry its own data: connection geometry, priorities,
boundary type. That data lives ON the relationship, not on the objects.
A relationship is added or removed WITHOUT editing the connected
objects. ALWAYS edit the relationship instance, NEVER the participants.
A relationship is itself identifiable and versionable through its
GlobalId.
The cost is indirection: to reach a wall's property sets you follow the
wall's IsDefinedBy INVERSE to IfcRelDefinesByProperties instances,
then read RelatingPropertyDefinition. NEVER expect a direct attribute.
The six relationship families
IfcRelationship is abstract with exactly six direct subtypes (verified).
NEVER instantiate IfcRelationship or any abstract family supertype.
Family
Purpose
Concrete entities used most
IfcRelAssigns
Cross-domain assignment of objects to a group, process, resource, control, actor, or product
Declare objects or types into an IfcContext (project or library)
IfcRelDeclares
IfcRelDecomposes
Whole and part decomposition, plus feature subtraction
IfcRelAggregates, IfcRelNests, IfcRelVoidsElement
IfcRelDefines
Assign a type or a property set to objects
IfcRelDefinesByType, IfcRelDefinesByProperties
The Relating versus Related convention
Every relationship has one Relating... role and one Related... role.
The direction is part of the semantics. A backwards relationship is a
structurally valid but meaningless model.
The Relating... side is the single anchor: the whole, the type, the
spatial container, the property set, the opening.
The Related... side is the dependent participant. In one-to-many
relationships it is an aggregate (SET or LIST, cardinality 1..n).
ALWAYS read the entity attribute documentation to know which object goes
on which side. NEVER guess the direction.
Key IfcRel* reference table
All entities and attribute types below are verified against the IFC4.3
specification. Full positional signatures are in references/methods.md.
Entity
Supertype
Relating side
Related side
IfcRelAggregates
IfcRelDecomposes
RelatingObject: IfcObjectDefinition (the whole)
RelatedObjects: SET [1:?] OF IfcObjectDefinition (the parts)
IfcRelNests
IfcRelDecomposes
RelatingObject: IfcObjectDefinition (the whole)
RelatedObjects: LIST [1:?] OF IfcObjectDefinition (ordered parts)
IfcRelContainedInSpatialStructure
IfcRelConnects
RelatingStructure: IfcSpatialElement
RelatedElements: SET [1:?] OF IfcProduct
IfcRelReferencedInSpatialStructure
IfcRelConnects
RelatingStructure: IfcSpatialElement
RelatedElements: SET [1:?] OF IfcSpatialReferenceSelect
Note the reversed anchor between IfcRelVoidsElement and
IfcRelFillsElement: see the door-in-wall pattern below.
Decision Trees
Which relationship do I use?
What am I trying to express?
|
+- A whole made of parts, order does NOT matter
| -> IfcRelAggregates (spatial tree, element assemblies)
|
+- A whole made of parts, order DOES matter
| -> IfcRelNests (ordered ports, ordered cost items, ordered tasks)
|
+- Place a physical element into a spatial level (storey, space)
| -> IfcRelContainedInSpatialStructure
|
+- Reference an element from a second spatial structure
| -> IfcRelReferencedInSpatialStructure
|
+- Attach a property set or quantity set to objects
| -> IfcRelDefinesByProperties
|
+- Link occurrences to their shared type object
| -> IfcRelDefinesByType
|
+- Assign a material to elements or element types
| -> IfcRelAssociatesMaterial
|
+- Assign a classification reference (Uniclass, OmniClass)
| -> IfcRelAssociatesClassification
|
+- Connect two elements physically or logically
| -> IfcRelConnectsElements (or IfcRelConnectsPathElements for wall joins)
|
+- Cut an opening into an element
| -> IfcRelVoidsElement
|
+- Fill an opening with a door or window
| -> IfcRelFillsElement
|
+- Define the surfaces that bound a space
| -> IfcRelSpaceBoundary (or its 1stLevel / 2ndLevel subtypes)
|
+- Group objects across domains (a system, a zone, a schedule)
-> IfcRelAssignsToGroup
Aggregate or nest?
Does the order of the parts carry meaning?
|
+- No -> IfcRelAggregates : RelatedObjects is a SET, order is irrelevant.
| The spatial tree (Project, Site, Building, Storey) ALWAYS uses
| IfcRelAggregates.
|
+- Yes -> IfcRelNests : RelatedObjects is a LIST, position is meaningful.
Use for ordered distribution ports, ordered cost items, ordered
subtasks.
NEVER use IfcRelNests for the spatial tree. NEVER use IfcRelAggregates
when the consumer depends on part order.
Containment or aggregation for the spatial tree?
What are the two objects?
|
+- Both are spatial elements (Site inside Project, Storey inside Building)
| -> IfcRelAggregates : spatial element decomposes spatial element.
|
+- A physical element placed into a spatial element (a wall in a storey)
| -> IfcRelContainedInSpatialStructure : NEVER IfcRelAggregates.
|
+- A physical element that also belongs to a second structure
-> add IfcRelReferencedInSpatialStructure for the secondary link.
The single primary containment stays IfcRelContainedInSpatialStructure.
A physical element ALWAYS sits in exactly ONE
IfcRelContainedInSpatialStructure (the WR31 rule on that entity enforces
at-most-once). Extra spatial links ALWAYS go through
IfcRelReferencedInSpatialStructure. See ifc-core-spatial-structure.
Patterns
Every snippet uses STEP physical file syntax. $ marks an unset optional
attribute. Attribute order is the EXPRESS declared order. Full verified
signatures are in references/methods.md; runnable instances are in
references/examples.md.
Pattern: aggregate parts into a whole
IfcRelAggregates has 6 positional attributes: the 4 from IfcRoot, then
RelatingObject (the whole), then RelatedObjects (the SET of parts).
#30=IFCRELAGGREGATES(
'1Hkj5pQ9X8x9bq0d6FZ7yA', /* GlobalId */
#5, /* OwnerHistory */
$, /* Name */
$, /* Description */
#10, /* RelatingObject : IfcBuilding (the whole) */
(#11,#12) /* RelatedObjects : the IfcBuildingStorey parts */
);
ALWAYS put the whole on RelatingObject and the parts on RelatedObjects.
A reversed instance describes a storey aggregating a building.
Pattern: contain elements in a spatial structure
IfcRelContainedInSpatialStructure places physical elements into one
spatial level. RelatedElements comes BEFORE RelatingStructure in the
declared order.
Each physical element appears in RelatedElements of exactly one such
relationship. NEVER list the same element in two
IfcRelContainedInSpatialStructure instances.
Pattern: attach a property set
IfcRelDefinesByProperties links an IfcPropertySet or IfcElementQuantity
to objects. RelatedObjects precedes RelatingPropertyDefinition.
#50=IFCRELDEFINESBYPROPERTIES(
'3mNp7rTf0Y9y0cr1e7GA8z', /* GlobalId */
#5, /* OwnerHistory */
$, /* Name */
$, /* Description */
(#21,#22), /* RelatedObjects : the elements */
#48 /* RelatingPropertyDefinition : the IfcPropertySet */
);
One relationship can serve many objects (N-to-N). See
ifc-syntax-property-sets for building the IfcPropertySet itself.
Pattern: link occurrences to a type
IfcRelDefinesByType is 1-to-N: one type, many occurrences.
RelatingMaterial accepts the IfcMaterialSelect choices: IfcMaterial,
IfcMaterialLayerSet, IfcMaterialLayerSetUsage, IfcMaterialProfileSet,
IfcMaterialProfileSetUsage, IfcMaterialConstituentSet, IfcMaterialList.
See ifc-syntax-materials.
Pattern: the door-in-wall void then fill
The canonical opening pattern uses two relationships, in this order:
IfcRelVoidsElement subtracts an IfcOpeningElement from the wall.
IfcRelFillsElement places the IfcDoor into that opening.
/* step 1 : the wall voids the opening */
#60=IFCRELVOIDSELEMENT(
'6rSt1uWi3_2_3fu4h0JD1A', /* GlobalId */
#5, $, $, /* OwnerHistory, Name, Description */
#21, /* RelatingBuildingElement : the IfcWall */
#58 /* RelatedOpeningElement : the IfcOpeningElement */
);
/* step 2 : the opening is filled by the door */
#62=IFCRELFILLSELEMENT(
'7sTu2vXj4A3A4gv5i1KE2B', /* GlobalId */
#5, $, $, /* OwnerHistory, Name, Description */
#58, /* RelatingOpeningElement : the IfcOpeningElement */
#59 /* RelatedBuildingElement : the IfcDoor */
);
The anchor reverses between the two relationships. The wall is the
Relating side of IfcRelVoidsElement; the SAME opening (#58) is the
Relating side of IfcRelFillsElement. ALWAYS create the void first, then
the fill. NEVER point IfcRelFillsElement straight from wall to door:
the door fills the opening, not the wall.
Version note: IfcRelVoidsElement is a subtype of IfcRelDecomposes in
IFC4 and IFC4.3. In IFC2x3 it sat under the connectivity branch. The
attribute names and order are stable across all three versions.
Pattern: traverse through INVERSE attributes
Objects do not store relationships as forward attributes. They expose
INVERSE attributes that the parser populates by scanning relationship
instances. To find what defines an object, follow its inverses:
To read a wall's property sets: take wall.IsDefinedBy, keep the
IfcRelDefinesByProperties instances, then read each
RelatingPropertyDefinition. NEVER look for a direct PropertySets
attribute on the wall: it does not exist.
Anti-Patterns
Full detail with the failure mechanism is in references/anti-patterns.md.
The five that matter most:
Reversing Relating and Related. The model parses but states the
wrong fact (a storey aggregating a building, a part owning the whole).
Using IfcRelAggregates to place a physical element into a storey.
Containment of physical elements ALWAYS uses
IfcRelContainedInSpatialStructure.
Listing one element in two IfcRelContainedInSpatialStructure instances.
Violates WR31; the element belongs to the spatial tree once only.
Pointing IfcRelFillsElement from the wall to the door directly,
skipping the IfcOpeningElement. The door has nothing to fill.
Treating a relationship as a pointer and editing the participants to
"connect" them. Connections ALWAYS exist only as IfcRel* instances.
Reference Links
This skill
references/methods.md: full positional attribute signatures for every
IfcRel* entity in this skill, with supertypes and version notes.
