Data Schema Reference
Energy Efficiency Measurement
Version 1.1
Overview
This document provides the structure and attributes of the Recurve intake data schema to enable FLEX Programs’ measurement features for energy efficiency programs. The schema outlines a consistent structure for representing interval usage, service point metadata, and project data.
This schema ensures that all inputs required to enable baseline construction, project impact calculation, and comparison-group analysis are available. The schema versioned in this document applies specifically to energy efficiency measurement use cases and may evolve as new capabilities, technologies, and regulatory requirements are supported.
Entities
This section describes the core data entities that make up the Energy Efficiency Measurement intake schema and how they relate to one another. Each entity represents a distinct concept required to create baseline models and calculate measured performance. These entities define the minimum set of inputs required to link service points to energy-efficiency projects and supply the interval data used for measurement. Detailed schema definitions and example files are provided for each entity to support consistent implementation and validation.
Timestamp Format
All timestamps must use the ISO 8601 format and include the date, time, and timezone.
Supported Formats: YYYY-MM-DDTHH:MM:SS±HH:MM or YYYY-MM-DDTHH:MM:SSZ (UTC)
Examples: 2026-06-26T13:15:30-07:00, 2026-06-26T20:15:30Z
interval_data
Hourly or 15-minute AMI electric data and/or daily interval gas data, for all participating service points. This data provides the observed load used to calculate project impacts and serves as the basis for performance measurement.
File Requirements
- interval_data file names must begin with interval_data and end with the appropriate file type suffix (.csv)
- If any delimiters are present in any field values, all values must be wrapped in double quotes
- Files must have a header row that contains all required fields
- "Null" values should only be passed as empty values
Examples of acceptable file names
- interval_data_20240204.csv
- interval_data_westernRegion.csv
| Field | Type | Required | Description | Notes |
|---|---|---|---|---|
| service_point_id | string | Yes | A specific location at a premise where utilities supply service, or where usage occurs. Multiple service_point_ids can belong to a single premise_id. | “9471297459” “df-443-jk” |
| start_time | string | Yes | Start datetime in ISO 8601 format. | ISO format date |
| end_time | string | Yes | End datetime in ISO 8601 format. | ISO format date |
| value | number | Yes | The interval data value. | format: float |
| direction | string | No | Direction of energy flow: 'delivered' or 'received'. Assumed to be received if not specified. | enum: "delivered", "received" |
service_points
Customer metadata in reference to the service points that are either enrolled in measured programs or are supplied as non-participant data to support comparison groups.
File Requirements
- Service point file names must begin with service_point_ and end with the appropriate file type suffix (.csv)
- If any delimiters are present in any field values, all values must be wrapped in double quotes
- Files must have a header row that contains all required fields, and any applicable non-required fields
- "Null" values should only be passed as empty values
Examples of acceptable file names
- service_point_data_20240204.csv
- service_point_data_westernRegion.csv
| Field | Type | Required | Description | Notes |
|---|---|---|---|---|
| service_point_id | string | Yes | A specific location at a premise where utilities supply service, or where usage occurs. Multiple service_point_ids can belong to a single premise_id. | |
| service_point_type | string | Yes | The type of the service point, either Gas or Electric. | enum: “electricity”, “gas” |
| substation | string | No | Substation identifier. | |
| feeder_line | string | No | Feeder line identifier. | |
| timezone | string | No | IANA timezone string (e.g., America/Los_Angeles). | |
| premise_id | string | No | A unique identifier for the premise, if available. | |
| street_1 | string | Yes | ||
| street_2 | string | No | ||
| city_town | string | Yes | ||
| state_province_region | string | Yes | ||
| zip_code_postal_code | string | Yes | ||
| county | string | No | ||
| country | string | No | ||
| naics_code | string | No* | The 6-digit North American Industry Classification System (NAICS). *Required for Commercial programs for comparison group mapping. | |
| sector | string | Yes | The sector classification of the premise. | enum: "residential", "commercial", "Industrial", "agriculture", "other" |
| interval | object | No | The interval at which this meter device records data, if available. | enum: "15min", “30min”, "hourly", "daily" |
| can_export | boolean | No | This service point can export to the grid. This is relevant if solar is installed. | |
| export_start_date | string | No | When did this service point become capable of exporting energy? | ISO 8601 date format |
| rate_code | string | No | The tariff rate code under which this service point operates. | |
| equity_flag | string | No | An indicator for customer participation in income-qualified, medical, geographic, or debt-relief assistance programs. Helps identify vulnerable, protected, or subsidized ratepayer segments. | enum: “CARE”, “FERA”, “LIFE_SUPPORT”, “MEDICAL_BASELINE”, “DISADVANTAGED_COMMUNITY”, “TRIBAL”, “MOBILE_HOME” |
| account_id | string | No | A unique identifier for the account. | |
| agreement_id | string | No | A unique identifier for the agreement between the service point and the customer. Along with the corresponding date, it identifies the latest customer at the service point. Often referred to as service agreement ID, customer agreement ID, or account agreement ID. | |
| start_date | string | No | Start date of the service point's contract agreement. | ISO 8601 date format |
| end_date | string | null | No | End date of the service point's contract agreement. |
project_data
Project intervention data for the measured program(s). This data provides the basis for the measured impacts and defines each service point’s baseline period, blackout period, and measurement period. This file type is not required if using the Enrollments Tool in Project Hub to collect project data.
File Requirements
- Project data files must start with project_data_ and end with the appropriate file type suffix (.csv)
- If any delimiters are present in any field values, all values must be wrapped in double quotes
- Files must have a header row that contains all required fields, and a field name for each preferred data column provided
- "Null" values should only be passed as empty values
- Should include data at the intervention level, and then the interventions aggregate into projects - there should not be a need for any pre-aggregated project data
Examples of acceptable file names
- project_data_20240204.csv
- project_data_june2024.csv
| Field | Type | Required | Description | Notes |
|---|---|---|---|---|
| included_service_point_ids | string | Yes | A specific location at a premise where utilities supply service, or where usage occurs. Multiple service_point_ids can belong to a single premise_id. Should include all service point IDs for the intervention. This list of IDs must be separated by commas and all wrapped in double quotes. | "9471297459, 9471297000” “df-443-jk” |
| intervention_start_date | date | Yes | date work began on the intervention. | ISO 8601 date format |
| intervention_end_date | date | Yes | date work completed on the intervention. | ISO 8601 date format |
| measure_category | string | No* | Recurve defined measure categories - to be mapped based on the provided measure name. *Required if including valuation, for load shape mapping and subsequent dollar valuation and prorated realization rate. | "Lighting" "Heat Pump Water Heater" |
| measure_name | string | Yes | Client provided measure name information. | "Heat Pump Retrofit" "Heat Pump Water Heater" "Attic Insulation" |
| contractor | string | Yes | Name of contractor or aggregator performing the work of the measure install. | "John Doe's Energy Efficiency Co" "Best Lighting Upgrades Inc" |
| effective_useful_life | integer | Yes | Expected number of years the installed measure will be useful. | 12 |
| predicted_savings_kwh | float | Yes | Predicted measure savings for use in the realization rate (kWh). | 1000.00 |
| predicted_savings_therms | float | Yes | Predicted measure savings for use in realization rate (therms). | 30.00 |
| program_name | string | Yes | Name of program to include this work. | "Utility Demand Flexibility Program" "Summer Peak Reduction Program" |
| intervention_id | string | Yes | Unique ID for the intervention/measure. If an intervention ID is provided, it will take priority in the user display. | "project_d2_799" "ee_882" |
| provided_project_id | string | No | Aggregator or other provided project ID. This can be repeated across multiple interventions (i.e., multi-measure projects) | "p_123" "ee_005" |
| deemed_savings_kwh | float | No | Deemed measure gross annual electricity savings (kWh) | 500.00 |
| deemed_savings_therms | float | No | Deemed measure gross annual electricity savings (therms) | 40.00 |
| cost_currency | string | No | The currency used for the costs provided. For display purposes only. | "USD" |
| cost_customer | float | No | The cost that the customer incurred for the intervention. | 70.00 |
| cost_incentive | float | No | The incentive provided for the intervention. | 15.00 |
| cost_utility | float | No | The cost that the utility incurred for the intervention, separate from the cost paid by the customer or incentives. | 15.00 |
| num_units | integer | No | The number of units installed with the intervention. | 2 |
| equipment_make | string | No | The make associated with the intervention. | "Goodman" |
| equipment_model | string | No | The model associated with the intervention. | "2.5 Ton SEER20" |
| measure_details | string | No | An optional field to include any extra details about the measure, such as the configuration information. | "integrated" "split system" |
Change Log
| Version | date | Change |
|---|---|---|
| 1.1 | 2026-07-09 | Initial version |