Working with classification
Classification is how you tag an element with the taxonomy your host application already uses — a Revit category, an AutoCAD layer, an IFC entity class, or a discipline. Classify and ClassificationSystem give you a typed way to do this that doesn’t depend on getting a string exactly right.
Why classification is separate from element creation
Before this API, an element’s category, family, and type were free-text fields baked into its constructor. Code like Classify(element, "Categori", "Walls") — a one-character typo — compiled without complaint and ran without an exception. It just silently produced data that didn’t match anything, fragmenting what should have been a single “Walls” category into two.
Classify decouples tagging from element creation, and ClassificationSystem replaces the free-text system name with a fixed, typed set of well-known values. A typo in a well-known system name is now a compile error instead of a runtime data-quality problem. Classification is entirely optional — the SDK does not require any element to have a category, family, or type hierarchy.
Classify an element
Call Classify after creating an element to tag it under a classification system:
var wall = elementDataModel.AddElement("wall-001", "Exterior Wall");
elementDataModel.Classify(wall, ClassificationSystem.Category, "Walls");
Classify finds or creates the (”Walls” under Category) classification node and attaches the element to it, then returns an IClassification handle you can reuse — for example, as the parent for a nested classification, or to read back Id, Value, System, and SourceId later.
Well-known classification systems
ClassificationSystem ships nine well-known values covering the taxonomies most host applications already use:
| Value | Typical use |
|---|---|
Category |
Top-level element category (Walls, Doors, Windows) |
SubCategory |
A nested category within Category |
Family |
Element family (for example, a Revit "Basic Wall" or "Curtain Wall") |
Layer |
Organizational layer (AutoCAD, Rhino, ArchiCAD, MicroStation, 3ds Max, SketchUp) |
Group |
Named object grouping (AutoCAD, Rhino, 3ds Max, SketchUp) |
Discipline |
Engineering discipline (Architectural, Structural, Mechanical) |
Phase |
Project phase (New, Existing, Demolished) |
Level |
Building level or floor (L1, L2, Roof) — not the MicroStation "Level," which maps to Layer |
IfcClass |
IFC entity class (IfcWall, IfcSlab, IfcDoor) |
If your connector needs a system that isn’t in this list — an industry-specific standard such as OmniClass, or a host-specific taxonomy — use ClassificationSystem.Custom:
elementDataModel.Classify(wall, ClassificationSystem.Custom("OmniClass"), "23.30.10");
Custom requires the name to be PascalCase with no whitespace (for example, "OmniClass" or "WorkSet") and throws ArgumentException otherwise. This keeps every custom system name in your connector consistent, and lets you grep a codebase for .Custom( to find every non-standard system in use. Comparison between ClassificationSystem values — well-known or custom — is case-insensitive.
Build a classification hierarchy
Pass a previously returned IClassification as the parent argument to nest one classification under another:
var category = elementDataModel.Classify(wall, ClassificationSystem.Category, "Walls");
var family = elementDataModel.Classify(wall, ClassificationSystem.Family, "Basic Wall", parent: category);
The element attaches to the deepest classification in the chain — here, Basic Wall — not every level. To read the hierarchy back, walk IClassification.Parent from any leaf classification up to the root:
var leaf = wall.Classifications.First();
for (var node = leaf; node != null; node = node.Parent)
{
Console.WriteLine($"{node.System}: {node.Value}");
}
Reuse and conflicts: the sourceId rule
sourceId lets your connector attach its own stable identifier to a classification node, so you can recognize “the same” classification across sync operations even if its Value is later renamed. The rule is: reuse silently, or throw on genuine conflict.
- Passing
sourceId: null(or omitting it) means “no opinion” — the call finds or creates the classification purely bysystemandvalue, and doesn’t touch any existingsourceId. - Passing a
sourceIdthat matches what’s already on that classification node is a no-op reuse. - Passing a
sourceIdthat differs from an existing, non-emptysourceIdon that node throwsArgumentException— the SDK will not silently overwrite one connector-assigned id with another.
// First call establishes the sourceId.
elementDataModel.Classify(wall, ClassificationSystem.Category, "Walls", sourceId: "host-cat-42");
// Later call with the SAME sourceId is a safe no-op reuse.
elementDataModel.Classify(otherWall, ClassificationSystem.Category, "Walls", sourceId: "host-cat-42");
// A DIFFERENT sourceId for the same (system, value) throws ArgumentException.
elementDataModel.Classify(thirdWall, ClassificationSystem.Category, "Walls", sourceId: "host-cat-99");
Read classification from an element
IElement.Classifications returns the leaf classification nodes attached directly to an element — empty if the element is unclassified:
foreach (var classification in wall.Classifications)
{
Console.WriteLine($"{classification.System}: {classification.Value} (source: {classification.SourceId})");
}
Use cases
- Preventing silent data fragmentation — replace ad hoc string concatenation for category/family tags with a fixed set of systems, so a typo fails at compile time instead of producing an orphaned classification node.
- Cross-application taxonomies — tag the same element with both a
Category(from the host UI) and an industry-standardCustomsystem such as OmniClass, without the two competing for the same field. - Stable identity across syncs — use
sourceIdto recognize a classification you created in an earlier sync even after a user renames it in the host application.
See also
- Working with types — the privileged classification that backs a reusable, shared type definition
- Working with design instancing