Refactor connectivity relationship among ports. (#400)

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

@@ -7,6 +7,7 @@
     <ECSchemaReference name="BisCore" version="01.00.14" alias="bis" />
     <ECSchemaReference name="CoreCustomAttributes" version="01.00.03" alias="CoreCA"/>
     <ECSchemaReference name="BisCustomAttributes" version="01.00.00" alias="bisCA"/>
+    <ECSchemaReference name="ECDbMap" version="02.00.02" alias="ecdbmap"/>
 
     <ECCustomAttributes>
         <ProductionStatus xmlns="CoreCustomAttributes.01.00.03">
@@ -119,34 +120,33 @@
         <BaseClass>bis:InformationRecordElement</BaseClass>
     </ECEntityClass>
 
-    <ECRelationshipClass typeName="PortConnectionConnectsPorts" strength="referencing" modifier="Abstract" description="Indicates that the DistributionPort is connected to some other Distribution ports via PortConnection.">
+    <ECRelationshipClass typeName="PortConnectsToPorts" strength="referencing" modifier="Abstract" description="Indicates that the DistributionPort is connected to other DistributionPorts.">
         <BaseClass>bis:ElementRefersToElements</BaseClass>
-        <Source multiplicity="(0..1)" roleLabel="connects" polymorphic="true">
-            <Class class="PortConnection"/>
+        <Source multiplicity="(0..*)" roleLabel="connects to" polymorphic="true">
+            <Class class="DistributionPort"/>
         </Source>
-        <Target multiplicity="(2..*)" roleLabel="is connected by" polymorphic="true">
+        <Target multiplicity="(0..*)" roleLabel="is connected by" polymorphic="true">
             <Class class="DistributionPort"/>
         </Target>
+        <ECNavigationProperty propertyName="PortConnection" relationshipName="PortConnectionObjectifiesConnection" direction="backward" description="The PortConnection instance objectifying this connection."/>
     </ECRelationshipClass>
 
-    <ECRelationshipClass typeName="PortConnectionConnectsTwoPorts" strength="referencing" modifier="Abstract" description="Indicates that the DistributionPort is connected to one other Distribution port via PortConnection.">
-        <BaseClass>PortConnectionConnectsPorts</BaseClass>
-        <Source multiplicity="(0..1)" roleLabel="connects" polymorphic="true">
+    <ECRelationshipClass typeName="PortConnectionObjectifiesConnection" strength="referencing" modifier="None" description="Indicates that the connection between DistributionPorts is objectified by a PortConnection element.">
+        <Source multiplicity="(0..1)" roleLabel="objectifies" polymorphic="true">
             <Class class="PortConnection"/>
         </Source>
-        <Target multiplicity="(2..2)" roleLabel="is connected by" polymorphic="true">
-            <Class class="DistributionPort"/>
+        <Target multiplicity="(0..*)" roleLabel="is objectified by" polymorphic="true">
+            <Class class="PortConnectsToPorts"/>
         </Target>
     </ECRelationshipClass>
-    
-    <ECRelationshipClass typeName="PortConnectionIsRealizedByPhysicalElements" strength="referencing" modifier="None" description="Indicates that the Port Connection is realized by some Physical Element(s).">
+
+    <ECRelationshipClass typeName="PhysicalElementRealizesConnection" strength="referencing" modifier="None" description="Indicates the Physical Element(s) that realize a Connection between DistributionPorts.">
         <BaseClass>bis:ElementRefersToElements</BaseClass>
-        <Source multiplicity="(0..1)" roleLabel="is realized by" polymorphic="true">
-            <Class class="PortConnection"/>
-        </Source>
-        <Target multiplicity="(0..*)" roleLabel="realizes" polymorphic="true">
+        <Source multiplicity="(0..*)" roleLabel="realizes" polymorphic="true">
             <Class class="bis:PhysicalElement"/>
+        </Source>
+        <Target multiplicity="(0..1)" roleLabel="is realized by" polymorphic="true">
+            <Class class="PortConnection"/>
         </Target>
     </ECRelationshipClass>
-
 </ECSchema>

Domains/1-Common/DistributionSystems/DistributionSystems.remarks.md

@@ -11,9 +11,11 @@ A BIS [DistributionSystem](#distributionsystem) consists of [IDistributionElemen
 
 A given bis:PhysicalElement can implement more that one of [IDistributionFlowElement](#idistributionflowelement), [IDistributionControlElement](#idistributioncontrolelement), and [IDistributionFlowElement](#idistributionflowelement).
 
-Connection point information will be added in subsequent versions of the schema.
+The following class-diagrams depict the main classes and relationships in the DistributionSystems schema:
 
-![Class and Instance Diagrams](./media/DistributionSystems.png)
+![DistributionSystems](./media/DistributionSystems.png)
+
+![DistributionPorts](./media/DistributionPorts.png)
 
 ## Entity Classes
 
@@ -79,8 +81,24 @@ Equivalent to [IfcDistributionPort](https://standards.buildingsmart.org/IFC/RELE
 
 ### PortConnection
 
-A `PortConnection` defines a physical connection between 2 DistributionPorts. In the case where a connection is realized by some other physical element, the realizing element could be found using `PortConnectionIsRealizedByPhysicalElements` relationship.
+A `PortConnection` instance objectifies a physical connection between 2 or more DistributionPorts when needed. That is typically the case when the level of granularity being modeled includes any physical element(s) that realize a connection. In that case, the realizing element(s) could be found using the `PortConnectionIsRealizedByPhysicalElements` relationship.
+
+## Relationships
+
+### PortConnectsToPort
+
+The connection between two or more DistributionPorts can be objectified by associating a `PortConnection` instance via the `PortConnectionObjectifiesConnection` relationship. Objectifying a connection is needed when there is data (identity or business-related) to be captured about a connection, or when the level of granularity being modeled includes any physical element(s) that realize it.
+
+BIS domains extending the rules and patterns in the DistributionSystems schema are expected to subclass the `PortConnectsToPort` relationship in order to provide specific semantics and multiplicity applicable to how DistributionPort instances connect in such domain.
+
+Equivalent to [IfcRelConnectsPorts](https://standards.buildingsmart.org/IFC/RELEASE/IFC4_3/HTML/lexical/IfcRelConnectsPorts.htm).
+
+### PhysicalElementRealizesConnection
+
+When the Connection between DistributionPorts needs to be objectified, a `PortConnection` instance could be introduced, referenced by the `PortConnectsToPort` relationship via its _PortConnection_ navigation property. The `PhysicalElementRealizesConnection` relationship can then be used to associate Physical Elements with such `PortConnection` instance.
+
+Note that Physical Elements realizing a Connection are not directly enabling the flow of matter in a DistributionSystem. Thus, they are typically not `IDistributionElement`s themselves. 
 
-A `PortConnection` generally connects two distribution ports via the `PortConnectionConnectsTwoPorts`. However, its base `PortConnectionConnectsPorts` relationship class can be used when modeling port-connections at a higher level of detail.
+Examples include bolts, rings or cement used on Connections between Pipes.
 
-Equivalent to [IfcRelConnectsPorts](https://standards.buildingsmart.org/IFC/RELEASE/IFC4_3/HTML/lexical/IfcRelConnectsPorts.htm).
+Equivalent to the _RealizingElement_ property of [IfcRelConnectsPorts](https://standards.buildingsmart.org/IFC/RELEASE/IFC4_3/HTML/lexical/IfcRelConnectsPorts.htm).

Domains/2-DisciplinePhysical/Piping/PipeworkPhysical.ecschema.xml

@@ -155,12 +155,12 @@
         </Target>
     </ECRelationshipClass>
 
-    <ECRelationshipClass typeName="PortConnectionConnectsTwoPipingPorts" strength="referencing" modifier="None" description="Indicates that the PipingPortElement is connected to one other PipingPortElement via a PortConnection.">
-        <BaseClass>dsys:PortConnectionConnectsTwoPorts</BaseClass>
+    <ECRelationshipClass typeName="PortConnectsToPort" strength="referencing" modifier="None" description="Indicates that the PipingPortElement is connected to one other PipingPortElement.">
+        <BaseClass>dsys:PortConnectsToPorts</BaseClass>
         <Source multiplicity="(0..1)" roleLabel="connects" polymorphic="true">
-            <Class class="dsys:PortConnection"/>
+            <Class class="PipingPortElement"/>
         </Source>
-        <Target multiplicity="(2..2)" roleLabel="is connected by" polymorphic="true">
+        <Target multiplicity="(1..1)" roleLabel="is connected by" polymorphic="true">
             <Class class="PipingPortElement"/>
         </Target>
     </ECRelationshipClass>