Skip to content

Schema & Mappings

The bidirectional converter is schema-driven: the OpenDSS file format is defined in LinkML YAML under src/cimhub_opendss/schema/linkml/, and that schema is the single source of truth for both the data structure and how each OpenDSS attribute maps to CIM. The full, attribute-level reference is generated from this schema and lives under Schema Reference.

Importer / Exporter structure

Each OpenDSS element type is handled by a dedicated converter module, paired across the two directions:

importer/<group>/<element>.py     DSS → CIM   (dss_to_cim orchestrates)
exporter/<group>/<element>.py     CIM → DSS   (cim_to_dss orchestrates)
  • Import parses OpenDSS with OpenDSSDirect.py and builds a cimgraph FeederModel of cimhub_2026 objects. See Import.
  • Export walks the FeederModel and writes one .dss file per element type via a registry of converters. See Export.

Reading the mappings

Every slot in the schema can carry mapping annotations that document how an OpenDSS attribute corresponds to a CIM class/field. Two kinds matter most:

exact_mappings

A one-to-one correspondence: the OpenDSS attribute and the CIM attribute represent the same physical quantity (subject only to unit conversion). These are the mappings the importer and exporter rely on directly — a value round-trips through them without loss.

r0:
  description: Zero-sequence resistance.
  exact_mappings:
    - cim:PerLengthSequenceImpedance.r0
  comments:
    - >-
      Import: PerLengthSequenceImpedance.r0 = r0 converted to ohm/m,
      or 0.0 if r0 is not specified. Export: r0 = r0.

close_mappings

A near-equivalent correspondence that requires interpretation or a lossy transform — for example, an OpenDSS field that aggregates or approximates a CIM concept, or where the two models disagree on convention. A close_mapping signals "these are related but not interchangeable," so a converter must apply logic rather than copy the value.

comments and todos

  • comments describe the concrete Import: / Export: behavior for that slot — the routing decisions, defaults, and unit handling the converter applies.
  • todos track known gaps where a mapping is planned but not yet implemented; these roll up into Model Coverage.

For the complete slot-by-slot listing with every mapping rendered, browse the Schema Reference.