Data Schema Reference

Demand Response

Version 1.1

Overview

This document provides the structure and attributes of the Recurve intake data schema to enable FLEX Programs’ Demand Response measurement and forecasting features. The schema outlines a consistent structure for representing enrollments, events, participations, interval usage, and service point metadata across utilities, aggregators, DERMS providers, and device vendors.

The intent of this schema is to ensure that all inputs required for baseline construction, event-impact calculation, comparison-group analysis, and forward-looking capacity forecasting are clearly defined. The schema versioned in this document applies specifically to Demand Response measurement and forecasting use cases and may evolve over time as new capabilities, technologies, and regulatory requirements are supported.

Validation

The FLEX platform will use the supplied JSONSchema (or equivalent OpenAPI) schemas to validate the structure of incoming data. If you choose to, you can use these same schemas to verify the data for testing or validation on your own systems. Exactly how to utilize these schemas will vary depending on the languages and frameworks that provide the source data. Recurve can provide example code, upon request, for validating JSON input against the provided schemas in various programming languages.

Entities

This section describes the core data entities that make up the Demand Response intake schema and how they relate to one another. Each entity represents a distinct concept required to model program structure, participant enrollment, event dispatch, and measured performance. These entities define the minimum set of inputs needed to link service points to programs and events, associate technologies and providers with dispatches, and supply the interval data used for measurement and forecasting. Detailed schema definitions and example files are provided for each entity to support consistent implementation and validation.

Download JSON Schema documents & examples:

https://docs.recurve.com/schemas/dr-data-schema-examples.zip

enrollments

Defines which service points are enrolled in which programs, when they became active, and through which delivery channel or aggregator. Links service points to the specific technologies and dispatches used to inform measurements and forecasts.

Field	Type	Required	Description	Constraints
enrollment_id	string	Yes	A unique identifier for program enrollment
program_id	string	Yes	Unique identifier for the program into which the service point was
service_point_id	string	Yes	Reference to the service point attached to the enrollment
provider_id	string	No	The provider (DERMs, OEM, Aggregator) responsible for dispatching the participant. (If multiple providers dispatch a participant, separate participations should be created for each.)
network	string	No	Network / call group / dispatch group associated with the enrollment
start_date	string	Yes	The date the enrollment started	ISO format date string
end_date	string \| null	No	When this enrollment ended. End dates that are missing or in the future are assumed to indicate active enrollments.	ISO format date string
technologies	array	No	List of technologies associated with the enrollment

enrollments.technologies

Field	Type	Required	Description	Constraints
name	string	Yes	The name of the technology, like 'Smart Thermostat.'
details	object	No	Additional details about devices

enrollments.technologies.details

Field	Type	Required	Description	Constraints
device_type	string	No	An indicator for the specific type of device, like the manufacturer or control type
device_count	number	No	The number of devices of the given type enrolled

Example

{
 "items": [
   {
     "metadata": {
       "last_updated": "2025-01-08"
     },
     "value": {
       "enrollment_id": "ENR-01",
       "program_id": "PROG-01",
       "end_date": null,
       "provider_id": "PROVIDER-1",
       "network": "Dispatch-Zone-A123",
       "service_point_id": "SP123",
       "start_date": "2025-01-08T16:48:00Z",
       "technologies": [
         {
           "name": "Smart Thermostat",
           "details": {
             "device_type": "Ecobee",
             "device_count": 1
           }
         }
       ]
     }
   }
 ]
}

events

Defines the timing, scope, and structure of each demand response event, forming the foundation for performance measurement.

Field	Type	Required	Description	Constraints
event_id	string	Yes	A unique identifier for the event
program_id	string	Yes	Reference to the demand response program
start_time	string	Yes	Start time of the event with timezone	format: date-time
end_time	string	Yes	End time of the event with timezone	format: date-time
is_test_event	boolean	No	Indicates whether the event represented a test

Example

{
 "items": [
   {
     "metadata": { 
       "last_updated": "2026-01-01T00:00:00Z"
     },
     "value": {
       "event_id": "EVENT-123",
       "program_id": "PROG-1",
       "start_time": "2025-01-01T00:00:00Z",
       "end_time": "2025-01-01T03:00:00Z",
       "is_test_event": false
     }
   }
 ]
}

interval_data

Hourly or 15-minute AMI data for all participating service points. This data provides the observed load used to calculate event impacts and serves as the basis for performance measurement.

Field	Type	Required	Description	Constraints
service_point_id	string	Yes	The service point ID to which this interval data belongs
meter_device_id	string	No	The meter device ID that generated this interval data, if available
start_time	string	Yes	Start datetime in ISO 8601 format	format: date-time
end_time	string	Yes	End datetime in ISO 8601 format	format: date-time
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"

