Navigation properties and relationships for annotation elements

[Alfonso-Martello]

This is an issue asking for guidance on the best way to expose a style navigation property for the various annotation elements used by Drawing Production. It is related to the recommendations from the BWG meeting on 08/01/2025. There was a brief asynchronous discussion about this with @ColinKerr and this issue is a place for that discussion to continue and for others to chime in.

There are 5 ECEntityClasses that need to refer to a style. They are:

1. TextAnnotation2d refers to an AnnotationTextStyle
2. TextAnnotation3d refers to an AnnotationTextStyle
3. Table refers to an AnnotationTextStyle
4. Dimension refers to a DimensionStyle
5. DimensionStyle refers to an AnnotationTextStyle

Does each ECNavigationProperty need to refer to a new ECRelationshipClass? So we would end up with this setup:

1. TextAnnotation2d refers to AnnotationTextStyle via relationship TextAnnotation2dUsesAnnotationTextStyle
2. TextAnnotation3d refers to AnnotationTextStyle via relationship TextAnnotation3dUsesAnnotationTextStyle
3. Table refers to AnnotationTextStyle via relationship TableUsesAnnotationTextStyle
4. Dimension refers to a DimensionStyle via relationship DimensionUsesDimensionStyle
5. DimensionStyle refers to an AnnotationTextStyle via relationship DimensionStyleUsesTextStyle

Or should we do something else?

TextAnnotation2ds, Tables, and Dimensions all extend the AnnotationElement2d concrete class. Is it possible to create a more generic Annotation2dUsesStyle relationship that could be on this base class? Should we use a mixin?

cc: @ColinKerr, @diegoalexdiaz, @pmconne, @Josh-Schifter, @SheetalNair

[pmconne]

All of those classes will need to derive from the new BisCore:ITextAnnotation mix-in (the first two already do). That seems like the logical class for the relationship source.

[ColinKerr]

Here is an example of a navigation property:

Relationship:

    <ECRelationshipClass typeName="CodeSpecSpecifiesCode" strength="referencing" modifier="Sealed">
        <!-- @see Element.CodeSpec ECNavigationProperty -->
        <Source multiplicity="(1..1)" roleLabel="specified code for" polymorphic="true">
            <Class class="CodeSpec"/>
        </Source>
        <Target multiplicity="(0..*)" roleLabel="code is specified by" polymorphic="true">
            <Class class="Element"/>
        </Target>
    </ECRelationshipClass>

Navigation Property:

    <ECEntityClass typeName="Element" modifier="Abstract" description="Most abstract class and smallest individually identifiable building block for modeling Entities in a BIS repository.">
        <ECNavigationProperty propertyName="CodeSpec" displayLabel="Code Specification" relationshipName="CodeSpecSpecifiesCode" direction="backward" />

Important things to note:

• Relationship modifier (modifier="Sealed"): If Sealed then it will be stored as a single column in the db, the id of the related element. If None it will be stored as two columns, the id of the related element and the id of the relationship class. Using None is useful if you want to differentiate between different kinds of relationships.
• Multiplicity (multiplicity="(1..1)"): The endpoint the navigation property points to must have a multiplicity of 1..1 or 0..1. 1..1 means one and only one, 0..1 means zero or one. This makes sense because it’s a single property so it can only store one id. NOTE the other endpoint may have any multiplicity based on the nature of your relationship.
• Role Label (roleLabel="specified code for"): Read in format e.g. ‘CodeSpec specified code for Element’ or ‘Element code is specified by CodeSpec’ in this case.
• Direction on Nav Prop (direction="backward" ): In this case it’s backwards because we’re going from target to source

Relationship constraint attributes (e.g. multiplicity, role label): https://www.itwinjs.org/bis/ec/ec-relationship-class/#attributes
Relationship naming guidelines: https://www.itwinjs.org/bis/guide/naming-guidelines/rules-and-recommendations/#relationship
Nav prop docs: https://www.itwinjs.org/bis/ec/ec-property/#ecnavigationproperty
Class attributes w/ docs on modifier: https://www.itwinjs.org/bis/ec/ec-class/#common-class-attributes

As @pmconne notes a common mixin is a possible candidate for the navigation property as a way to have a common definition. see ILinearElement mixin from the LinearReferencing schema as an example of a nav prop on a mixin:

bis-schemas/Domains/1-Common/LinearReferencing/Released/LinearReferencing.02.00.03.ecschema.xml

Line 28 in db51083

