Add semantical custom attributes for aggregate relationships.

Domains/0-Core/BisCore.ecschema.xml

@@ -6,7 +6,7 @@
 <ECSchema schemaName="BisCore" alias="bis" version="01.00.17" xmlns="http://www.bentley.com/schemas/Bentley.ECXML.3.2" displayLabel="BIS Core" description="The BIS core schema contains classes that all other domain schemas extend.">
 
     <ECSchemaReference name="CoreCustomAttributes" version="01.00.03" alias="CoreCA"/>
-    <ECSchemaReference name="BisCustomAttributes" version="01.00.00" alias="bisCA"/>
+    <ECSchemaReference name="BisCustomAttributes" version="01.00.01" alias="bisCA"/>
     <ECSchemaReference name="ECDbMap" version="02.00.00" alias="ecdbmap"/>
     <ECSchemaReference name="ECDbSchemaPolicies" version="01.00.00" alias="ecdbpol"/>
 
@@ -344,6 +344,9 @@
     </ECEntityClass>
     <ECRelationshipClass typeName="ModelModelsElement" displayLabel="Model Sub-Models Element" strength="embedding" strengthDirection="backward" modifier="None" description="Relates a bis:Model to the bis:Element that it sub-models. The sub-Model models the same Entity as the sub-modeled Element, but at a finer granularity.">
         <!-- @see Model.ModeledElement ECNavigationProperty -->
+        <ECCustomAttributes>
+            <AggregateRelationship xmlns="BisCustomAttributes.01.00.01"/>
+        </ECCustomAttributes>        
         <Source multiplicity="(0..1)" roleLabel="models" polymorphic="true">
             <Class class="Model"/>
         </Source>
@@ -1440,6 +1443,9 @@
     <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. -->
+        <ECCustomAttributes>
+            <AggregateRelationship xmlns="BisCustomAttributes.01.00.01"/>
+        </ECCustomAttributes>
         <Source multiplicity="(0..1)" roleLabel="owns child" polymorphic="true">
             <Class class="Element"/> <!-- Logically should be IParentElement, but that mixin was invented later. -->
         </Source>
@@ -1812,6 +1818,9 @@
 
     <ECRelationshipClass typeName="PhysicalSystemAggregatesSubSystems" modifier="None" strength="referencing" displayLabel="Physical System Aggregates Sub-Systems" description="Forms the Physical System hierarchy.">
         <!-- @see PhysicalSystem.AggregatingSystem -->
+        <ECCustomAttributes>
+            <AggregateRelationship xmlns="BisCustomAttributes.01.00.01"/>
+        </ECCustomAttributes>
         <Source multiplicity="(0..1)" roleLabel="aggregates" polymorphic="true">
             <Class class="PhysicalSystem"/>
         </Source>

Domains/1-Common/SpatialComposition/SpatialComposition.ecschema.xml

@@ -66,6 +66,9 @@
     <ECRelationshipClass typeName="SpatialStructureElementAggregatesElements" modifier="None" strength="embedding" displayLabel="Spatial Structure Element Aggregates Spatial Structure Elements" description="Forms the Spatial Structure. The volumes of the aggregated Elements should not overlap and should generally add up to the volume of the aggregator (the aggregating Element) and lie spatially within the aggregator.">
         <!-- @see CompositeElement.ComposingElement -->
         <BaseClass>CompositeComposesSubComposites</BaseClass>
+        <ECCustomAttributes>
+            <AggregateRelationship xmlns="BisCustomAttributes.01.00.01"/>
+        </ECCustomAttributes>
         <Source multiplicity="(0..1)" roleLabel="aggregates" polymorphic="true">
             <Class class="SpatialStructureElement"/>
         </Source>

Standard/BisCustomAttributes.ecschema.xml

@@ -3,7 +3,7 @@
 |  * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
 |  * See LICENSE.md in the project root for license terms and full copyright notice.
 ======================================================================================= -->
-<ECSchema schemaName="BisCustomAttributes" alias="bisCA" version="01.00.00" description="Custom attributes to indicate BIS concepts." displayLabel="BIS Custom Attributes" xmlns="http://www.bentley.com/schemas/Bentley.ECXML.3.2">
+<ECSchema schemaName="BisCustomAttributes" alias="bisCA" version="01.00.01" description="Custom attributes to indicate BIS concepts." displayLabel="BIS Custom Attributes" xmlns="http://www.bentley.com/schemas/Bentley.ECXML.3.2">
     <ECEnumeration typeName="SchemaLayer" backingTypeName="string" isStrict="true" description="Defines the layers in the BIS schema hierarchy.">
         <ECEnumerator name="Core"               displayLabel="Core"                value="Core"               description="Layer for schemas that define the most fundamental concepts and key organizational strategies for all other BIS schemas."/>
         <ECEnumerator name="Common"             displayLabel="Common"              value="Common"             description="Layer for schemas that define abstract concepts and patterns used by multiple disciplines."/>
@@ -15,4 +15,6 @@
     <ECCustomAttributeClass typeName="SchemaLayerInfo" appliesTo="Schema" modifier="Sealed" description="Declares the target layer in the BIS schema hierarchy for a schema.">
         <ECProperty propertyName="Value" typeName="SchemaLayer" description="Layer in the BIS schema hierarchy that a schema targets." />
     </ECCustomAttributeClass>
+
+    <ECCustomAttributeClass typeName="AggregateRelationship" appliesTo="RelationshipClass" description="Identifies a relationship class that carries Aggregate semantics." displayLabel="Aggregate Relationship" modifier="Sealed"/>
 </ECSchema>

Standard/BisCustomAttributes.remarks.md

@@ -37,4 +37,10 @@ Other technology-specific schemas not meant to be referenced by other schemas be
 
 ### SchemaLayerInfo
 
-BIS schemas should be tagged with the `SchemaLayerInfo` `CustomAttribute` to enable validation and error checking related to schema-references.
+BIS schemas should be tagged with the `SchemaLayerInfo` `CustomAttribute` to enable validation and error checking related to schema-references.
+
+### AggregateRelationship
+
+Under this _aggregate_ semantics, read in the _forward_ direction, the element at the source end of the relationship (the whole) can be described as being composed of the elements at the target end (its parts). As a result, relationship classes tagged with the `AggregateRelationship` `CustomAttribute` lead to a strict hierarchy in which the parts decompose one and only one whole-element.
+
+Note that the `AggregateRelationship` `CustomAttribute` does not imply by itself that the element at the source end of the relationship (the whole) controls the lifetime of its parts. A relationship class tagged with it shall use its **strength** attribute in order to advertise the expected behavior regarding lifetime control. The two typical values in that case are _embedding_ (whole controls lifetime of parts) and _referencing_ (no lifetime control is expected).