Example

{
 "items": [
   {
     "metadata": {
       "last_updated": "2026-01-01T00:00:00Z"
     },
     "value": {
       "service_point_id": "SP-12345",
       "meter_device_id": "meter-xyz",
       "start_time": "2026-01-01T00:00:00Z",
       "end_time": "2026-01-01T01:00:00Z",
       "value": 5.67,
       "direction": "received"
     }
   },
   {
     "metadata": {
       "last_updated": "2026-01-01T00:00:00Z"
     },
     "value": {
       "service_point_id": "SP-12346",
       "meter_device_id": "meter-xyz",
       "start_time": "2026-01-01T00:00:00Z",
       "end_time": "2026-01-01T01:00:00Z",
       "value": 4.32,
       "direction": "delivered"
     }
   }
 ]
}

participations

Defines which service points are dispatched for a given event, including which specific networks, technologies, and providers associated with the service point.

Field	Type	Required	Description
event_id	string	Yes	Reference to the event
service\point_id	string	Yes	Reference to the service point
provider_id	string	No	The provider (DERMs, OEM, Aggregator) responsible for dispatching the participant. (If multiple providers dispatch a participant, separate participations should be created for each.)
opted_out	boolean	No	Indicates whether the participant took an action to opt out of this event.
technologies	array	No	List of technologies associated with the participation
network	string	No	Network / call group / dispatch group associated with dispatching the participant

participations.technologies

Field	Type	Required	Description		Constraints
name	string	Yes	The name of the technology, like 'Smart Thermostat'
details	object	No	Additional details about devices

participations.technologies.details

Field	Type	Required	Description	Constraints
device_type	string	No	An indicator for the specific type of device, like the manufacturer, or control type
device_count	number	No	The number of devices of the given type enrolled.

Example

{
 "items": [
   {
     "metadata": {
       "last_updated": "2026-01-01T00:00:00Z"
     },
     "value": {
       "event_id": "EVENT-123",
       "service_point_id": "SP-4321",
       "technologies": [
         {
           "name": "Smart Thermostat",
           "details": {
             "device_type": "Ecobee",
             "device_count": 1
           }
         }
       ],
       "provider_id": "Acme-DERMS",
       "network": "CG-1",
       "opted_out": false
     }
   }
 ]
}

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.

Field	Type	Required	Description	Constraints
service_point_id	string	Yes	A unique and stable identifier for the service point provided by the API user. Should not be a meter device ID, as these may change.
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)
sector	string	No	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", "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?	format: timestamp
rate_code	string	No	The tariff rate code under which this service point operates
agreement_id	string	No	A unique identifier for the agreement
account_id	string	No	A unique identifier for the account
start_date	string	No	Start date of the service point's contract agreement	ISO format date
end_date	string	null	No	End date of the service point's contract agreement

Example

{
 "items": [
   {
     "metadata": {
       "last_updated": "2026-01-12T10:00:00Z"
     },
     "value": {
       "start_date": "2024-01-01",
       "end_date": "2026-01-01",
       "service_point_id": "SP123",
       "service_point_type": "electricity",
       "account_id": "ACCOUNT123",
       "timezone": "America/Los_Angeles",
       "premise_id": "9999999999",
       "street_1": "123 Example St.",
       "street_2": "Unit 1",
       "city_town": "San Francisco",
       "state_province_region": "CA",
       "zip_code_postal_code": "94105",
       "county": "San Francisco",
       "country": "USA",
       "sector": "residential",
       "interval": "hourly",
       "substation": "SUB-0457",
       "feeder_line": "FD-12A",
       "naics_code": "221122",
       "can_export": true,
       "export_start_date": "2023-06-15T00:00:00Z",
       "rate_code": "E-TOU-RES",
       "agreement_id": "AGR-789456"
     }
   }
 ]
}

Change Log

Version	Date	Change
1.1	2025-11-16	Added device_count to technology details to support explicit device-level participation tracking. Clarified enrollment and participation relationships for multi-provider dispatch. Refined interval data direction semantics. Minor description and validation clarifications.

Demand Response

Version 1.1​

Overview

Validation

Entities

Download JSON Schema documents & examples:​

enrollments​

enrollments.technologies​

enrollments.technologies.details​

Example​

events​

Example​

interval_data​

Example​

participations​

participations.technologies​

participations.technologies.details​

Example​

service_points​

Example​

Change Log

Version 1.1

Download JSON Schema documents & examples:

enrollments

enrollments.technologies

enrollments.technologies.details

Example

events

Example

interval_data

Example

participations

participations.technologies

participations.technologies.details

Example

service_points

Example