<ECNavigationProperty propertyName="LinearElementSource" relationshipName="ILinearElementProvidedBySource" direction="Forward" displayLabel="Source" description="Source element providing this Linear-Element."/>

. You could potentially create a new mixin just to have a common definition for the nav prop for every class that points to a AnnotationTextStyle. This is a useful abstraction if you want to be able to polymorphicly query for this. For example you could query for all text annotations that were used more easily.

[Alfonso-Martello]

Thank you, @ColinKerr, that was extremely helpful reading. One follow-up question, I noticed a possible slight discrepancy in the documentation. The modified property has None listed as “Not valid for ECRelationshipClass type”, but your comment explains what None does on a relationship class AND I can see instances of ECRelationshipClass with the None modifier, like

    <ECRelationshipClass typeName="ElementOwnsChildElements" strength="embedding" modifier="None" description="Relates a bis:Element to child bis:Elements which represent parts of the Entity modeled by the parent bis:Element.">
        <!-- @see Element.Parent ECNavigationProperty -->
        <!-- NOTE: Was not made abstract because of too many legacy situations. -->
        <Source multiplicity="(0..1)" roleLabel="owns child" polymorphic="true">
            <Class class="Element"/> <!-- Logically should be IParentElement, but that mixin was invented later. -->
        </Source>
        <Target multiplicity="(0..*)" roleLabel="is owned by parent" polymorphic="true">
            <Class class="Element"/>
        </Target>
    </ECRelationshipClass>

[Alfonso-Martello]

All of those classes will need to derive from the new BisCore:ITextAnnotation mix-in (the first two already do). That seems like the logical class for the relationship source.

I really liked this suggestion, but thinking about it more there are some wrinkles that make me wonder if we should just keep it simple and have the 5 separate navigation properties/relationships. The wrinkles are as follows:

DimensionStyles do not implement ITextAnnotation

They are styles and do not have any text, so I assume this will need its own navigation property and relationship. Still, we could standardize the annotation classes except…

Dimensions refer to DimensionStyles, not AnnotationTextStyles

Based on my understanding, to allow a relationship to target multiple classes, we would need to introduce a new base "AnnotationStyle" class that Dimension and Text styles extend. Then the relationship would target the new “AnnotationStyle” class and be polymorphic. Thus, our navigation property/relationship from the ITextAnnotation would…

Allow any ITextAnnotation to refer to any AnnotationStyle, but Dimensions only understand DimensionStyles and Text/Tables only understand AnnotationTextStyles

Who would be responsible for preventing bad data from being inserted into the iModel (aka a TextAnnotation2d that refers to a DimensionStyle)? Is that something we would be able to prevent in the schema while still supporting all of the annotation classes? Is this even a problem?

By making the text style a navigation property in the schema, we are separating the style from the TextBlock

Currently, TextBlocks are largely self-contained data units. You get a TextBlock, it knows its style. After the changes from the BWG meeting, any code that currently works with a TextBlock will need to also accept a style argument to know which style to use. This is true for the ITextAnnotation mix-in as well. This is fine, but if we make the navigation property part of the mix-in, two things quickly become more complicated:

1. Dimensions are still different. The mix-in would need special logic to recognize that it is a dimension and then traverse the relationship from the DimensionStyle to get the TextAnnotationStyle.
2. Our assumption underpinning this change is that styles are for a purpose, and users are not going to want to mix them. Drawing Production does not have users yet, so this has not been extensively vetted. It is possible our assumption is wrong, and users will want multiple styles within their annotation. We would like to be able to handle this in a non-breaking way. To support this, we would probably want to have the ability for a class to tell the ITextAnnotation interface “this is my text block and this is the style it uses”. I am not sure how different it is to have the navigation property on the class vs. on the mix-in implemented by the class. @Josh-Schifter do you have any thoughts on this?

You could potentially create a new mixin just to have a common definition for the nav prop for every class that points to a AnnotationTextStyle. This is a useful abstraction if you want to be able to polymorphicly query for this. For example you could query for all text annotations that were used more easily.

I could see a new mix-in for the 3 annotations that use the AnnotationTextStyle, I just do not think it could be applied to Dimensions and therefore could not be part of the ITextAnnotation mix-in

[Alfonso-Martello]

I went ahead and added a draft pull request detailing how I think the schema could/should work. Happy for any feedback!

[diegoalexdiaz]

Let's summarize the different intents behind the concepts listed above.

