Organizing Definition Elements
Instances of DefinitionElement hold configuration-related information that is meant to be referenced and shared. They are expected to be contained in DefinitionModel
s as explained in Model Fundamentals.
Examples of DefinitionElement
s include instances of:
Category
andSubcategory
TypeDefinitionElement
RenderMaterial
PhysicalMaterial
LineStyle
- etc.
Definition Rank
Some DefinitionElement
instances are introduced in an iModel for standardization. This is done at various ranks of the BIS ecosystem. The ranks to keep in mind in this discussion are:
- Core: standardized definitions that are semantically at the "Core" and "Common" layers of the BIS schema hierarchy. There are actually no examples of these to-date.
- Discipline: standardized definitions at the "Discipline-Physical" or "Discipline-Other" layers of the BIS schema hierarchy.
- Application: application-specific definitions. Note that applications and connectors should endeavor to define and use standardized domains, so this does not mean "any definition written by a connector".
- User: most definitions, which are user-specific or project-specific.
Definition scope
The Subject
hierarchy in the repository essentially defines various levels of scope. The Root Subject
is a "global" scope and all other Subjects
define narrower scopes.
Each Subject
can have 0 or 1 child DefinitionPartition
element which is sub-modeled by a DefinitionModel
.
DictionaryModel (for global-scoped definitions)
The DefinitionPartion
of the Root Subject
always has a CodeValue
of "BisCore.DictionaryModel". Its sub-model is called the "DictionaryModel". The DictionaryModel is a singleton container of DefinitionElement
instances. It directly holds User-rank definitions and holds Core, Discipline, and Application-standardized definitions organized under DefinitionContainer
s.
- For Discipline-rank definitions, there should be a
DefinitionContainer
with aCodeValue
of "{domain alias}:DomainDefinitions" (where {domain alias} is the schema alias for the domain that is doing the standardization - which might be different than the schema that defines the particularDefinitionElement
subclass) - and aCodeScope
that is the ElementId of theDefinitionModel
that contains it. Domain-standardized definitions should go in the sub-model of thatDefinitionContainer
. - For standardized Application-rank definitions, there should be a
DefinitionContainer
with aCodeValue
of "{application name}:ApplicationDefinitions" and aCodeScope
that is the Id of theDefinitionModel
that contains it. Application-standardized definitions should go in the sub-model of that `DefinitionContainer. - For Core-rank definitions, there should be a
DefinitionContainer
with aCodeValue
of "bis:CoreDefinitions" and aCodeScope
that is the Id of theDefinitionModel
that contains it. BIS-standardized definitions should go in the sub-model of thatDefinitionContainer
.
All global-scoped Core-rank, Discipline-rank and Application-rank definitions should be organized under the DictionaryModel.
As an example of domain-ranked definitions, the "Terrain" domain (with prefix "trrn") defines a set of standard Category
elements and the "Earthworks" domain (with prefix "ew") defines some standard PhysicalType
elements to be used with Connectors and Applications that support that domain. See diagram below.
Subject-specific definitions
Only User-rank definitions should be placed in Subject-specific DictionaryModel
s, which are typically created by iModel Connectors. In that case, the DefinitionPartion
for Subject-specific definitions should have a CodeValue
of "Definitions" and CodeScope
of its parent Subject
.
Example organization of definitions
The following instance-diagram depicts the organization of definition elements of various ranks and scopes. See Instance-diagram Conventions for details about the conventions used.
| Next: 3D Guidance |:---
Last Updated: 21 November, 2022