Add ElectricDistribution domain schema (01.00.00) by juliusguay · Pull Request #733 · iTwin/bis-schemas

juliusguay · 2026-06-19T16:50:54Z

Summary

This PR proposes a new BIS 2-DisciplinePhysical domain schema for overhead electric distribution infrastructure.

Schema name: ElectricDistribution · alias edist · version 01.00.00
Schema path: Domains/2-DisciplinePhysical/ElectricDistribution/ElectricDistribution.ecschema.xml
Validation: Passes SchemaValidationRunner with zero violations

Schema Contents

Category	Count	Classes
PhysicalElement	10	DistributionPole, Crossarm, Insulator, OverheadConductor, DistributionTransformer, PoleEquipment, SpanGuy, GuyWire, AnchorAssembly, PoleAttachment (abstract)
ElementAspect	8	GroundingConfiguration, EnvironmentalDesignContext, VegetationContext, AvianProtectionContext, ClearanceSummary (Unique); PoleLoadingResult, InspectionFinding, ConductorSagCondition (Multi)
AnalyticalElement	2	PoleLoadingAnalysis, ClearanceCheck
InformationRecordElement	2	PoleInspection, ClearanceViolation
DefinitionElement	3	AvianZone, LoadCaseDefinition, ClearanceRequirement
PhysicalType	1	DistributionPoleType
ECEnumeration	25	PoleMaterial, NescDistrict, GO95Zone, ConductorUsageGroup, and 21 others
ECRelationshipClass	14	Type-instance, assembly, analytical, aspect ownership, and reference relationships
Custom KOQ	2	EDIST_RESISTANCE (`u:OHM`), EDIST_RESISTIVITY (`u:OHM_M`)

Design Rationale

DistributionPole implements dsys:IDistributionElement (not IDistributionFlowElement) — a pole is structural support, not a flow conduit
Five aspects are ElementUniqueAspect (one per pole: grounding, environmental, vegetation, avian protection, clearance summary); three are ElementMultiAspect (many per host: loading results, inspection findings, sag conditions)
AvianZone modeled as bis:DefinitionElement with a PoleIsInAvianZone many-to-many relationship, supporting upsert-by-ZoneId from connector imports
anlyt:AnalyticalSimulatesSpatialElement used as the base for analytical relationships (confirmed against Analytical schema)
ClearanceViolation and PoleInspection use bis:InformationRecordElement (bis:InformationContentElement carries NotSubclassableInReferencingSchemas)

Ground Truth

Property names are aligned 1-to-1 with the Universal Pole Model (UPM), a proprietary Pydantic domain model validated against the data models of SPIDAcalc, PLS-POLE / PLS-CADD, and O-Calc Pro — the three dominant overhead distribution analysis tools. The UPM is covered by 825+ domain-validated tests spanning real-world pole configurations across NESC and GO-95 jurisdictions.

Schema References

Schema	Version
BisCore	01.00.15
Analytical	01.00.02
DistributionSystems	01.00.03
AecUnits	01.00.03
Units	01.00.06
Formats	01.00.00
CoreCustomAttributes	01.00.03
BisCustomAttributes	01.00.00

BisCore 01.00.15 is required by Analytical 01.00.02. Units 01.00.06 is the minimum released version containing u:OHM_M (ELECTRICAL_RESISTIVITY).

Proposed by Julius Guay IV (Bentley Systems, Application Engineer, Solutions Engineering) · linkedin.com/in/juliusguay

CLAassistant · 2026-06-19T16:51:01Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

juliusguay · 2026-06-19T17:06:32Z

Noting for the maintainers: I'm currently confirming internal authorization per Section 4 of the CLA (employer IP rights) given my role as a Bentley Application Engineer with Solutions Engineering. Will execute the CLA once confirmed. Happy to discuss the schema design in the meantime.

alfredocontreras88 · 2026-06-22T12:41:46Z

if creating or adding a new power system schema, please coordinate with other interested parties like substation plus team. we already have a base schema that should be extended for other power sub domains. you can contact me directly and should be coordinated with Diego Diaz.

