An ECName is used any time an invariant, string based, name is needed for an element in a schema. These strings must follow the following rules:
- Must contain at least one character
- Must contain only alpha numeric characters plus
- May not start with a number or
- May not contain spaces
- Case is allowed but all comparisons are case insensitive. E.g. PIPE == Pipe
These rules are designed to ease code generation and mapping into databases.
If coming from a system with less restrictive naming rules some valid ECName must be chosen for each named element in the schema. There are two common options suggested.
- Replace illegal characters with a similar legal character and swizzle names to be unique if necessary. The original name can be placed in the display label for the element so it shows in the UI
- Replace invalid characters with a special sequence
HHHHis the character code for the replaced character. Names created this way will automatically be converted back to their original form for display so the display label should be left unset. This option has the upside of preserving all names with no swizzle but produces ugly invariant names.
Different ECName Representations
There are many different ways to represent an ECName depending on the context they need to be referred to. This section explains each one and the differences between them.
ECSchema Full Name
The Schema full name contains the name of the schema in addition to the 3-part version number.
A full name is comprised of the schema name, or schema full name, and the name of the schema item, an ECName. It can either be separated by a
: separator is the most common and has long been the preferred separator. However, the
. has been used by WSG and more recently introduced into the ECSchemaJSON format and may continue to become more widely spread and supported.
Note: If the schema full name is used then the
: separator must be used.
: separator without schema version:
: separator with schema version:
An ECSql name contains the same information as the full name but has a slightly different format to be used in an ECSql context. Square braces,
[, are added around each item to escape any naming conflicts with reserved keywords in ECSql.
The ECSql Name like its name suggests is only ever used within the context of ECSql and is not supported, or recommended, for use outside of it.
A qualified name contains the schema's alias, if the schema item exists within a reference schema, and the schema item name, an ECName.
This is no longer the preferred way of identifying a class within the context of its parent ECSchema, using full name is now preferred. The qualified name is currently only supported in the ECXML format for references.
Last Updated: 15 June, 2021