1. ITextAnnotation was introduced coupled with ElementDrivesTextAnnotation, as pieces of the bigger puzzle that allows portions of text-content to be computed from property-values in other Elements. Thus, I agree that DimensionStyle doesn't need to mix this interface in.

2. There are two kinds of "Styles" at play here: AnnotationTextStyle and DimensionStyle. They are different concepts that apply to different Element-classes. Those are details that need to be captured in the schema.

3. For the classes associated with an AnnotationTextStyle (i.e. TextAnnotation2d, TextAnnotation3d, Table and DimensionStyle), a mix-in was proposed for two reasons:
   a. Facilitate querying - primarily to identify which Elements are using a particular AnnotationTextStyle.
   b. Unify semantics of all those nav-properties in different Element-classes.

In previous BWG meetings, we've been moving away from using mix-ins for 3.b. We envision that the Base Infrastructure Ontologies (BION) will be the way to address that.

Regarding 3.a., those meetings have raised a convention that enables such kind of querying without mix-ins: just make sure to introduce those properties under the same name - then, one can use ECSQL's instance-query syntax. e.g.

Let's assume the following TextStyle nav-properties were introduced, all associated with an AnnotationTextStyle via their corresponding relationships:

• TextAnnotation2d.TextStyle
• TextAnnotation3d.TextStyle
• Table.TextStyle
• DimensionStyle.TextStyle

One could then use the following query to find associated bis:Element instances to a particular AnnotationTextStyle:

SELECT e.ECInstanceId 
FROM bis.AnnotationTextStyle style 
INNER JOIN bis.Element e ON style.ECInstanceId = HexToId(json_extract(e.$->TextStyle, '$.Id'))
WHERE style.ECInstanceId = ?

In this particular case, that syntax requires handling JSON (i.e. HexToId and json_extract() in the JOIN since these are nav-properties). @khanaffan tells me that syntax could be further simplified, dropping the need to handle JSON in this case. But it seems to me the use-case behind this kind of query in light of AnnotationTextStyle is not performance-critical anyway.

Lastly, each ITextAnnotation class will have its own implementation of the callback, so it can interpret its "TextStyle" nav-property accordingly - with the appropriate logic.

Thus, I'm leaning towards recommending introducing separate nav-properties under the same name in the schema, each with its backing relationship-class, which enables the enforcement of the appropriate Element-class-to-Style associations.

[ColinKerr]

Thank you, @ColinKerr, that was extremely helpful reading. One follow-up question, I noticed a possible slight discrepancy in the documentation. The modified property has None listed as “Not valid for ECRelationshipClass type”, but your comment explains what None does on a relationship class AND I can see instances of ECRelationshipClass with the None modifier, like

    <ECRelationshipClass typeName="ElementOwnsChildElements" strength="embedding" modifier="None" description="Relates a bis:Element to child bis:Elements which represent parts of the Entity modeled by the parent bis:Element.">
        <!-- @see Element.Parent ECNavigationProperty -->
        <!-- NOTE: Was not made abstract because of too many legacy situations. -->
        <Source multiplicity="(0..1)" roleLabel="owns child" polymorphic="true">
            <Class class="Element"/> <!-- Logically should be IParentElement, but that mixin was invented later. -->
        </Source>
        <Target multiplicity="(0..*)" roleLabel="is owned by parent" polymorphic="true">
            <Class class="Element"/>
        </Target>
    </ECRelationshipClass>

I created an issue to fix these docs: #564. Thanks for finding the issue.

[ColinKerr]

@Alfonso-Martello

I went ahead and added a draft pull request detailing how I think the schema could/should work. Happy for any feedback!

If this new mixin is only going to be used for text annotations then I don't see much difference in using it vs ITextAnnotation. I also think it's ok to put a nav prop on ITextAnnotation then create individual relationships for the other cases if they do not fit.

Maybe the intent of this PR was to use the new mixin for TextAnnotation2d, TextAnnotation3d, Table and DimensionStyle. In that case I think that is OK as well.

@diegoalexdiaz

In previous BWG meetings, we've been moving away from using mix-ins for 3.b. We envision that the Base Infrastructure Ontologies (BION) will be the way to address that.

Regarding 3.a., those meetings have raised a convention that enables such kind of querying without mix-ins: just make sure to introduce those properties under the same name - then, one can use ECSQL's instance-query syntax. e.g.

