ifc-core-entity-hierarchy

name	ifc-core-entity-hierarchy
description	Use when navigating or authoring the IFC entity inheritance tree, choosing which entity to instantiate, generating IFC GlobalId values, or deciding between a type object and an occurrence. Prevents instantiating abstract supertypes, regenerating GUIDs on every export, confusing IfcTypeObject with IfcObject, and misusing IfcBuildingElementProxy as a placeholder. Covers IfcRoot and its four attributes, the IfcObjectDefinition to IfcBuiltElement object chain, the 22-character compressed IFC GUID, the type versus occurrence model, the PredefinedType enumeration pattern, and the IFC4.3 IfcBuildingElement to IfcBuiltElement rename. Keywords: IfcRoot, IfcBuiltElement, IfcBuildingElement, GlobalId, IfcGloballyUniqueId, IFC GUID, IfcObjectDefinition, IfcObject, IfcProduct, IfcElement, IfcTypeObject, IfcTypeProduct, IfcElementType, IfcRelDefinesByType, PredefinedType, IfcBuildingElementProxy, abstract entity, type vs occurrence, which IFC entity do I use, GUID keeps changing, cannot instantiate abstract entity, IFC entity name not found, how do I create an IFC element, what is an occurrence in IFC.
license	MIT
compatibility	Designed for Claude Code. Requires IFC IFC2x3,IFC4,IFC4.3.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

IFC Entity Hierarchy

The IFC schema is a deep single-inheritance tree. Every meaningful object, relationship, and property definition descends from one abstract root, IfcRoot. This skill covers the identity backbone, the object inheritance chain down to concrete construction elements, the type versus occurrence model, and the IFC GUID. 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. Read the version annotations: one hard file-breaking rename (IfcBuildingElement to IfcBuiltElement) sits inside this hierarchy.

Quick Reference

IfcRoot: the identity backbone

IfcRoot is abstract. Every entity needing independent identity, ownership tracking, and a human label derives from it. ALWAYS place a valid GlobalId as the first positional attribute of every rooted instance.

#	Attribute	Type	Cardinality	Notes
1	GlobalId	IfcGloballyUniqueId	required	22-char compressed GUID. UNIQUE within the file.
2	OwnerHistory	IfcOwnerHistory	optional	Optional in IFC4 and IFC4.3. Mandatory in IFC2x3.
3	Name	IfcLabel	optional	Some subtypes promote it to required via a WHERE rule.
4	Description	IfcText	optional	Free-text comment.

IfcRoot has exactly three direct subtypes. This three-way split is the schema's top-level conceptual division:

Subtype	Role
IfcObjectDefinition	Semantically treated things or processes (types and occurrences).
IfcRelationship	Objectified relationships between objects.
IfcPropertyDefinition	Property and property-set definitions.

This skill covers the IfcObjectDefinition branch. See ifc-core-relationships for IfcRelationship and ifc-syntax-property-sets for IfcPropertyDefinition.

The object chain

IfcRoot                    abstract  : identity (GlobalId, OwnerHistory, Name, Description)
  IfcObjectDefinition      abstract  : objects, types, contexts
    IfcObject              abstract  : an occurrence; adds ObjectType
      IfcProduct           abstract  : adds ObjectPlacement, Representation
        IfcElement         abstract  : a physical component; adds Tag
          IfcBuiltElement  IFC4.3 CONCRETE  /  IfcBuildingElement IFC2x3+IFC4 abstract
            IfcWall, IfcSlab, IfcBeam, IfcColumn, IfcDoor, IfcWindow, ...  concrete

Resources and details are in references/methods.md. Direct subtype counts (IFC4.3, verified): IfcObjectDefinition has 3, IfcObject has 6, IfcProduct has 8, IfcElement has 11, IfcBuiltElement has 30.

Abstract entities: NEVER instantiate

NEVER write an instance of an abstract entity into an IFC file. Instantiate a concrete leaf instead. Abstract entities in this hierarchy:

IfcRoot, IfcObjectDefinition, IfcObject, IfcProduct, IfcElement, IfcTypeObject, IfcTypeProduct, IfcElementType, and IfcBuildingElement (IFC2x3 and IFC4 only).

Concrete entities you DO instantiate: IfcWall, IfcSlab, IfcBeam, IfcColumn, IfcDoor, IfcWindow, IfcWallType, IfcBuildingElementProxy, and (IFC4.3 only) IfcBuiltElement itself.

Critical version rename

Aspect	IFC2x3, IFC4	IFC4.3
Entity name	IfcBuildingElement	IfcBuiltElement
Abstract?	abstract (never instantiated)	non-abstract (may be instantiated)

The IFC4.3 CHANGE note: "The entity has been renamed from IfcBuildingElement and made non abstract." The old name IfcBuildingElement returns HTTP 404 in the IFC4.3 lexical documentation. ALWAYS pick the entity name by target version: IfcBuildingElement for IFC2x3 and IFC4, IfcBuiltElement for IFC4.3. This rename does NOT affect the concrete leaves (IfcWall, IfcSlab and the rest keep their names across all three versions).

