Qubit Energy Schemas

Open-source JSON Schema definitions for energy data interchange. Built by the energy community, for the energy community.

Vision

Creating a universal, open standard for energy data that enables seamless integration between energy assets, monitoring systems, and optimization platforms. Our schemas provide a common language for the energy transition.

Core Schemas

Foundation Schemas

Organization

Energy company, utility, or entity managing energy assets

Site

Physical location containing energy assets (solar farm, charging station)

Asset

Physical energy equipment (solar panels, batteries, inverters)

Meter

Energy measurement devices providing consumption/generation data

Sensor

Environmental or operational sensors (weather, temperature, vibration)

TimeSeries

Time-stamped measurements and telemetry data

Advanced Schemas (v0.2)

Tariff

Dynamic pricing with carbon intensity, P2P trading, V2G rates

Event

VPP dispatches, blockchain verification, AI anomaly detection

Weather Observation

Hyperlocal weather with satellite, drone, and AI-enhanced data

Demand Response

ML baselines, V2G coordination, flexibility market participation

Alarm

Predictive maintenance alerts and cybersecurity threat detection

Quick Start

Installation

# Clone the schemas repository
git clone https://github.com/qubit-foundation/qubit-energy-schemas.git
cd qubit-energy-schemas

# Install validation dependencies
pip install -r requirements.txt

Validate Example Data

python scripts/validate.py examples/site.json

Use in Your Project

Python
JavaScript
Go

import json
from jsonschema import validate

# Load schema
with open('schemas/v0.2/site.json') as f:
    schema = json.load(f)

# Your data
site_data = {
    "id": "sit_solar_farm_001",
    "name": "North Solar Farm",
    "organization_id": "org_acme_energy",
    "location": {
        "latitude": 37.7749,
        "longitude": -122.4194,
        "timezone": "America/Los_Angeles"
    }
}

# Validate
validate(instance=site_data, schema=schema)
print("✅ Data is valid!")

const Ajv = require('ajv');
const fs = require('fs');

// Load schema
const schema = JSON.parse(fs.readFileSync('schemas/v0.2/timeseries.json'));
const ajv = new Ajv();
const validate = ajv.compile(schema);

// Your data
const timeseriesData = {
  "id": "ts_solar_001_2024_01_15_14_30",
  "asset_id": "ast_solar_inverter_001",
  "metric": "energy_generation",
  "value": 2500.0,
  "unit": "kWh",
  "timestamp": "2024-01-15T14:30:00Z"
};

// Validate
const valid = validate(timeseriesData);
if (!valid) console.log(validate.errors);

package main

import (
    "encoding/json"
    "github.com/xeipuuv/gojsonschema"
)

func validateTimeSeries(data []byte) error {
    schemaLoader := gojsonschema.NewReferenceLoader("file:///schemas/v0.2/timeseries.json")
    documentLoader := gojsonschema.NewBytesLoader(data)
    
    result, err := gojsonschema.Validate(schemaLoader, documentLoader)
    if err != nil {
        return err
    }
    
    if !result.Valid() {
        return fmt.Errorf("validation failed: %v", result.Errors())
    }
    
    return nil
}

Schema Examples

TimeSeries Schema

The most commonly used schema for real-time energy data:

{
  "id": "ts_solar_farm_001_2024_01_15_14_30",
  "asset_id": "ast_solar_farm_001",
  "metric": "energy_generation",
  "value": 2500.0,
  "unit": "kWh",
  "timestamp": "2024-01-15T14:30:00Z",
  "quality": "good",
  "metadata": {
    "weather_condition": "sunny",
    "panel_temperature": 35.2,
    "inverter_efficiency": 0.98
  }
}

Asset Schema

Defines physical energy equipment:

{
  "id": "ast_battery_storage_001",
  "name": "Tesla Megapack 2XL",
  "site_id": "sit_energy_storage_facility",
  "type": "battery_storage",
  "specifications": {
    "capacity_kwh": 3916,
    "max_charge_rate_kw": 1890,
    "max_discharge_rate_kw": 1890,
    "efficiency": 0.89,
    "chemistry": "lithium_iron_phosphate"
  },
  "installation": {
    "commissioned_date": "2024-01-15",
    "warranty_years": 20,
    "installer": "Tesla Energy"
  }
}

Key Features

Standardization
Advanced Features
Quality & Reliability

Consistent Identifiers

Organizations: org_ prefix (e.g., org_pacific_gas_electric)
Sites: sit_ prefix (e.g., sit_solar_farm_001)
Assets: ast_ prefix (e.g., ast_inverter_001)
Meters: mtr_ prefix (e.g., mtr_main_001)
Sensors: sns_ prefix (e.g., sns_temperature_001)
TimeSeries: ts_ prefix (e.g., ts_generation_001)

