ifc-syntax-classifications

IFC Syntax : Classifications

An IFC model links its objects to external classification systems (Uniclass, OmniClass, MasterFormat, ETIM) and to external libraries through a small, fixed set of entities. This skill covers those entities, the attribute that carries the actual code, and the IFC2x3 / IFC4 / IFC4.3 version differences that break round-tripped files.

Applies to IFC2x3, IFC4, and IFC4.3. Several attribute names and types changed across versions : see the Version Differences section.

Quick Reference

The three classification entities

IfcClassification              the system    (Uniclass 2015 as a whole)
        ^
        | ReferencedSource
        |
IfcClassificationReference     one code      (one Uniclass code, e.g. EF_25_10)
        ^
        | RelatingClassification
        |
IfcRelAssociatesClassification the link       (binds the code to objects)
        |
        | RelatedObjects
        v
IfcWall, IfcWallType, ...      the classified objects

ALWAYS use IfcClassification for the system and IfcClassificationReference for a single code. NEVER attach an IfcClassification directly to elements as if it were a code : the system entity names the publisher and edition, not one item.

IfcClassification : the system

IfcClassification identifies an external classification system : its publisher, edition, and name. In IFC4 and IFC4.3 it is a subtype of IfcExternalInformation.

Verified verbatim (IFC4.3) :

ENTITY IfcClassification
 SUBTYPE OF (IfcExternalInformation);
	Source : OPTIONAL IfcLabel;
	Edition : OPTIONAL IfcLabel;
	EditionDate : OPTIONAL IfcDate;
	Name : IfcLabel;
	Description : OPTIONAL IfcText;
	Specification : OPTIONAL IfcURIReference;
	ReferenceTokens : OPTIONAL LIST [1:?] OF IfcIdentifier;
 INVERSE
	ClassificationForObjects : SET [0:?] OF IfcRelAssociatesClassification FOR RelatingClassification;
	HasReferences : SET [0:?] OF IfcClassificationReference FOR ReferencedSource;
END_ENTITY;