Decision Trees

Which entity should I instantiate?

Need to represent a thing in an IFC file?
|
+- Is it a physical construction component (wall, slab, beam, door)?
|    |
|    +- Yes : does a specific concrete entity exist for it?
|    |    +- Yes -> instantiate that concrete entity (IfcWall, IfcSlab, ...)
|    |    +- No, semantics genuinely unknown -> IfcBuildingElementProxy
|    |
|    +- No : continue
|
+- Is it the shared definition reused by many occurrences (a product type)?
|    -> instantiate the matching *Type entity (IfcWallType, IfcDoorType, ...)
|
+- Is it spatial (project, site, building, storey, space)?
|    -> see ifc-core-spatial-structure
|
+- Is it a relationship between objects?
     -> see ifc-core-relationships

NEVER instantiate IfcElement, IfcProduct, IfcObject, or IfcBuiltElement (in IFC2x3/IFC4 named IfcBuildingElement) to mean "some generic element". Instantiate the concrete leaf. The one exception: IfcBuiltElement is itself instantiable in IFC4.3, but ONLY when no concrete subtype fits and the element is still a primary construction component.

Type object or occurrence?

Does this data describe one physically placed instance, or a shared template?
|
+- One physical instance, placed somewhere, with its own geometry transform
|    -> an OCCURRENCE : an IfcObject subtype (IfcWall, IfcDoor, ...)
|    -> carries ObjectPlacement and Representation
|
+- A reusable definition shared by many instances (catalogue product)
     -> a TYPE : an IfcTypeObject subtype (IfcWallType, IfcDoorType, ...)
     -> carries HasPropertySets and RepresentationMaps, NOT ObjectPlacement
     -> link to occurrences with one IfcRelDefinesByType

ALWAYS keep geometry-placement data on the occurrence. NEVER put ObjectPlacement on a type: IfcTypeProduct has no ObjectPlacement attribute. Type geometry is reusable and lives in RepresentationMaps.

When the same property name exists on both the type and the occurrence, the OCCURRENCE value wins. The type provides the default, the occurrence overrides it. See references/methods.md for the resolution order.

Concrete entity or IfcBuildingElementProxy?

The semantic class of this construction element is...
|
+- Known and a concrete entity exists -> use that concrete entity. STOP.
|
+- Genuinely unknown or unclassifiable, but it is a real construction element
|    -> IfcBuildingElementProxy with PredefinedType = USERDEFINED
|       and ObjectType set to your own term
|
+- A spatial placeholder or a provision for a future void/space
     -> IFC4.3 : use IfcVirtualElement. NEVER IfcBuildingElementProxy.
     -> IFC2x3/IFC4 : a proxy was tolerated; prefer a concrete entity anyway.

IfcBuildingElementProxy is an escape hatch, not a default. Reaching for it when a concrete entity exists produces a model that downstream tools cannot classify, cost, or analyse.

Patterns

Pattern: generate a stable GlobalId

GlobalId is of defined type IfcGloballyUniqueId: a STRING of fixed length 22 that encodes a 128-bit GUID. The encoding is a custom base64 over the 64-symbol alphabet 0-9 A-Z a-z _ $. It is NOT RFC 4648 base64. Because the first character holds only 2 bits, the first character is ALWAYS one of 0, 1, 2, 3.

Example: the hex GUID f70dd363-bfe3-495d-84a0-2c02dcb7d4d2 compresses to the 22-character form 3t3TDZl_D9NOIWB0BSjzJI.

ALWAYS generate the GlobalId once, when the logical object is first created, and persist it. The GUID identifies the same logical object across file versions and edit sessions. NEVER regenerate GlobalId on every export: round-trip identity, model diffing, and issue tracking all depend on its stability. See references/anti-patterns.md for the failure this causes.

Pattern: walk or build the object chain

Every concrete element inherits four attribute blocks. For IfcWall the full positional order in a STEP physical file is:

#21=IFCWALL(
  '3t3TDZl_D9NOIWB0BSjzJI',  /* 1 GlobalId      from IfcRoot    */
  #5,                        /* 2 OwnerHistory  from IfcRoot    */
  'Wall-001',                /* 3 Name          from IfcRoot    */
  $,                         /* 4 Description   from IfcRoot    */
  $,                         /* 5 ObjectType    from IfcObject  */
  #18,                       /* 6 ObjectPlacement from IfcProduct */
  #19,                       /* 7 Representation  from IfcProduct */
  'A-101',                   /* 8 Tag           from IfcElement */
  .SOLIDWALL.                /* 9 PredefinedType from IfcWall   */
);

When reading, climb the inheritance chain to know which attribute index means what. When authoring, ALWAYS emit attributes in declared order and use $ for an unset optional. See references/examples.md for more instances.

Pattern: pair a type with its occurrences

A type object holds data common to many occurrences. One IfcWallType is shared by many IfcWall occurrences. The link is one IfcRelDefinesByType instance (1-to-N): RelatingType points to the type, RelatedObjects is the SET of occurrences.

