Skip to main content

Mav.json to CIM Process

Introduction​

The mav.json file (Maverick JSON) is a simplified, OpenDSO-specific format for defining circuit models. It was designed to quickly create circuit models for testing and simulation purposes without the complexity of full CIM models.

This guide explains how to convert mav.json files to CIM XML format for ingestion into OpenDSO.

What is Mav.json?​

The Maverick Project File (mav.json) is a JSON file that defines:

  • Circuit Topology: Equipment and connections
  • Equipment Details: Device parameters and settings
  • Simulation Configuration: How to simulate the circuit
  • Communication Settings: External communication interfaces

Background​

The Maverick simple simulator was created to:

  • Speed up the creation of test circuits
  • Improve communication with simulated devices
  • Provide a lightweight format for circuit definition
  • Enable rapid prototyping of OpenDSO features

Mav.json Structure​

A mav.json file consists of several main sections:

1. CIM Metadata Section​

This section provides base CIM information for the feeder:

{
  "cim": {
    "line": "Feeder 1",
    "lineMrid": "f9cfd5e4-949d-487c-9c39-4400ec68a24f",
    "substation": "Region",
    "subregion": "City",
    "region": "Alpha",
    "location": "feeder1_src_Location",
    "coordinate": "feeder1_src_CrsUrn"
  }
}

Field Descriptions:

  • line: Descriptive name for the feeder
  • lineMrid: Unique identifier (UUID/GUID) that becomes the feeder mRID in topology
  • substation: Regional name denoting the location of the substation or microgrid
  • subregion: Generally the city where the assets are located
  • region: Larger grouping of assets (e.g., utility service territory)
  • location: Unique string used within CIM to denote a location
  • coordinate: Unique string used within CIM to denote a base coordinate system

2. Equipment Section​

Defines the electrical equipment in the circuit (breakers, switches, transformers, lines, loads, DER, etc.)

3. Topology Section​

Defines how equipment is connected (bus connections, phases, etc.)

4. Simulation Settings​

Configuration for how the circuit should be simulated

5. Communication Configuration​

Settings for external communication interfaces (DNP3, Modbus, OpenFMB)

Conversion Process: Mav.json to CIM​

The conversion from mav.json to CIM is performed by the cim-generator tool.

Prerequisites​

Required Software​

  • Git: To clone the cim-generator repository
  • Build Tools: CMake and C++ compiler
  • cim-generator: The OpenDSO tool for converting mav.json to CIM

Step 1: Install cim-generator​

Clone the cim-generator repository:

git clone git@gitlab.com:OES_OpenDSP/cim-generator.git
cd cim-generator

Build the Tool​

Follow the build instructions in the repository:

# Create build directory
mkdir build
cd build

# Configure and build
cmake ..
make

Note: The cim-generator repository may require updates to its documentation. Refer to any README or build instructions in the repository.

Step 2: Prepare Your Mav.json File​

Before conversion, ensure your mav.json file is complete and valid:

  1. Validate JSON Syntax: Ensure the file is valid JSON
  2. Check Equipment Definitions: All equipment should have required fields
  3. Verify Connectivity: Equipment connections should be complete
  4. Add Geospatial Data: Include latitude/longitude coordinates if available

Example Equipment Definition​

Your mav.json should include properly defined equipment with all necessary parameters for your circuit model.

Step 3: Run cim-generator​

Convert your mav.json file to CIM:

# From the cim-generator build directory
./cim-generator -f /path/to/your/circuit.mav.json

Command Options​

  • -f <filename>: Specify the path to your mav.json file
  • Additional options may be available; check ./cim-generator --help

Step 4: Locate Output Files​

After conversion, cim-generator creates a directory structure:

feeders/
  └── [circuit_name]/
      └── cim_cartesian.xml

The cim_cartesian.xml file is your CIM output file, ready for ingestion into OpenDSO.

Step 5: Validate the CIM Output​

Before ingesting into OpenDSO, validate the generated CIM file:

Check File Structure​

Open the cim_cartesian.xml file and verify:

  1. XML Validity: File is well-formed XML
  2. CIM Namespace: Contains proper CIM namespace declarations
  3. Equipment Elements: All equipment from mav.json is present
  4. Connectivity: Terminal and connectivity nodes are defined
  5. mRIDs: All elements have unique mRID identifiers

Example CIM Output Structure​

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:cim="http://iec.ch/TC57/CIM100#">

  <!-- Feeder definition -->
  <cim:Feeder rdf:ID="f9cfd5e4-949d-487c-9c39-4400ec68a24f">
    <cim:IdentifiedObject.name>Feeder 1</cim:IdentifiedObject.name>
  </cim:Feeder>

  <!-- Equipment definitions -->
  <cim:Breaker rdf:ID="breaker-uuid">
    <cim:IdentifiedObject.name>MainBreaker</cim:IdentifiedObject.name>
    <!-- Additional properties -->
  </cim:Breaker>

  <!-- More equipment and connectivity -->

</rdf:RDF>

Testing the Conversion​

Option 1: Test with Maverick Simulator​

Before generating CIM, test your mav.json with the Maverick simulator:

# Clone Maverick repository (if needed)
git clone [maverick-repo-url]