New BIS 2-DisciplinePhysical domain schema for overhead electric distribution infrastructure (poles, attachments, conductors, transformers, structural loading analysis, field inspection, and clearance checking). Schema contents: - 10 PhysicalElement classes (DistributionPole, Crossarm, Insulator, OverheadConductor, DistributionTransformer, and others) - 8 ElementAspect classes (5 UniqueAspect, 3 MultiAspect) - 2 AnalyticalElement classes (PoleLoadingAnalysis, ClearanceCheck) - 2 InformationRecordElement classes (PoleInspection, ClearanceViolation) - 3 DefinitionElement classes (AvianZone, LoadCaseDefinition, ClearanceRequirement) - 1 PhysicalType (DistributionPoleType) - 25 ECEnumerations aligned with NESC and GO-95 jurisdiction values - 14 ECRelationshipClasses - 2 custom KindOfQuantity (EDIST_RESISTANCE u:OHM, EDIST_RESISTIVITY u:OHM_M) Passes SchemaValidationRunner with zero violations. Property names are aligned 1-to-1 with the Universal Pole Model (UPM), a proprietary Pydantic domain model validated against SPIDAcalc, PLS-POLE, and O-Calc Pro data models and covered by 825+ domain tests across NESC and GO-95 jurisdictions. Proposed by Julius Guay IV (Bentley Systems Solutions Engineer)

naveedkhan8067 · 2026-06-22T13:53:17Z

Seems like you are using the fork? If yes, it will block several checks.

Are you not able to create a branch from master?

Per @AlfredoConGo review: extend the shared psrp base instead of a parallel power-system schema. Class names/properties unchanged. - DistributionPole -> psrp:Structure (keeps dsys:IDistributionElement) - PoleAttachment (abstract) -> psrp:AuxiliaryEquipment (Crossarm/Insulator/SpanGuy/ GuyWire/PoleEquipment/DistributionTransformer inherit) - AnchorAssembly -> psrp:Foundation - OverheadConductor -> psrp:Equipment (dsys:IDistributionFlowElement now inherited) - DistributionTransformer: dsys:IDistributionFlowElement now inherited - Refs aligned to psrp 01.00.02: BisCore 01.00.25, DistributionSystems 01.00.02, CoreCustomAttributes 01.00.04, + PowerSystemResourcesPhysical 01.00.02 Passes SchemaValidationRunner with zero violations.

juliusguay · 2026-06-23T23:17:46Z