These are both good tools when the simplest strategy doesn't fit. In this case, if this new mixin can be used for the 4 references w/ no compromises vs 4 relationships then we should use a mixin. If there are some compromises using a mixin then I agree that we should use this as a case to further adding semantic meaning to properties and improving instance query.

@khanaffan I agree this is a clumsy bit in instance queries. Do we have an issue to track this and other instance query improvements that have been discussed?

[Alfonso-Martello]

The intent of the mix-in in the draft PR was to be used with the TextAnnotation2d, TextAnnotation3d, Table, and DimensionStyle. The DimensionStyle is the reason I did not put it into the ITextAnnotation, since the DimensionStyle does not need to implement the ITextAnnotation interface (it does not have text/fields).

I could see putting the navigation property on ITextAnnotation and then having a separate one for the DimensionStyle. Having one general AnnotationTextStyle relationship and then a separate DimensionStyle one feels a little weird, but I think that is more of an OO mindset speaking.

The reason I used a mix-in was mainly for reason 3.b and a little bit 3.a. In terms of querying, the main use case in my mind is determining if the AnnotationTextStyle is in use before allowing delete.

Both Deigo’s recommendation to use separate navigation properties with the same name and Colin’s recommendation to use a mix-in similar to the draft PR seem reasonable to me. From the Drawing Production perspective I think we would be happy with either.

[diegoalexdiaz]

Re: @ColinKerr : If there are some compromises using a mixin then I agree that we should use this as a case

The compromise that I'm observing with the mix-in is that it conflicts with two domain rules that @Alfonso-Martello has risen:

• A DimensionAnnotation shall only be associated with a DimensionStyle.
• A DimensionStyle (not an ITextAnnotation) shall reference an AnnotationTextStyle.

So it is not clear to me what's the benefit of introducing an association to an AnnotationTextStyle via a mix-in in the presence of such edge-cases.

[Alfonso-Martello]

I think I see Diego’s point, but I will put it into my own words to make sure I am understanding.

Using a mix-in as I did in my draft PR leads to reduced semantic granularity. Mainly, that a DimensionStyle is a very different element than an ITextAnnotation and while both can refer to an AnnotationTextStyle the meaning is not the same. So, it would be better to represent this via a separate relationship (basically “DimensionStyleUsesTextStyle” is more specific than “ElementUsesTextStyle”). I think this same granularity argument could even be made for Tables vs TextAnnotation2d/3d as well.

Regardless, if we treat a DimensionStyle referring to an AnnotationTextStyle as a semantic edge case, then it would be better to have the way text styles are referenced be uniform. In this case, all classes have their own granular navigation property and relationship. The fact that DimensionAnnotations must refer to their associated DimensionStyle in the same way further enforces this approach as the most uniform.

Is my understanding correct @diegoalexdiaz?

[diegoalexdiaz]

@Alfonso-Martello, what I'm understanding from your last paragraph is that:

• we'd go with a mix-in to achieve uniformity of how text styles are referenced from any bis:GeometricElement. e.g. ITextStyleReferencingElement.TextStyle + GeometricElementUsesTextStyle, to be implemented by TextAnnotation2d, TextAnnotation3d and Table (for now?).
• We'd leave the DimensionStyle case as an edge-case, and thus, it would not implement the aforementioned mix-in but it would still follow a similar pattern: e.g. DimensionStyle.TextStyle nav-property + DimensionStyleUsesTextStyle relationship.

I'm ok with that in general, with the its main purpose being to advertise the overall pattern. I just can't think of a consumer of such mix-in at the moment. The use-case that drove my previous reply (e.g. checking if a TextStyle is in use before it gets deleted), rather than a mix-in, it still requires the instance-query that I mentioned earlier.

[Alfonso-Martello]

@diegoalexdiaz, my previous message was more about me trying to understand why the DimensionStyle should be an edge case, and why that leads to each element that references a Style needing its own nav-property + relationship.

What I mean by “uniformity” is actually uniformity of implementation (aka every Element that refers to a Style does so via a nav-property + uniquely named relationship). Instead of having some ECClasses that follow that pattern and others that follow the mix-in pattern.

However, I agree with the pattern you put forth:

• we'd go with a mix-in to achieve uniformity of how text styles are referenced from any bis:GeometricElement. e.g. ITextStyleReferencingElement.TextStyle + GeometricElementUsesTextStyle, to be implemented by TextAnnotation2d, TextAnnotation3d and Table (for now?).
• We'd leave the DimensionStyle case as an edge-case, and thus, it would not implement the aforementioned mix-in but it would still follow a similar pattern: e.g. DimensionStyle.TextStyle nav-property + DimensionStyleUsesTextStyle relationship.