UTC Timestamps

All timestamps use ISO 8601 UTC format: 2024-01-15T14:30:00Z

SI Units

Standardized on International System of Units (kWh, kW, °C, m/s, etc.)

Data Quality

Quality indicators: good, questionable, poor
Confidence scores for AI-generated data
Data source provenance tracking

Extensibility

metadata objects for custom fields
Backward-compatible versioning
Plugin architecture for domain-specific extensions

Validation

Comprehensive JSON Schema validation
Automated testing with 1000+ example records
CI/CD integration with validation workflows

Schema Versions

Always specify which schema version you’re using. Version 0.2 includes significant enhancements for blockchain, AI, and advanced energy markets.

Version 0.2 (Current)

Advanced tariff structures with dynamic pricing
Blockchain and smart contract integration
AI/ML metadata and confidence scoring
V2G and bidirectional energy flow support
Enhanced cybersecurity and threat detection

Version 0.1 (Legacy)

Foundation schemas for basic energy data
Simple tariff structures
Core asset and measurement definitions

Validation Tools

python scripts/validate.py examples/timeseries.json

Contributing

Fork Repository

Fork the schemas repository

Create Branch

git checkout -b feature/new-schema-enhancement

Make Changes

Add or modify schema files in schemas/v0.2/
Include example data in examples/
Update documentation

Validate

python scripts/validate.py
pytest tests/

Submit PR

Create a pull request with detailed description of changes

Best Practices

Always validate your data against the schemas before sending to production systems. Invalid data can cause downstream processing failures.

Schema Design Guidelines

Minimize Breaking Changes: Use optional fields for new features
Clear Naming: Use descriptive, unambiguous field names
Consistent Units: Always specify units explicitly
Rich Metadata: Include context and provenance information
Future-Proof: Design for extensibility and evolution

Implementation Tips

Performance

Cache compiled schemas for repeated validation to improve throughput

Error Handling

Provide meaningful error messages when validation fails

Monitoring

Track validation success rates and common error patterns

Versioning

Support multiple schema versions during migration periods

Real-World Examples

Solar Farm Monitoring

{
  "id": "ts_solar_generation_2024_01_15_14_30",
  "asset_id": "ast_solar_array_001",
  "metric": "energy_generation",
  "value": 1250.5,
  "unit": "kWh",
  "timestamp": "2024-01-15T14:30:00Z",
  "quality": "good",
  "metadata": {
    "irradiance_wm2": 850,
    "ambient_temp_c": 25.3,
    "panel_temp_c": 45.1,
    "inverter_efficiency": 0.976
  }
}

EV Charging Session

{
  "id": "ts_charging_power_2024_01_15_15_45",
  "asset_id": "ast_fast_charger_001",
  "metric": "charging_power",
  "value": 150.0,
  "unit": "kW",
  "timestamp": "2024-01-15T15:45:00Z",
  "quality": "good",
  "metadata": {
    "session_id": "ses_charge_001",
    "vehicle_id": "veh_tesla_model_s_001",
    "soc_percent": 65,
    "charging_curve": "fast"
  }
}

The Qubit Energy Schemas provide the data foundation that enables interoperability across the entire energy ecosystem. By establishing universal standards, we accelerate the development and deployment of innovative energy solutions.

Get Started

Layer 1: Data

Layer 2: Prediction

Layer 3: Optimization

Layer 4: Coordination

Layer 5: Settlement

Layer 6: Interface

​Qubit Energy Schemas

​Vision

​Core Schemas

​Foundation Schemas

Organization

Site

Asset

Meter

Sensor

TimeSeries

​Advanced Schemas (v0.2)

Tariff

Event

Weather Observation

Demand Response

Alarm

​Quick Start

​Installation

​Validate Example Data

​Use in Your Project

​Schema Examples

​TimeSeries Schema

​Asset Schema

​Key Features

​Schema Versions

​Version 0.2 (Current)

​Version 0.1 (Legacy)

​Validation Tools

​Contributing

​Best Practices

​Schema Design Guidelines

​Implementation Tips

Performance

Error Handling

Monitoring

Versioning

​Real-World Examples

​Solar Farm Monitoring

​EV Charging Session

Qubit Energy Schemas

Vision

Core Schemas

Foundation Schemas

Advanced Schemas (v0.2)

Quick Start

Installation

Validate Example Data

Use in Your Project

Schema Examples

TimeSeries Schema

Asset Schema

Key Features

Schema Versions

Version 0.2 (Current)

Version 0.1 (Legacy)

Validation Tools

Contributing

Best Practices

Schema Design Guidelines

Implementation Tips

Real-World Examples

Solar Farm Monitoring

EV Charging Session