[Specification] CDS-WG3-01 - Customer Data by daniel-utilityapi · Pull Request #26 · lfe-cds/CDS-Customer-Data

daniel-utilityapi · 2024-03-28T15:00:02Z

This is the initial draft of a proposed specification for utility servers to publish customer data.

Relevant Issue: #24

NOTE: This is a draft in progress (see "TODO" throughout the draft) and will continue to be developed and modified based on feedback and comments in this pull request and during meetings

See a rendered preview of this specification on the maintainer's branch:
https://daniel-utilityapi.github.io/CDS-Customer-Data/specs/cds-wg3-01

Timeline

This specification is under active development, so it will be merged when complete and reaching consensus among working group participants.

halliecramer1

Clarifications and suggested changes, mainly related to customer usage data.

halliecramer1 · 2024-04-05T23:03:42Z

website/specs/cdsc-wg1-03/overview.md

+            "cds_modified": "2024-01-01T00:00:00Z",
+            "meter_number": "M55555555",
+            "meter_type": "usage_forward_only",
+            "current_servicepoints": [


is there a relationship between meter devices and service points?

I reckon a service point can have multiple meter devices linked to it. If so, maybe it would be great that in the Service Point Endpoint, we also add the meterdevice_ids that are linked to it.

halliecramer1 · 2024-04-05T23:04:14Z

website/specs/cdsc-wg1-03/overview.md

+            "cds_modified": "2024-01-01T00:00:00Z",
+            "cds_account_id": "111111111111-1",
+            "account_number": "22222-222-22222",
+            "statement_date": "2024-01-01",


also including billing cycle?

halliecramer1 · 2024-04-05T23:07:29Z

website/specs/cdsc-wg1-03/overview.md

+                    "item_type": "charge",
+                    "for": "distribution_entity",
+                    "name": "Electric delivery",
+                    "start": "2023-12-01T00:00:00Z",


why do some of these have start / end and other item types don't?

halliecramer1 · 2024-04-05T23:09:03Z

website/specs/cdsc-wg1-03/overview.md

+                {
+                    "summary_type": "demand",
+                    "name": "Commercial Peak Demand",
+                    "start": "2023-12-01T00:00:00Z",


if these start / end link to bill section and are all the same, then maybe can simplify and remove from here

halliecramer1 · 2024-04-05T23:12:38Z

specifications/cdsc-wg1-03.md

+
+This specification was developed as part of the global effort to combat the climate crisis. Specifically, in order to scalably measure carbon emissions of organizations and calculate the impact of deploying and operating clean energy technologies, companies need an efficient means of requesting authorization for and accessing Customer data from utilities and other entities.
+
+There are thousands of utilities serving Customers across the world, and each have their own way of providing access to and formatting Customer data. This specification defines a way for these utilities and other entities ("Servers") to provide a standardized, structured process for external users and companies ("Clients") to access Customer data, requesting authorization from Customers if needed. By offering a standardized a Customer data access protocol, utilities and other entities can enable secure interoperability with other external systems providing climate-change fighting services such as carbon tracking, decarbonization measures, grid flexibility capabilities, and energy benchmarking.


typo, "offering a standardized Customer.."

halliecramer1 · 2024-04-05T23:37:24Z

specifications/cdsc-wg1-03.md

+* `amount_due_date` - _ISO8601 date_ - (REQUIRED) The value shown on the Customer-facing bill statement as the date that the `amount_due` value is due, if available.
+* `shutoff_prevention_minimum_due` - _decimal or `null`_ - (REQUIRED) The value shown on the Customer-facing bill statement as the minimum amount due to prevent service shutoff, if available. If there is no shutoff notice on the Customer-facing bill statement, this value is `null`.
+* `shutoff_prevention_date` - _ISO8601 date or `null`_ - (REQUIRED) The value shown on the Customer-facing bill statement as the date that the `shutoff_prevention_minimum_due` value is due, if available. If `shutoff_prevention_minimum_due` is `null`, this value is also `null`.
+* `program_participations` - _Array[[ProgramParticipation](#program-participation-format)]_ - (REQUIRED) A list of Account-level programs in which the Customer is participating. If the Server does not have this information or the Customer is not participating in any Account-level programs, this value is and empty list (`[]`).


how does program participation relate to rate plan? e.g. could be fees related to a program that are separate / add on from the rate?

halliecramer1 · 2024-04-05T23:41:04Z

specifications/cdsc-wg1-03.md

+
+Listings of Aggregation objects MUST be ordered in reverse chronological order by `modified` timestamp, where the most recently updated relevant Aggregation MUST be first in each listing.
+
+## 11. Usage Segments API <a id="usage-segments-api" href="#usage-segments-api" class="permalink">🔗</a>


what is meant by "Segments"?

halliecramer1 · 2024-04-05T23:42:51Z

specifications/cdsc-wg1-03.md

+
+This specification requires Servers provide a set of APIs allowing Clients to retrieve a Customer's and Server's Usage Segment objects for which they are authorized to access. These APIs are authenticated using a Bearer `access_token` [granted](/specs/cdsc-wg1-02#grants-api) that provisions access for a [scope](#authorization-scopes) that allows access to the Usage Segments API.
+
+### 11.1. Usage Segment Object Format <a id="usage-segment-format" href="#usage-segment-format" class="permalink">🔗</a>


when calling usage, can you specify as parameters: which service contracts? what time period? what data granularity (e.g. 15min, hourly, monthly)?

halliecramer1 · 2024-04-05T23:57:20Z

specifications/cdsc-wg1-03.md

+* `segment_end`
+* `interval`
+* `format`
+* `values`


extension to working group 2 - breakdown of values by fuel source and emissions e.g. (not fully compatible)
"supplier_mix": [
{
"startDatetime": "2021-06-01 00:00:00+00",
"endDatetime": "2021-06-01 01:00:00+00",
"values": [10.5, 50]
"format": ["kWh", "tCO2e"]
"valuesByFuelSource": [
{
"technology": "Thermal - Steam engine - Unspecified",
"type": "Fossil - Solid - Hard Coal - Unspecified",
"values": [5.0, 50]
},
{
"technology": "Solar - Photovoltaic - Unspecified",
"type": "Renewables - Heating and Cooling - Solar",
"values": [5.5, 0]
},
// Additional entries for other fuel sources if available
]
}

The discussion indicated it's okay if it's not fully compatible with the Power Systems specs.

halliecramer1 · 2024-04-06T00:22:13Z

specifications/cdsc-wg1-03.md

+* `interval`
+* `format`
+* `values`
+


Customer EACs API: add list of eacs retired on customer's behalf
eac_id - string - (REQUIRED) The unique identifier for this EAC object.
eac_source - string - (REQUIRED) The registry provider where the EAC was issued and retired by the Service provider on the Customer's behalf, or by the Customer.
destination_id - string (REQUIRED) The organization responsible for the retirement of the EAC.
beneficiary_id - string (REQUIRED) The ID of the beneficiary (individual account or group of accounts) for this EAC.
beneficiary_type - [BeneficiaryType] - (REQUIRED) The type of beneficiary that the beneficiary ID represents, e.g. Account ID or Utility Program identifier
program_type - [ProgramType] - (OPTIONAL) Category of EAC pools dedicated for a certain purpose across a certain set of customers, e.g. ["CES", "Non-bypassable Clean Energy", "PPA", "XX Tariff"]
asset_id - string - (REQUIRED) The ID of the generation asset that generated the EAC.
technology_type - [TechnologyType] - (REQUIRED) The type of technology of the generating asset (should align with technology and type from "values by fuel source").
emissions_factor_direct - decimal - (REQUIRED) Direct emissions factor of the asset in gCO2/kWh
emissions_factor_lca - decimal - (REQUIRED) Lifecycle assessment emissions factor of the asset in gCO2/kWh
asset_origination - string - (REQUIRED) Location of asset (e.g. from region / grid)
asset_destination - string - (REQUIRED) Location of destination ID entity or beneficiary (e.g. to region / grid)
issuance_date - ISO8601 date - (REQUIRED) Date registry issued EAC.
retirement_date - ISO8601 date - (REQUIRED) Date that destination ID entity retired EAC.
period_start - ISO8601 datetime - (REQUIRED) Period start of generation from asset.
period_end - ISO8601 datetime - (REQUIRED) Period end of generation from asset.
volume - decimal - (REQUIRED) kWh of generation

Relevant fields in EACs/GCs cancellation statements, returned after asking for them on a certain period and contract:

period_start - ISO8601 datetime - (REQUIRED) Production period start fits within requested period
period_end - ISO8601 datetime - (REQUIRED) Production period end fits within requested period
registry_id - string - (REQUIRED) For traceability and to know the origin and registry managing the EAC/GC
beneficiary_id - string - (REQUIRED) The Customer or account identifier.
asset_id - string - (REQUIRED) The generation asset’s identifier.
asset_name - string (OPTIONAL) Sometimes, it is pretty challenging to relate the production sites just with the asset_id
technology_type - (REQUIRED) The technology used to generate the EAC.
production_country - string (REQUIRED) Needed for matching and reporting criteria
production_site_commissioning_date - ISO8601 datetime (REQUIRED) Relevant for reporting purposes (RE100 technical criteria)
quantity - integer (REQUIRED) - Volume of canceled EACs/GCs
unit - (REQUIRED) The unit of the EAC’s quantity.
certificate_ids - array - (REQUIRED). It usually comes with the following format: From Certificate ID & To Certificate ID (134567.....134599)
emissions_factor_direct - decimal - (REQUIRED) The carbon intensity of the generating asset in kg CO2 / kWh.

Would be great to discuss together if we fullfill all information/use cases and some of the listed fields.

eloifabrega · 2024-04-23T10:47:29Z

website/specs/cdsc-wg1-03/overview.md

+            "account_address": "123 Main St\nAnytown, TX 11111",
+            "account_type": "business",
+            "account_contacts": [
+                {


Maybe it would be better to add a reference to the next level of information? Meaning:

I check the Accounts Endpoint -> I am able to identify the Service Contracts linked to this account

I check the Service Contracts -> I am able to identify the Service Points linked to this contract

I check the Service Point --> I am able to identify the meter devices linked to the service point.

Idk if I missed something. But I would go for a Top to bottom approach.

eloifabrega · 2024-04-23T11:00:43Z

website/specs/cdsc-wg1-03/overview.md

+}
+```
+
+## Aggregation Endpoint <a id="aggregation-api" href="#aggregation-api" class="permalink">🔗</a>


missing the aggregation endpoint in the index?

eloifabrega · 2024-04-23T12:26:06Z

website/specs/cdsc-wg1-03/overview.md

+            "format": ["kwh_net", "kwh_fwd", "kwh_rev"],
+            "values": [
+                [{"v": 1.2}, {"v": 1.2}, {"v": 0.0}],
+                [{"v": 1.1}, {"v": 1.1}, {"v": 0.0}],


I reckon we only account here for settlement/validated data. Nevertheless, depending on the utility, confirmed readings could come pretty delayed. Should we differentiate the type of reading? (e.g. estimated/confirmed?). In case readings need to be made available before the settlement period? (e.g. use cases for demand response)

As an example: Energinet API offers the following quantity.quality:

Not Available: Specifies that the grid operator has submitted a “missing indicator” to DataHub for the specific position, meaning that the energy quantity is not available. Therefore, no quantity will be returned for the specific
position.

Estimated: Specifies that the grid operator has submitted the quantity to DataHub as an estimate

As provided: Specifies that the grid operator has submitted the quantity to DataHub as measured.

Incomplete: is applied to an aggregated energy quantity if at least one of the quantities included in the aggregation has been submitted to DataHub with a “missing indicator”

API data description can be found here: https://energinet.dk/media/4beb0pgg/customer-and-third-party-api-for-datahub-eloverblik-data-description_validfrom_20240626.pdf

eloifabrega · 2024-04-23T12:52:00Z

specifications/cdsc-wg1-03.md

+    * `rateplan_code`
+    * `rateplan_name`
+
+Listings of Service Contract objects MUST be ordered in reverse chronological order by `cds_modified` timestamp, where the most recently updated relevant Service Contract MUST be first in each listing.


when we say relevant service contracts we refer to the ones active, for example? Or which other variables have an influence here on the order?

eloifabrega · 2024-04-23T13:29:16Z

specifications/cdsc-wg1-03.md

+* `cds_usagesegment_id` - _string_ - (REQUIRED) The Server's unique identifier for this Usage Segment object.
+* `cds_created` - _ISO8601 datetime_ - (REQUIRED) When the Server created this Usage Segment object.
+* `cds_modified` - _ISO8601 datetime_ - (REQUIRED) When the Server last modified this Usage Segment object.
+* `cds_aggregation_ids`


Are the descriptions of the following values missing? All of them will be REQUIRED, correct?

and what does format describe?

kdonhowe-rh · 2024-05-22T17:50:22Z

website/specs/cdsc-wg1-03/overview.md

+            "contract_end": null,
+            "service_type": "electric",
+            "service_class": "commercial",
+            "rateplan_code": "COMM-1A",


Would other rate plan modifiers like CARE and FERA be included here? Also, what about baseline territory?

kdonhowe-rh · 2024-05-22T17:58:10Z

website/specs/cdsc-wg1-03/overview.md

+            "cds_created": "2024-01-01T00:00:00Z",
+            "cds_modified": "2024-01-01T00:00:00Z",
+            "meter_number": "M55555555",
+            "meter_type": "usage_forward_only",


Would this also include information like whether this is a submeter for EV charging, for example?

Temporal247 · 2024-09-12T09:59:36Z

website/specs/cdsc-wg3-01/overview.md

+            "cds_created": "2024-01-01T00:00:00Z",
+            "cds_modified": "2024-01-01T00:00:00Z",
+            "eac_number": "AAAZZZ-123",
+            "source_id": "101010101-10aaa",


What is the source refering to here? is it the production device Unique ID?

Temporal247 · 2024-09-12T10:01:27Z

website/specs/cdsc-wg3-01/overview.md

+{
+    "eacs": [
+        {
+            "cds_eac_id": "101010101-10",


Is this the EAC Unique ID from the registry or something else?

"101010101-10" is this just an example or does it fix the ID length to this number of figures, if so it may be too small

Temporal247 · 2024-09-12T10:03:09Z

website/specs/cdsc-wg3-01/overview.md

+            "related_servicepoints": [...],
+            "related_meterdevices": [...],
+            "related_billsections": [...],
+            "related_eacs": [...],


Is this meant to be a string of EAC IDs for for the certificates that are retired for load matching claims?

Temporal247 · 2024-09-12T10:06:21Z

website/specs/cdsc-wg3-01/overview.md

+                    "retired": "2024-02-01",
+                    "start": "2024-01-01T00:00:00Z",
+                    "end": "2024-02-01T00:00:00Z",
+                    "unit": "kwh",


Why in kWh and not in Wh? recommend Wh

Temporal247 · 2024-09-12T10:09:58Z

website/specs/cdsc-wg3-01/overview.md

+Content-Type: application/json;charset=UTF-8
+
+{
+    "eacs": [


Is this EAC data based on a particular base standard or a specific EAC registry for example? EnergyTag has a standard list of attributes that we could use.

https://docs.google.com/spreadsheets/d/1aaNP2LLGvd2WW9iBqA5yjngRahrwnveB2t0vMFlXT7M/edit?gid=0#gid=0

and an API spec for hourly EAC registries that could also be helpful here:
https://energytag.org/api/#tag/Certificates/operation/certificate_bundle_cancellation_certificates_certificates_cancel_post

eloifabrega · 2024-09-12T13:11:12Z

website/specs/cdsc-wg3-01/overview.md

+            "asset_id": "AP111111",
+            "asset_origination": "grid",
+            "asset_destination": "grid",
+            "technology_type": "solar",


Here, the types of energy inputs and technologies defined in the European Energy Certificates System (EECS) and AIB:

https://www.aib-net.org/sites/default/files/assets/eecs/facts-sheets/AIB-2024-EECSFS-05%20EECS%20Rules%20Fact%20Sheet%2005%20-%20Types%20of%20Energy%20Inputs%20and%20Technologies%20-%20Release%207.8.pdf

eloifabrega · 2024-09-12T13:13:25Z

website/specs/cdsc-wg3-01/overview.md

+            "asset_id": "AP111111",
+            "asset_origination": "grid",
+            "asset_destination": "grid",
+            "technology_type": "solar",


Here, the types of energy inputs and technologies defined in the European Energy Certificate System (EECS) Rules approved by AIB:

https://www.aib-net.org/sites/default/files/assets/eecs/facts-sheets/AIB-2024-EECSFS-05%20EECS%20Rules%20Fact%20Sheet%2005%20-%20Types%20of%20Energy%20Inputs%20and%20Technologies%20-%20Release%207.8.pdf

…in the Server metadata, so we don't have to define a comprehensive EAC format, and Servers can just provide access to the EAC data they have in whatever format the locality uses

daniel-roesler · 2025-10-16T14:56:24Z

I am replacing this pull request with Pull Request #31, which is from the Maintainer branch on my new account.

added draft of CDSC-WG1-03 spec and overview

15d04f0

halliecramer1 reviewed Apr 6, 2024

View reviewed changes

added EACs to cdsc-wg1-03 draft spec

63d518b

eloifabrega reviewed Apr 23, 2024

View reviewed changes

kdonhowe-rh reviewed May 22, 2024

View reviewed changes

daniel-utilityapi added 2 commits May 28, 2024 12:22

added better descriptions for some Usage Segment attributes

336d5b6

Merge branch 'upstream-main' into issue_24_customer_data

ef7d8bf

daniel-utilityapi changed the title ~~[Specification] CDSC-WG1-03 - Customer Data~~ [Specification] CDSC-WG3-01 - Customer Data Jul 16, 2024

daniel-utilityapi added 6 commits August 8, 2024 08:26

Merge remote-tracking branch 'upstream/main' into upstream-main

2c80fec

testing collapsing example sections

7427a07

Merge remote-tracking branch 'upstream/main' into upstream-main

91b81ab

Merge branch 'upstream-main' into issue_24_customer_data

fc19e7e

added examples of usagesegments for various situations

e127991

refactored EAC objects to allow for interval-based EACs

37672a5

Temporal247 reviewed Sep 12, 2024

View reviewed changes

eloifabrega reviewed Sep 12, 2024

View reviewed changes

daniel-utilityapi added 4 commits September 25, 2024 14:51

moved EAC data format specifics to external URL with defined formats …

961e642

…in the Server metadata, so we don't have to define a comprehensive EAC format, and Servers can just provide access to the EAC data they have in whatever format the locality uses

Merge branch 'upstream-main' into issue_24_customer_data

ad3b635

added Value Format and Value Set definitions to the spec

bb15974

Merge remote-tracking branch 'upstream/main' into issue_24_customer_data

ae4a43e

merged in rename from CDSC to CDS for CDS-WG3-01

2422ba8

daniel-utilityapi changed the title ~~[Specification] CDSC-WG3-01 - Customer Data~~ [Specification] CDS-WG3-01 - Customer Data May 28, 2025

daniel-roesler mentioned this pull request Oct 16, 2025

[Specification] CDS-WG3-01 - Customer Data #31

Open

daniel-roesler closed this Oct 16, 2025


		This specification was developed as part of the global effort to combat the climate crisis. Specifically, in order to scalably measure carbon emissions of organizations and calculate the impact of deploying and operating clean energy technologies, companies need an efficient means of requesting authorization for and accessing Customer data from utilities and other entities.

		There are thousands of utilities serving Customers across the world, and each have their own way of providing access to and formatting Customer data. This specification defines a way for these utilities and other entities ("Servers") to provide a standardized, structured process for external users and companies ("Clients") to access Customer data, requesting authorization from Customers if needed. By offering a standardized a Customer data access protocol, utilities and other entities can enable secure interoperability with other external systems providing climate-change fighting services such as carbon tracking, decarbonization measures, grid flexibility capabilities, and energy benchmarking.


		Listings of Aggregation objects MUST be ordered in reverse chronological order by `modified` timestamp, where the most recently updated relevant Aggregation MUST be first in each listing.

		## 11. Usage Segments API <a id="usage-segments-api" href="#usage-segments-api" class="permalink">🔗</a>


		This specification requires Servers provide a set of APIs allowing Clients to retrieve a Customer's and Server's Usage Segment objects for which they are authorized to access. These APIs are authenticated using a Bearer `access_token` [granted](/specs/cdsc-wg1-02#grants-api) that provisions access for a [scope](#authorization-scopes) that allows access to the Usage Segments API.

		### 11.1. Usage Segment Object Format <a id="usage-segment-format" href="#usage-segment-format" class="permalink">🔗</a>

Conversation

daniel-utilityapi commented Mar 28, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Timeline

Uh oh!

halliecramer1 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

halliecramer1 Apr 5, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eloifabrega Sep 12, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Temporal247 Sep 12, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

daniel-roesler commented Oct 16, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

daniel-utilityapi commented Mar 28, 2024 •

edited

Loading

halliecramer1 Apr 5, 2024 •

edited

Loading

eloifabrega Sep 12, 2024 •

edited

Loading

Temporal247 Sep 12, 2024 •

edited

Loading