/* #20 : an IfcWallType type     (see ifc-syntax-building-elements) */
/* #21, #22 : two IfcWall occurrences sharing that type            */
#30=IFCRELDEFINESBYTYPE(
  '1Hkj5pQ9X8x9bq0d6FZ7yA',  /* GlobalId                      */
  #5,                        /* OwnerHistory                  */
  $,                         /* Name                          */
  $,                         /* Description                   */
  (#21,#22),                 /* RelatedObjects : the occurrences */
  #20                        /* RelatingType   : the type        */
);

IfcRelDefinesByType has exactly 6 positional attributes: the 4 from IfcRoot, then RelatedObjects (SET [1:?] OF IfcObject), then RelatingType (IfcTypeObject). NEVER place a type object inside RelatedObjects: that slot accepts occurrences only. Type objects receive their property sets directly via HasPropertySets, not via a relationship.

Pattern: set PredefinedType and ObjectType

Concrete element entities and their type entities carry a PredefinedType enumeration that sub-classifies them (for IfcWall the enum is IfcWallTypeEnum). Every such enum ends with two reserved values:

• NOTDEFINED : no specialization is asserted.
• USERDEFINED : the specialization is named by a separate label attribute.

ALWAYS pair PredefinedType = USERDEFINED with the ObjectType label on an occurrence (IfcObject.ObjectType). When PredefinedType is any concrete enum value, leave ObjectType unset ($). NEVER set PredefinedType to a value that is not in that entity's enumeration: it is a schema violation.

IfcWallTypeEnum values (IFC4.3, verified): ELEMENTEDWALL, MOVABLE, PARAPET, PARTITIONING, PLUMBINGWALL, POLYGONAL, RETAININGWALL, SHEAR, SOLIDWALL, STANDARD, WAVEWALL, USERDEFINED, NOTDEFINED. Other element entities have their own enums; verify per entity.

Pattern: the proxy escape hatch

IfcBuildingElementProxy is a concrete subtype of IfcBuiltElement (IFC4.3) or IfcBuildingElement (IFC2x3, IFC4). Use it ONLY for a genuine construction element with no matching concrete entity.

#40=IFCBUILDINGELEMENTPROXY(
  '2k7sB$Qe9X8x9bq0d6FZ7y',  /* GlobalId        */
  #5,                        /* OwnerHistory    */
  'Acoustic baffle',         /* Name            */
  $,                         /* Description     */
  'AcousticBaffle',          /* ObjectType : the USERDEFINED term */
  #38,                       /* ObjectPlacement */
  #39,                       /* Representation  */
  $,                         /* Tag             */
  .USERDEFINED.              /* PredefinedType : IfcBuildingElementProxyTypeEnum */
);

IfcBuildingElementProxyTypeEnum values: COMPLEX, ELEMENT, PARTIAL (all three "shall no longer be used"), PROVISIONFORSPACE, PROVISIONFORVOID (both deprecated as of IFC4.3.0.0), USERDEFINED, NOTDEFINED.

IFC4.3 CHANGE note: "IfcBuildingElementProxy should no longer be used as spatial placeholders or provisions. Use IfcVirtualElement instead." In IFC4.3, NEVER use a proxy as a placeholder, a provision-for-void, or a provision-for-space: use IfcVirtualElement.

Anti-Patterns

Full detail with the failure mechanism is in references/anti-patterns.md. The five that matter most:

• Instantiating an abstract entity (IfcElement, IfcProduct, IfcBuildingElement). The file fails schema validation.
• Regenerating GlobalId on every export. Breaks model diffing and issue-tracking continuity.
• Using IfcBuildingElement against an IFC4.3 schema, or IfcBuiltElement against IFC2x3/IFC4. Wrong-version entity name, file rejected.
• Putting ObjectPlacement or Representation on a type object. Those attributes do not exist on IfcTypeProduct.
• Using IfcBuildingElementProxy where a concrete entity exists, or as a placeholder in IFC4.3.

Reference Links

This skill

• references/methods.md : full attribute signatures for IfcRoot, IfcObjectDefinition, IfcObject, IfcProduct, IfcElement, IfcBuiltElement, IfcTypeObject, IfcTypeProduct, IfcElementType, IfcRelDefinesByType, IfcBuildingElementProxy, IfcGloballyUniqueId.
• references/examples.md : verified STEP physical file instances.
• references/anti-patterns.md : failure modes and their root causes.

Related skills

• ifc-core-data-model : the four-layer schema architecture this tree sits in.
• ifc-core-relationships : the IfcRelationship branch and the objectified relationship pattern.
• ifc-core-spatial-structure : IfcProject, IfcContext, the spatial branch.
• ifc-syntax-building-elements : full attribute lists of the concrete leaves.
• ifc-core-version-evolution : the complete cross-version rename ledger.

Official sources

• IfcRoot: https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcRoot.htm
• IfcGloballyUniqueId: https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcGloballyUniqueId.htm
• IfcBuiltElement: https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcBuiltElement.htm
• IfcTypeProduct: https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcTypeProduct.htm
• IfcRelDefinesByType: https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcRelDefinesByType.htm