XmiSchema 0.13.2

XMI Schema - Cross Model Information

XMI (Cross Model Information) is an open-source file format schema designed to represent built environment data. This C# library provides a complete implementation for constructing, validating, and serializing XMI graphs representing structural analytical and physical building elements.

What is Cross Model Information?

Cross Model Information (XMI) is a graph-based data schema specifically designed for the Architecture, Engineering, and Construction (AEC) industry. It enables seamless exchange of structural and physical building data between different software platforms, analysis tools, and BIM (Building Information Modeling) systems.

Key Characteristics

• Graph-Based Architecture: Entities (nodes) are connected via typed relationships (edges), enabling rich semantic connections between building elements
• Domain-Specific: Purpose-built for structural engineering and physical building representation
• Interoperable: Supports IFC GUID references for integration with Industry Foundation Classes (IFC) workflows
• Lightweight: JSON serialization for human-readable, easily parseable output
• Extensible: Modular entity and relationship system allows for domain-specific extensions

Relationship to Industry Standards

Industry Foundation Classes (IFC)

XMI is designed to complement and integrate with IFC (Industry Foundation Classes), the ISO-certified open standard for BIM data exchange:

XMI entities include an ifcGuid property, allowing direct mapping to IFC elements for round-trip workflows between BIM authoring tools and structural analysis software.

Schema Design Principles

Following industry best practices for AEC data schemas:

1. Unique Identification: Every entity has a stable id, optional ifcGuid for IFC interoperability, and nativeId for source system traceability
2. Polymorphic Serialization: EntityName discriminator enables type-safe deserialization of heterogeneous entity collections
3. Domain Classification: Entities include a Domain field (Physical, StructuralAnalytical, Geometry, Functional, Shared) to make payload routing explicit
4. Explicit Relationships: Graph edges (relationships) are first-class citizens with their own identity and metadata
5. Unit Awareness: XmiUnit entities define measurement units for proper unit conversion across systems
6. Tolerance-Aware Geometry: Point deduplication with configurable geometric tolerance prevents duplicate coordinates

Installation

Install via NuGet Package Manager:

dotnet add package XmiSchema

Or via Package Manager Console:

Install-Package XmiSchema

Quick Start

using XmiSchema.Managers;
using XmiSchema.Entities.Commons;
using XmiSchema.Entities.StructuralAnalytical;
using XmiSchema.Entities.Geometries;
using XmiSchema.Enums;

// Initialize manager and model
var manager = new XmiManager();
manager.Models.Add(new XmiModel());

// Create a storey
var storey = manager.CreateXmiStorey(
    modelIndex: 0,
    id: "storey-1",
    name: "Level 1",
    ifcGuid: "2O2Fr$t4X7Zf8NOew3FL9r",
    nativeId: "LEVEL_1",
    description: "Ground floor",
    storeyElevation: 0,
    storeyMass: 800);

// Create a material
var material = manager.CreateXmiMaterial(
    modelIndex: 0,
    id: "mat-1",
    name: "Concrete C40",
    ifcGuid: "3$HnSh4fn5$vQIE9d8M0L9",
    nativeId: "MAT_C40",
    description: "High-strength concrete",
    materialType: XmiMaterialTypeEnum.Concrete,
    grade: 40,
    unitWeight: 24,
    eModulus: "33000",
    gModulus: "13000",
    poissonRatio: "0.2",
    thermalCoefficient: 1.0);

// Create points with automatic deduplication
var point1 = manager.CreateXmiPoint3D(0.0, 0.0, 0.0, "pt-1");
var point2 = manager.CreateXmiPoint3D(0.0, 0.0, 3.0, "pt-2");

// Create structural nodes
var node1 = manager.CreateXmiStructuralPointConnection(
    modelIndex: 0, id: "node-1", name: "Node 1", 
    ifcGuid: "", nativeId: "", description: "", point: point1);

var node2 = manager.CreateXmiStructuralPointConnection(
    modelIndex: 0, id: "node-2", name: "Node 2", 
    ifcGuid: "", nativeId: "", description: "", point: point2);

// Create segments with positions
var segments = new List<XmiSegment>
{
    new XmiSegment("seg-1", "Segment 1", "", "seg-1", "", XmiSegmentTypeEnum.Line)
};
var positions = new List<int> { 0 };