For the curious - my reasoning for that pattern

In this discussion, we have thrown out a few different implementations. I think they can be boiled down to a few key questions whose answers point at the pattern we should use.

1. Can we use a single mix-in for all styles?
   If "yes", create a single mix-in and we are done.
   If "no", we must consider question 2.
2. Can we use a single mix-in for all elements that use an AnnotationTextStyle?
   If "yes", use a mix-in as I did in the draft PR and we are done.
   If "no", then DimensionStyle will have the following pattern: DimensionStyle.TextStyle nav-property + DimensionStyleUsesTextStyle relationship. We must use the instance-query to check for AnnotationTextStyle usage. We must also consider question 3.
3. Is there semantic meaning with differentiating between a TextAnnotation2d, a TextAnnotation3d, or a Table referring to an AnnotationTextStyle?
   If "yes", then use separate “nav-properties under the same name in the schema, each with its backing relationship-class” and we are done.
   If "no", use the pattern ITextStyleReferencingElement.TextStyle + GeometricElementUsesTextStyle, to be implemented by TextAnnotation2d, TextAnnotation3d and Table. We must also consider question 4.
4. Can we simply add the navigation property to the existing ITextAnnotation mix-in since all of the GeometricElement classes we care about already implement this mix-in?
   If "yes", the pattern becomes ITextAnnotation.TextStyle + GeometricElementUsesTextStyle and we are done.
   If "no", then we are done.

Based on the discussion that has already happened, I believe these are the answers to the questions:

1. Can we use a single mix-in for all styles?
   No. We need to be able to differentiate between elements that only refer to DimensionStyles (DimensionAnnotations) and elements that only refer to AnnotationTextStyles (DimensionStyles, TextAnnotation2d/3d, and Tables).
2. Can we use a single mix-in for all elements that use an AnnotationTextStyle?
   No. There is a semantic difference between a DimensionStyle referring to an AnnotationTextStyle and a GeometricElement referring to an AnnotationTextStyle. Namely, one is a definition and the other is an actual piece of text.
3. Is there semantic meaning with differentiating between a TextAnnotation2d, a TextAnnotation3d, or a Table referring to an AnnotationTextStyle?
   Unsure, but leaning towards no, since these are all GeometricElements that refer to an AnnotationTextStyle for the same purpose.
4. Can we simply add the navigation property to the existing ITextAnnotation mix-in since all of the GeometricElement classes we care about already implement this mix-in?
   No. There is a semantic difference between a Text Element being driven by another (aka having fields) and an element referring to an AnnotationTextStyle. We should keep these as separate concepts to allow behavior to be mix-and-matched in the future.

Thus, we arrive at the same pattern.

[pmconne]

There is a semantic difference between a Text Element being driven by another (aka having fields) and an element referring to an AnnotationTextStyle. We should keep these as separate concepts to allow behavior to be mix-and-matched in the future.

BisCore.ITextAnnotation does not solely describe a geometric element that can host fields. It describes a geometric element that hosts text. That is why the corresponding TypeScript interface provides methods for interacting with TextBlocks. Text blocks reference text styles. So to me, ITextAnnotation is the right source type for a "geometric element uses text style" relationship. Dimension styles are of course a different concept entirely.

I don't think an ITextStyleReferencingElement type is a useful BIS concept; to me it seems like a contrivance.

[diegoalexdiaz]

@pmconne - BisCore.ITextAnnotation does not solely describe a geometric element that can host fields. It describes a geometric element that hosts text.

That is not accurate today. The description that we provided for ITextAnnotation in the latest release of BisCore reads:

"...indicate that its GeometryStream may contain text-content computed from property-values in other Elements (aka Text-Fields)."

We can certainly extend the scope of ITextAnnotation, but the description that you offered is too wide as it would target any bis:GeometricElement (i.e. "geometric element that hosts text").

If it is ok to expect that all implementations of ITextAnnotation will cover cases that need to reference a TextStyle and optionally contain portions of text that are computed from property-values, then I'm fine adding the proposed nav-property to it rather than on a separate mix-in. In that case, the description of ITextAnnotation could read like:

"An interface that can be mixed-into a bis:GeometricElement-subclass to indicate that its GeometryStream contains text-content that is styled according to a referenced AnnotationTextStyle, and optionally, contains portions of text-content computed from property-values in other Elements (aka Text-Fields)"