@alfredocontreras88 — correction / update (I've edited this comment): on a closer read, psrp already provides the full overhead-distribution class hierarchy, so I've re-based ElectricDistribution onto the specific psrp classes rather than the generic abstract bases I first used. Re-pushed.

Mapping — each edist class → its psrp base:

`edist`	`psrp` base
`DistributionPole`	`Pole` (`Pole → OverheadStructure → Structure`); keeps `dsys:IDistributionElement`
`OverheadConductor`	`Conductor` (`→ Equipment`)
`DistributionTransformer`	`Transformer`
`Insulator`	`Insulator`
`GuyWire`	`GuyWire`
`SpanGuy`	`SpanGuy`
`Crossarm`	`CableSupports`
`AnchorAssembly`	`AnchorCage` (`→ UndergroundStructure → Structure`)
`PoleEquipment`	`AuxiliaryEquipment`
`DistributionPoleType`	`PolePhysicalType`

Because the attachments now span both the Structure and Equipment branches, PoleAttachment is now a mixin (IsMixin, applies to bis:PhysicalElement) — it carries the shared attachment properties and is the target of DistributionPoleAssemblesAttachments, while each attachment class derives from its specific psrp base. Passes SchemaValidationRunner with zero violations.

A few points I'd like to confirm on our call:

Transformer — psrp:Transformer vs psrp:PowerTransformer for a pole-mounted distribution transformer?
Crossarm — psrp:CableSupports is the closest fit; is that the intended class?
Connectivity — should distribution adopt the psrp ElectricalPort / StructuralPort + PortConnection model (and ownership relationships like StructureOwnsInsulators) for spans/attachments, instead of our custom relationships?
Operational + analysis fields — our connector carries loading/clearance verdict fields plus Analytical classes (PoleLoadingAnalysis, ClearanceCheck). Should those live in this domain schema or a separate application schema that extends it?

Thanks again — looking forward to the discussion.

Domain README (class hierarchy extending psrp, references, validation) and the full design document (property tables, source-tool field mapping, enumeration rationale, open design decisions). Scrubbed of dev-repo artifacts (local paths, private-repo references, planning notes) for the public domain folder.

Correcting the earlier generic re-parent: psrp already provides the overhead- distribution hierarchy, so derive from the specific classes rather than the abstract bases (Structure/Equipment/Foundation/AuxiliaryEquipment). - DistributionPole -> psrp:Pole (Pole -> OverheadStructure -> Structure) - OverheadConductor -> psrp:Conductor (Conductor -> Equipment) - DistributionTransformer -> psrp:Transformer - Insulator -> psrp:Insulator - GuyWire -> psrp:GuyWire - SpanGuy -> psrp:SpanGuy - Crossarm -> psrp:CableSupports - AnchorAssembly -> psrp:AnchorCage (-> UndergroundStructure -> Structure) - PoleEquipment -> psrp:AuxiliaryEquipment - DistributionPoleType -> psrp:PolePhysicalType PoleAttachment is now a MIXIN (IsMixin, applies to bis:PhysicalElement): the attachment classes span both the Structure and Equipment branches, so they each derive from their specific psrp base AND apply this mixin, which carries the shared attachment properties and is the target of DistributionPoleAssemblesAttachments. README + design.md updated. Passes SchemaValidationRunner with zero violations.

diegoalexdiaz · 2026-06-29T17:50:42Z

Thanks a lot for your contribution @JJGIV2010. I'll provide specific feedback in-line.

@alfredocontreras88 mentioned that this proposed schema is not currently driven by any development effort. That would be a blocker to merge it as a "Standard BIS" schema since, without it, we wouldn't be able to validate its content and design. As a potential shorter-term solution, its concepts could be introduced as an Application schema while they are validated and proved out, and later introduce them as one or more Standardized schemas.

In the meantime, I suggest converting this PR to draft.

diegoalexdiaz · 2026-06-29T17:53:02Z

@@ -0,0 +1,1148 @@
+# ElectricDistribution BIS Domain Schema — Design Context


Great documentation content! FYI, schema documentation in this repo follows the following conventions.

diegoalexdiaz · 2026-06-29T17:55:35Z

+    <!-- Domain-specific KindOfQuantity not covered by AECUnits.
+         u:OHM = SI ohm (derived unit); u:OHM_M = ohm-metre for soil resistivity.
+         Verify unit alias strings against the BIS Units schema before PR. -->
+    <KindOfQuantity typeName="EDIST_RESISTANCE"   displayLabel="Resistance"       persistenceUnit="u:OHM"   relativeError="0.001" presentationUnits="f:DefaultRealU(4)[u:OHM]"/>


We've identified defining KoQs for a discipline in a separate schema is a best practice that simplifies future schema evolution.

diegoalexdiaz · 2026-06-29T17:56:51Z

+         ENUMERATIONS
+         ============================================================ -->
+
+    <ECEnumeration typeName="PoleMaterial" backingTypeName="int" isStrict="true"


BisCore already standardized the pattern to capture PhysicalMaterial information (i.e. via the PhysicalMaterial nav-property on PhysicalElement and/or PhysicalType).

diegoalexdiaz · 2026-06-29T18:04:23Z

+
+    <!-- isStrict=true: matches UPM Literal["pass","marginal","fail"] on
+         InspectionSection.pole_test_result and .verdict. -->
+    <ECEnumeration typeName="InspectionVerdict" backingTypeName="int" isStrict="true">


BIS uses modeling perspectives as a foundational mechanism to capture different kinds of data about the same infrastructure asset. We've identified as a best practice to introduce concepts in each perspective as a separate schema.

The current ElectricDistribution schema seems to target the following modeling perspectives:

Physical (Classification and description of entities aimed at use-cases such as Quantity Takeoffs or Clearance / Clash detection).

Analytical (concepts required for Structural Analysis - e.g. Load-Cases)

Operational (Inspections)

It is recommended to break it up into different schemas per modeling-perspective.

diegoalexdiaz · 2026-06-29T18:08:12Z

+         SPIDA, OCalc, PLS-POLE adapters. Connector maps adapter strings to this enum. -->
+    <ECEnumeration typeName="EquipmentType" backingTypeName="int" isStrict="false"
+        description="Classification of pole-mounted equipment other than distribution transformers.">
+        <ECEnumerator name="Transformer"       value="0"  displayLabel="Transformer"/>


As @alfredocontreras88 pointed out, the Substation+ effort is leading to the evolution of Standard BIS schemas that overlap some of these concepts. e.g. PowerSystemResourcesPhysical already has physical classes for Transformer, Switch or Recloser.

diegoalexdiaz · 2026-06-29T18:10:17Z

+        <ECProperty propertyName="Authority" typeName="string" displayLabel="Authority"  description="Designating body (e.g. PGE, CPUC)"/>
+    </ECEntityClass>
+
+    <ECEntityClass typeName="LoadCaseDefinition" displayLabel="Load Case Definition"


The concepts of Load-Cases and Load-Combinations are very commonly needed by Structural Analysis solvers.
FYI, @laurynas111 has recently looked into proposing a schema for such concepts, driven by existing development efforts involving iTwin-based Structural Analysis products.

diegoalexdiaz · 2026-06-29T18:15:11Z

+    <ECEntityClass typeName="DistributionPole" displayLabel="Distribution Pole"
+        description="A placed overhead distribution pole instance. Implements IDistributionElement (structural participant in the distribution system, not a flow element).">
+        <BaseClass>psrp:Pole</BaseClass>
+        <BaseClass>dsys:IDistributionElement</BaseClass>


IDistributionElement is not meant to be directly mixed-in. The DistributionSystems schema offers three options: an entity allows distribution of flow, control of flow or measurement of flow.

There is a related pattern that is meant to advertise structural connectivity via the StructuralConnections schema. Maybe that's more appropriate for the intent here?

juliusguay requested a review from a team as a code owner June 19, 2026 16:50

naveedkhan8067 reviewed Jun 22, 2026

View reviewed changes

Comment thread SchemaInventory.json

juliusguay force-pushed the add-electric-distribution-schema branch from 705a80d to 31d8238 Compare June 22, 2026 12:33

juliusguay force-pushed the add-electric-distribution-schema branch from 31d8238 to 4e0556f Compare June 22, 2026 13:49

juliusguay added 2 commits June 23, 2026 18:32

diegoalexdiaz reviewed Jun 29, 2026

View reviewed changes

juliusguay marked this pull request as draft June 29, 2026 22:28

		@@ -0,0 +1,1148 @@
		# ElectricDistribution BIS Domain Schema — Design Context

Uh oh!

Conversation

juliusguay commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Schema Contents

Design Rationale

Ground Truth

Schema References

Uh oh!

CLAassistant commented Jun 19, 2026

Uh oh!

juliusguay commented Jun 19, 2026

Uh oh!

Uh oh!

alfredocontreras88 commented Jun 22, 2026

Uh oh!

naveedkhan8067 commented Jun 22, 2026

Uh oh!

juliusguay commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

diegoalexdiaz commented Jun 29, 2026

Uh oh!

diegoalexdiaz Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

diegoalexdiaz Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

diegoalexdiaz Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

diegoalexdiaz Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

diegoalexdiaz Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

diegoalexdiaz Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

diegoalexdiaz Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

juliusguay commented Jun 19, 2026 •

edited

Loading

juliusguay commented Jun 23, 2026 •

edited

Loading