// Create a structural curve member
var column = manager.CreateXmiStructuralCurveMember(
    modelIndex: 0,
    id: "col-1", name: "Column 1", ifcGuid: "", nativeId: "col-1", description: "",
    material: material, crossSection: null, storey: storey,
    curveMemberType: XmiStructuralCurveMemberTypeEnum.Column,
    nodes: new List<XmiStructuralPointConnection> { node1, node2 },
    segments: segments, positions: positions,
    systemLine: XmiSystemLineEnum.MiddleMiddle,
    beginNode: node1, endNode: node2, length: 3.0,
    localAxisX: new XmiAxis(1, 0, 0), localAxisY: new XmiAxis(0, 1, 0), localAxisZ: new XmiAxis(0, 0, 1),
    beginNodeXOffset: 0, endNodeXOffset: 0, beginNodeYOffset: 0, endNodeYOffset: 0,
    beginNodeZOffset: 0, endNodeZOffset: 0,
    endFixityStart: "Fixed", endFixityEnd: "Fixed");

// Serialize to JSON
var json = manager.BuildJson(0);
Console.WriteLine(json);

Key API Changes

• Segment Positioning: Segment positions are now handled through XmiHasSegment relationships with a positions array
• Automatic Deduplication: Points, lines, and arcs with identical coordinates/geometries are automatically reused
• Required Parameters: Factory methods now require positions parameter when segments are provided
• End Fixity: Structural curve members require both endFixityStart and endFixityEnd parameters

Entity Types

Physical Elements

Physical building components that represent real-world objects:

Analytical Elements

Abstract representations for structural analysis:

Common Entities

Geometry

Relationships

XMI uses explicit relationship entities to connect nodes in the graph:

Supported Cross-Section Shapes

XMI supports parametric cross-section definitions:

• Rectangular
• Circular
• I-Shape (Wide Flange)
• T-Shape
• L-Shape (Angle)
• C-Shape (Channel)
• Hollow Rectangular (Box)
• Hollow Circular (Pipe)

JSON Output Format

XMI serializes to a clean JSON structure:

{
  "Entities": [
    {
      "id": "mat-1",
      "Name": "Concrete C40",
      "ifcGuid": "3$HnSh4fn5$vQIE9d8M0L9",
      "NativeId": "MAT_C40",
      "Description": "High-strength concrete",
      "EntityName": "XmiMaterial",
      "Domain": "Shared",
      "MaterialType": "Concrete",
      "Grade": 40,
      "UnitWeight": 24
    }
  ],
  "Relationships": [
    {
      "id": "rel-1",
      "EntityName": "XmiHasMaterial",
      "SourceId": "col-1",
      "TargetId": "mat-1"
    }
  ]
}

Building from Source

Prerequisites

• .NET 8.0 SDK

Build and Test

# Clone the repository
git clone https://github.com/xmi-schema/xmi-schema-csharp.git
cd xmi-schema-csharp

# Restore dependencies
dotnet restore XmiSchema.sln

# Build
dotnet build XmiSchema.sln

# Run tests (266 unit tests)
dotnet test XmiSchema.sln

# Run specific test
dotnet test --filter "FullyQualifiedName~XmiBeamTests"

Run the Example

dotnet run --project tests/Examples/StructuralGraphSample/StructuralGraphSample.csproj

Documentation

Inline Documentation

Documentation is now located alongside the code in respective namespace folders:

• Entities/Bases/ - Base classes and core abstractions
• Entities/Commons/ - Common domain entities (materials, cross-sections, storeys)
• Entities/Physical/ - Physical building elements (beams, columns, slabs, walls)
• Entities/StructuralAnalytical/ - Analytical structural elements
• Entities/Geometries/ - Geometric primitives (points, lines, arcs)
• Entities/Relationships/ - Graph relationships connecting entities
• Enums/ - Domain enumerations with serialization attributes
• Parameters/ - Shape parameter definitions and factories
• Utils/ - Utility classes and extension methods
• Managers/ - XmiModel and XmiManager orchestration classes

High-Level Documentation

• docs/examples/StructuralGraphSample.md - Complete working example
• docs/reference/ - Additional reference materials

Key Class Documentation

• Entities/Commons/XmiSegment.md - Segment class reference
• Managers/XmiModel.md - Model management and factory methods
• Managers/XmiManager.md - Multi-model orchestration

Resources

• Website: https://xmi-schema.com
• NuGet Package: XmiSchema on NuGet
• IFC Standard: buildingSMART IFC

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

This project is open source. See the repository for license details.