ECSchema XML

ECSchema XML is the XML representation of an ECSchema. It is a persistent interchange format for EC metadata: schemas, classes, properties, relationships, custom attributes, enumerations, quantities, units, and formats.

ECXML historically covered both metadata and instance data. Current iTwin schema workflows use ECSchema XML for schema metadata, while ECInstance XML appears most often as custom attribute instances embedded inside ECCustomAttributes elements.

This page documents the ECSchema XML 3.2 shape used by current iTwin schemas. The XML format describes the persisted schema document. The semantic rules for each EC item are documented on the linked EC pages and enforced by EC schema validation.

Namespace and Version

An ECSchema XML document has an ECSchema root element in an ECXML namespace.

The version attribute is the schema version, not the ECXML format version. It uses the RR.WW.mm form described by ECSchema: read version, write version, and minor version.

Common ECXML namespaces are:

Root Element

The ECSchema element contains schema-level metadata, references, custom attributes, and schema items.

Attributes

Child Elements

The schema root may contain these child elements. Schema item names must be unique within the schema.

Schema References

An ECSchemaReference identifies another schema used by this schema.

Schema Items

Most schema items share these attributes:

References to items in the same schema may use the item name, such as PhysicalElement. References to items in another schema use the reference alias, such as bis:PhysicalElement.

Classes

The EC class elements are ECEntityClass, ECStructClass, ECCustomAttributeClass, and ECRelationshipClass. See ECClass, ECEntityClass, ECStructClass, ECCustomAttributeClass, and ECRelationshipClass for their semantics.

Common class attributes:

Common class child elements:

Example:

Custom Attribute Classes

ECCustomAttributeClass adds an appliesTo attribute that lists the container types where instances of the custom attribute may be applied. See ECCustomAttributeClass for its semantics.

The list may be separated by commas, semicolons, or vertical bars.

Relationship Classes

ECRelationshipClass defines the relationship itself and contains Source and Target constraint elements. See ECRelationshipClass for its semantics.

Source and Target constraints have these attributes:

Each constraint contains one or more Class elements with a required class attribute. Source constraints support one class semantically; target constraints may support more than one.

For holding and embedding relationships, strengthDirection determines which endpoint acts as the parent or owner. forward means the source endpoint has that role; backward means the target endpoint has that role. Do not infer ownership from the endpoint names alone.

Properties

EC property elements are split by property kind. This is intentional: each property kind has a different XML shape and maps naturally to different typed APIs. See ECProperty for its semantics.

Common property attributes:

Property elements:

Array properties may define minOccurs and maxOccurs. maxOccurs may be a non-negative integer or unbounded.

Navigation properties use direction="forward" or direction="backward".

Enumerations

ECEnumeration defines a named enumeration with either an integer or string backing type. See ECEnumeration for its semantics.

Each ECEnumerator has a required name and value, with optional description and displayLabel.

Quantities, Units, and Formats

ECXML 3.2 includes units and formats as schema items. See KindOfQuantity, Unit, Constant, Phenomenon, UnitSystem, and Format for semantic details.

Common shapes:

In ECXML 3.2, KindOfQuantity/@persistenceUnit is a unit reference, not a legacy format string. Presentation formats belong in presentationUnits.

The presentationUnits attribute is a semicolon-separated list of format references or format override strings. A format override can change the precision, add units to a unitless format, or override unit labels. See KindOfQuantity format overrides for the full syntax.

Custom Attributes

ECCustomAttributes contains ECInstance XML for custom attribute instances applied to the parent schema, item, relationship constraint, or property. See ECCustomAttributes for its semantics.

The custom attribute element namespace is commonly the custom attribute schema full name, such as CoreCustomAttributes.01.00.03.

ECInstance XML in Custom Attributes

Each child element of ECCustomAttributes is an instance of an ECCustomAttributeClass. The element name identifies the custom attribute class, and the element's child elements are property values for that custom attribute instance.

The type of each value is determined from the custom attribute class definition in the referenced schema. A schema item can have multiple custom attributes, but only one instance of a given custom attribute class may be applied to the same container.

Validation

The XSD for ECSchema XML validates the XML document shape: allowed elements, attributes, simple value patterns, and some uniqueness rules. It does not express every semantic EC rule. Semantic rules such as relationship constraint compatibility, reference resolution, property override compatibility, and custom attribute applicability are covered by EC Schema Validation.

The ECXML 3.2 XSD is maintained in the BIS schemas repository at System/xsd/ECSchemaXML3.2.xsd. It is intentionally XSD 1.0 compatible for broad tool support, including .NET XML tooling. A companion XSD 1.1 file may provide optional assertions for validators that support XSD 1.1.

Version Notes

ECXML has evolved with ECObjects:

For current schemas, prefer ECXML 3.2 unless a repository or product explicitly requires an older format.