# Run Maverick with your mav.json
# Follow Maverick documentation for running

If Maverick runs successfully with your mav.json, the file is well-formed and ready for CIM generation.

Option 2: Validate with CIMEX​

You can validate the generated CIM by attempting to parse it with CIMEX (topology-genesis):

# Run CIMEX with your generated CIM file
./cimex -c /path/to/cim_cartesian.xml -e /path/to/config.yml --drop

This will attempt to parse the CIM file and display any errors or warnings.

Best Practices for Mav.json Files​

1. Use Meaningful Names​

Give equipment and buses descriptive names:

  • Good: "MainBreaker", "LineSegment_A_B", "Load_Building_1"
  • Avoid: "B1", "L1", "Device1"

2. Generate Valid UUIDs​

Use proper UUID/GUID format for all mRIDs:

  • Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  • Use UUID generation tools to create unique identifiers
  • Don't reuse mRIDs across different equipment

3. Include Geographic Coordinates​

When possible, include latitude/longitude for equipment:

  • Enables proper visualization in GIS applications
  • Helps with spatial analysis
  • Required for some OpenDSO features

4. Define Complete Connectivity​

Ensure all equipment has proper bus connections:

  • Specify both terminals for line segments
  • Define phase connections (A, B, C, N)
  • Verify radial topology (no unintended loops)

5. Use Realistic Parameters​

Use realistic electrical parameters:

  • Voltage levels should match system nominal voltages
  • Line impedances should be reasonable for the distance/type
  • Load values should be realistic for the application

6. Document Custom Extensions​

If you add custom fields to mav.json:

  • Document what they represent
  • Ensure they map to CIM equivalents
  • Consider if cim-generator supports them

Supported Equipment Types​

The mav.json to CIM conversion supports the following equipment types:

  • Breakers: Circuit breakers
  • Reclosers: Automatic reclosers
  • Switches: Load break switches
  • Transformers: Power transformers
  • Line Segments: Distribution lines
  • Loads: Energy consumers
  • Voltage Sources: Substation sources
  • Capacitors: Shunt capacitors
  • Voltage Regulators: Line regulators
  • DER Equipment:
    • Solar/PV systems
    • Energy storage systems (ESS)
    • Generators

Common Issues and Troubleshooting​

Issue: cim-generator Not Building​

Cause: Missing dependencies or build tools

Solution:

  • Ensure CMake is installed
  • Verify C++ compiler is available
  • Check for any required libraries
  • Review error messages during build

Issue: Invalid JSON Format​

Cause: Syntax errors in mav.json file

Solution:

  • Use a JSON validator to check syntax
  • Common errors: missing commas, unclosed brackets, unquoted strings
  • Use a JSON-aware text editor with syntax highlighting

Issue: Missing Equipment in CIM Output​

Cause: Equipment not properly defined in mav.json or not supported by cim-generator

Solution:

  • Review mav.json equipment definitions
  • Check cim-generator documentation for supported types
  • Verify equipment has all required fields
  • Check conversion log for warnings

Issue: Connectivity Errors​

Cause: Bus connections not properly defined

Solution:

  • Verify all equipment has valid bus connections
  • Check that bus names are consistent
  • Ensure phases are properly specified
  • Review topology for completeness

Issue: Duplicate mRIDs​

Cause: Same UUID used for multiple equipment

Solution:

  • Generate unique UUIDs for each piece of equipment
  • Use UUID generation tools
  • Check for copy-paste errors in mav.json

Maintaining Mav.json Files​

Version Control​

Keep mav.json files in version control:

  • Track changes to circuit models
  • Document why changes were made
  • Enable rollback if issues occur

File Organization​

Organize mav.json files logically:

circuits/
  ├── test_circuits/
  │   ├── simple_radial.mav.json
  │   └── ieee_13_node.mav.json
  ├── production/
  │   ├── feeder_a.mav.json
  │   └── feeder_b.mav.json
  └── templates/
      └── template.mav.json

Documentation​

For each mav.json file, document:

  • Purpose of the circuit
  • What it represents
  • Any special configurations
  • Date created/modified
  • Known issues or limitations

When to Use Mav.json vs. Other Formats​

Use Mav.json When:​

  • Creating test circuits quickly
  • Prototyping new OpenDSO features
  • Circuit model is simple and radial
  • You need to iterate rapidly on circuit design
  • Working in a development/testing environment

Use Other Formats When:​

  • OpenDSS: Need detailed power flow analysis, have existing DSS models, require simulation validation
  • Native CIM: Receiving data from utility systems, need industry-standard format, working with complex models
  • CYME/Synergi Export: Have existing utility planning models

Migration Path​

If you have existing mav.json files and want to move to other formats:

  1. Keep Using Mav.json: For simple test circuits and development
  2. Convert to CIM: Use cim-generator (this guide)
  3. Transition to OpenDSS: For circuits requiring simulation, create OpenDSS model, then use DSS to CIM Process
  4. Direct CIM Creation: For production, work with utility data in native CIM format

Next Steps​

After converting your mav.json to CIM:

  1. Validate the Output: Check the generated CIM XML file
  2. Test with CIMEX: Attempt to parse with topology-genesis
  3. Ingest into OpenDSO: Follow the CIM Ingestion Process guide

References​