Name is the only required attribute (the system's common name, e.g. 'Uniclass 2015').
Specification is a URI/URN/URL locator of the system. In IFC4 this attribute is named Location : see Version Differences.
ReferenceTokens lists the delimiter tokens that mark facet boundaries inside a compound code, so a reader can split EF_25_10_25 into facets.

IfcClassificationReference : one code

IfcClassificationReference is one specific code inside a system. It is a subtype of IfcExternalReference, which supplies the attribute that carries the code.

Verified verbatim (IFC4.3) :

ENTITY IfcClassificationReference
 SUBTYPE OF (IfcExternalReference);
	ReferencedSource : OPTIONAL IfcClassificationReferenceSelect;
	Description : OPTIONAL IfcText;
	Sort : OPTIONAL IfcIdentifier;
 INVERSE
	ClassificationRefForObjects : SET [0:?] OF IfcRelAssociatesClassification FOR RelatingClassification;
	HasReferences : SET [0:?] OF IfcClassificationReference FOR ReferencedSource;
END_ENTITY;

Inherited from IfcExternalReference (IFC4 and IFC4.3) :

Location (OPTIONAL IfcURIReference) : a URI for the code itself.
Identification (OPTIONAL IfcIdentifier) : the actual code (e.g. 'EF_25_10'). In IFC2x3 this attribute is named ItemReference.
Name (OPTIONAL IfcLabel) : the human-readable title of the classified item.

ALWAYS put the code string in Identification (IFC4+) or ItemReference (IFC2x3). NEVER put the code in Name : Name is the readable title, not the code.

ReferencedSource points either at the IfcClassification system or at a parent IfcClassificationReference. Pointing at a parent reference builds a hierarchical classification tree. Full select details : see references/methods.md.

IfcRelAssociatesClassification : the link

The objectified relationship that binds a classification to objects. Supertype chain IfcRoot > IfcRelationship > IfcRelAssociates > IfcRelAssociatesClassification.

Verified verbatim (IFC4.3) :

ENTITY IfcRelAssociatesClassification
 SUBTYPE OF (IfcRelAssociates);
	RelatingClassification : IfcClassificationSelect;
END_ENTITY;

RelatedObjects (SET [1:?] OF IfcDefinitionSelect, inherited from IfcRelAssociates) : the objects or object types being classified.
RelatingClassification (IfcClassificationSelect) : the IfcClassificationReference (a code) or the whole IfcClassification (the system) applied to those objects.

One IfcRelAssociatesClassification applies one classification to many objects at once. ALWAYS reuse a single relationship for a set of objects that share the same code. NEVER create one relationship per object when the code is identical.

The library entities (brief)

External library references use a structurally identical mechanism. Verified verbatim (IFC4.3) :

ENTITY IfcRelAssociatesLibrary
 SUBTYPE OF (IfcRelAssociates);
	RelatingLibrary : IfcLibrarySelect;
END_ENTITY;

IfcLibrarySelect resolves to IfcLibraryReference (one item in a library) or IfcLibraryInformation (metadata about the library as a whole). IfcLibraryReference is a subtype of IfcExternalReference, so it carries Identification exactly like a classification reference. Full definitions : see references/methods.md.

ALWAYS use the library entities for an external specification or product datasheet that is not a classification taxonomy. NEVER force a product datasheet into IfcClassificationReference : a datasheet is a library item, not a taxonomy code.

External classification systems

IfcClassificationReference points into a published system. Common systems :

System	Region	Shape	Example code
Uniclass 2015	UK	Faceted, table-based	`EF_25_10_25`
OmniClass	North America	Multi-table	Table 21 / Table 23 codes
MasterFormat	North America	Specification numbering	`04 20 00`
ETIM	Europe	Technical product classes	`EC000123`

The IfcClassification entity names the system; Identification on the IfcClassificationReference carries one code from it. ReferenceTokens on the IfcClassification tells a reader how to split a compound code into facets.

Version differences (compact)

Item	IFC2x3	IFC4	IFC4.3
`IfcClassification` supertype	none (standalone)	`IfcExternalInformation`	`IfcExternalInformation`
`IfcClassification` system URI attribute	absent	`Location`	`Specification`
`IfcClassification.Description` / `ReferenceTokens`	absent	present	present
Code attribute on the reference	`ItemReference`	`Identification`	`Identification`
`IfcExternalReference.Location` type	`IfcLabel`	`IfcURIReference`	`IfcURIReference`
`IfcClassificationReference.ReferencedSource` type	`IfcClassification`	`IfcClassificationReferenceSelect`	`IfcClassificationReferenceSelect`
`IfcRelAssociatesClassification.RelatingClassification` type	`IfcClassificationNotationSelect`	`IfcClassificationSelect`	`IfcClassificationSelect`
Hierarchical tree mechanism	`IfcClassificationItem` tree	nested `IfcClassificationReference`	nested `IfcClassificationReference`

Full per-version definitions : see references/methods.md.

Decision Trees

Which entity do I need?

What are you modelling?
|
+-- A whole classification system (publisher, edition, name)
|   --> IfcClassification. Set Name (required). Set Specification (IFC4.3) or
|       Location (IFC4) to the system URI.
|
+-- One code from a system (e.g. one Uniclass code)
|   --> IfcClassificationReference. Put the code in Identification (IFC4+)
|       or ItemReference (IFC2x3). Point ReferencedSource at the system.
|
+-- Binding a code (or a system) to objects
|   --> IfcRelAssociatesClassification. RelatedObjects = the objects,
|       RelatingClassification = the IfcClassificationReference.
|
+-- An external specification, datasheet, or product library item
    --> IfcLibraryReference + IfcLibraryInformation, bound by
        IfcRelAssociatesLibrary. NOT a classification entity.

Where does the code string go?

You have a code like "EF_25_10". Which attribute?
|
+-- IFC4 / IFC4.3 --> IfcClassificationReference.Identification
|
+-- IFC2x3        --> IfcClassificationReference.ItemReference
|
+-- NEVER         --> IfcClassificationReference.Name  (Name is the readable
                      title; the code is not a title)

Flat code or nested tree?

Do you need a classification hierarchy in the file?
|
+-- One code, no parent
|   --> IfcClassificationReference.ReferencedSource = the IfcClassification.
|
+-- A child code under a parent code (IFC4 / IFC4.3)
|   --> child IfcClassificationReference.ReferencedSource = the parent
|       IfcClassificationReference. The parent's ReferencedSource is the
|       IfcClassification. This nests because ReferencedSource is typed
|       IfcClassificationReferenceSelect.
|
+-- A hierarchy in IFC2x3
    --> ReferencedSource on the reference can only point at IfcClassification.
        The IFC2x3 tree is built with IfcClassificationItem instead. Do NOT
        try to nest IfcClassificationReference in an IFC2x3 file.

Patterns

Pattern : Classify objects with one shared relationship

ALWAYS model a classification as three entities : one IfcClassification (the system), one IfcClassificationReference per distinct code, and one IfcRelAssociatesClassification linking that reference to every object that carries the code. ALWAYS list every object with the same code in the single relationship's RelatedObjects set. NEVER emit a separate IfcRelAssociatesClassification per object when the code is identical : that bloats the file and adds nothing. ALWAYS classify the type object (IfcWallType) when every occurrence of that type shares the code; classify the occurrence (IfcWall) only when one element deviates from its type.

See ifc-core-relationships for the IfcRelAssociates family and ifc-impl-data-enrichment for the workflow of adding classifications to a model.

Pattern : Put the code in the code attribute

ALWAYS write the classification code string into IfcClassificationReference.Identification in IFC4 and IFC4.3, or into ItemReference in IFC2x3. ALWAYS write the human-readable title of the classified item into Name. NEVER swap the two : a reader extracting codes queries Identification (or ItemReference), and a code hidden in Name is invisible to that reader.

Pattern : Point the reference at its system

ALWAYS set IfcClassificationReference.ReferencedSource to the IfcClassification that names the system the code belongs to. A reference with no ReferencedSource is an orphan code with no system context. ALWAYS set IfcClassification.Name (the only required attribute) to the system's common name, such as 'Uniclass 2015'.

Pattern : Build a nested classification tree (IFC4 / IFC4.3)

ALWAYS build a hierarchy by setting a child IfcClassificationReference.ReferencedSource to its parent IfcClassificationReference, and the top reference's ReferencedSource to the IfcClassification. This works because ReferencedSource is typed IfcClassificationReferenceSelect, which accepts both. NEVER attempt this nesting in IFC2x3 : there ReferencedSource is typed IfcClassification only, and a hierarchy uses the separate IfcClassificationItem mechanism.

Pattern : Honour the version differences

ALWAYS write the system URI into IfcClassification.Specification in IFC4.3 and into IfcClassification.Location in IFC4. The attribute was renamed; using the wrong name yields an unknown-attribute error. ALWAYS use Identification for the code in IFC4 and IFC4.3, and ItemReference in IFC2x3. NEVER copy an IFC2x3 IfcClassification instance verbatim into an IFC4 file : IFC2x3 IfcClassification is a standalone entity with four attributes, while IFC4 adds Description, Location, and ReferenceTokens and a supertype. See ifc-impl-version-migration for the migration procedure.

Pattern : Reference an external library

ALWAYS model an external specification or datasheet with IfcLibraryInformation (the library as a whole) and IfcLibraryReference (one item in it), bound to objects by IfcRelAssociatesLibrary. ALWAYS set IfcLibraryReference.ReferencedLibrary to the owning IfcLibraryInformation in IFC4 and IFC4.3. NEVER use a classification entity for a library item : a classification taxonomy and a reference library are distinct concepts with distinct entities.

Reference Links

references/methods.md : the complete verified entity definitions for IFC2x3, IFC4, and IFC4.3, the IfcClassificationSelect / IfcClassificationReferenceSelect / IfcClassificationNotationSelect / IfcLibrarySelect select types, and the inherited IfcExternalReference / IfcExternalInformation attributes.
references/examples.md : worked STEP scenarios : a Uniclass system and code, a shared relationship over many walls, a nested code tree, an IFC2x3 classification, and a library reference.
references/anti-patterns.md : the failure modes this skill prevents, each with the reason it fails.

Official sources

IfcClassification (IFC4.3) : https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcClassification.htm
IfcClassificationReference (IFC4.3) : https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcClassificationReference.htm
IfcRelAssociatesClassification (IFC4.3) : https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcRelAssociatesClassification.htm
IfcRelAssociatesLibrary (IFC4.3) : https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcRelAssociatesLibrary.htm
IfcLibraryReference (IFC4.3) : https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcLibraryReference.htm
IfcLibraryInformation (IFC4.3) : https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcLibraryInformation.htm
IfcClassification (IFC4) : https://standards.buildingsmart.org/IFC/RELEASE/IFC4/ADD2_TC1/HTML/schema/ifcexternalreferenceresource/lexical/ifcclassification.htm
IfcClassification (IFC2x3) : https://standards.buildingsmart.org/IFC/RELEASE/IFC2x3/TC1/HTML/ifcexternalreferenceresource/lexical/ifcclassification.htm

Related skills

ifc-core-relationships : the IfcRelAssociates family that IfcRelAssociatesClassification and IfcRelAssociatesLibrary belong to.
ifc-impl-data-enrichment : the workflow of adding classifications to an existing model.
ifc-impl-version-migration : migrating classification entities between IFC2x3, IFC4, and IFC4.3.

About this skill

Quick Reference

The three classification entities

IfcClassification : the system

IfcClassificationReference : one code

IfcRelAssociatesClassification : the link

The library entities (brief)

External classification systems

Version differences (compact)

Decision Trees

Which entity do I need?

Where does the code string go?

Flat code or nested tree?

Patterns

Pattern : Classify objects with one shared relationship

Pattern : Put the code in the code attribute

Pattern : Point the reference at its system

Pattern : Build a nested classification tree (IFC4 / IFC4.3)

Pattern : Honour the version differences

Pattern : Reference an external library

Reference Links

Official sources

Related skills