Request

Response

    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:

    ValueTypical 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 by system and value, and doesn’t touch any existing sourceId.
    • Passing a sourceId that matches what’s already on that classification node is a no-op reuse.
    • Passing a sourceId that differs from an existing, non-empty sourceId on that node throws ArgumentException — 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");
    
    Show More

    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-standard Custom system such as OmniClass, without the two competing for the same field.
    • Stable identity across syncs — use sourceId to recognize a classification you created in an earlier sync even after a user renames it in the host application.

    See also