Internet-Draft DataRight+: Energy Resource Set April 2024
Low Expires 3 October 2024 [Page]
Workgroup:
datarightplus
Internet-Draft:
draft-authors-datarightplus-resource-set-energy-latest
Published:
Intended Status:
Experimental
Expires:
Author:
S. Low
Biza.io

DataRight+: Energy Resource Set

Abstract

This is the resource set profile outlining the energy sector related endpoints. In addition to outlining Initiator and Provider provisions it also specifies requirements for the Energy Authority (electricity assets and usage) and Energy Plan Website (retail electricity plan information).

Notational Conventions

The keywords "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on 3 October 2024.

▲

Table of Contents

1. Scope

The scope of this document is intended to be limited to the resource server endpoints related to energy, their associated authorisation contexts, the services provided by the Energy Authority and Energy Plan Website.

2. Terminology

This specification utilises the various terms outlined within [DATARIGHTPLUS-ROSETTA].

3. Providers

Providers which manage energy sector information are expected to deliver a number of resource server end points.

3.1. Authorisation Server

In addition to other provisions incorporated within the relevant ecosystem set, the Provider authorisation server SHALL:

  1. Support the [RFC6749] scope parameter with possible values outlined within Authorisation Scopes;

3.1.1. Authorisation Scopes

The Provider authorisation server SHALL utilise the following Data Set Language when seeking Consumer authorisation from a User for specific scope values:

Table 1
scope value Data Set Language
energy:accounts.basic:read Accounts and plans
Account and plan information;
energy:accounts.detail:read Account and plan details
Account type;
Fees, features, rates, and discounts;
Additional account users;
energy:accounts.concessions:read Concessions and assistance
Concession type;
Concession information;
energy:accounts.paymentschedule:read Payment preferences
Payment and billing frequency;
Any scheduled payment details;
energy:billing:read Billing payments and history
Account balance;
Payment method;
Payment status;
Charges, discounts, credits;
Billing date;
Usage for billing period;
Payment date;
Invoice number;
energy:electricity.servicepoints.basic:read Electricity connection
National Meter Identifier (NMI);
Customer type;
Connection point details;
energy:electricity.servicepoints.detail:read Electricity meter
Supply address;
Meter details;
Associated service providers;
energy:electricity.der:read Energy generation and storage
Generation information;
Generation or storage device type;
Device characteristics;
Devices that can operate without the grid;
Energy conversion information;
energy:electricity.usage:read Electricity usage
Usage;
Meter details;
3.1.1.1. Overlapping Scope Optimisation

Alternative Data Cluster Language SHALL be used when pairs of scope value are used as follows:

Table 2
scope pairing Data Set Language
energy:accounts.basic:read and Account and plan details
energy:accounts.detail:read Account and plan information;
Account type;
Fees, features, rates, and discounts;
Additional account users;
energy:electricity.servicepoints.basic:read and Electricity connection and meter
energy:electricity.servicepoints.detail:read National Meter Identifier (NMI);
Supply address;
Customer type;
Connection point details;
Meter details;
Associated service providers;

3.2. Resource Server

The Provider SHALL make available, as described further in [DATARIGHTPLUS-REDOCLY-ID1] endpoints, the following endpoints where the token is granted the energy:accounts.basic:read scope value:

Table 3
Resource Server Endpoint Valid x-v
GET /energy/accounts 2

The Provider SHALL make available, as described further in [DATARIGHTPLUS-REDOCLY-ID1] endpoints, the following endpoints where the token is granted the energy:accounts.detail:read scope value:

Table 4
Resource Server Endpoint Valid x-v
GET /energy/accounts/{accountId} 2, 3

The Provider SHALL make available, as described further in [DATARIGHTPLUS-REDOCLY-ID1] endpoints, the following endpoints where the token is granted the energy:accounts.concessions:read scope value:

Table 5
Resource Server Endpoint Valid x-v
GET /energy/accounts/{accountId}/concessions 1

The Provider SHALL make available, as described further in [DATARIGHTPLUS-REDOCLY-ID1] endpoints, the following endpoints where the token is granted the energy:accounts.paymentschedule:read scope value:

Table 6
Resource Server Endpoint Valid x-v
GET /energy/accounts/{accountId}/payment-schedule 1

The Provider SHALL make available, as described further in [DATARIGHTPLUS-REDOCLY-ID1] endpoints, the following endpoints where the token is granted the energy:billing:read scope value:

Table 7
Resource Server Endpoint Valid x-v
GET /energy/accounts/balances 1
GET /energy/accounts/{accountId}/balance 1
POST /banking/accounts/balances 1
GET /energy/accounts/{accountId}/invoices 1
GET /energy/accounts/invoices 1
POST /energy/accounts/invoices 1
GET /energy/accounts/{accountId}/billing 1
GET /energy/accounts/billing 1
POST /energy/accounts/billing 1

The Provider SHALL make available, as described further in [DATARIGHTPLUS-REDOCLY-ID1] endpoints, the following endpoints where the token is granted the energy:electricity.usage:read scope value:

Table 8
Resource Server Endpoint Valid x-v
GET /energy/electricity/servicepoints/{servicePointId}/usage 1
GET /energy/electricity/servicepoints/usage 1
POST /energy/electricity/servicepoints/usage 1

The Provider SHALL make available, as described further in [DATARIGHTPLUS-REDOCLY-ID1] endpoints, the following endpoints where the token is granted the energy:electricity.servicepoints.basic:read scope value:

Table 9
Resource Server Endpoint Valid x-v
GET /energy/electricity/servicepoints 1

The Provider SHALL make available, as described further in [DATARIGHTPLUS-REDOCLY-ID1] endpoints, the following endpoints where the token is granted the energy:electricity.servicepoints.detail:read scope value:

Table 10
Resource Server Endpoint Valid x-v
GET /energy/electricity/servicepoints/{servicePointId} 1

The Provider SHALL make available, as described further in [DATARIGHTPLUS-REDOCLY-ID1] endpoints, the following endpoints where the token is granted the energy:electricity.der.basic:read scope value:

Table 11
Resource Server Endpoint Valid x-v
GET /energy/electricity/servicepoints/der 1
POST /energy/electricity/servicepoints/der 1

In addition, the Provider MAY deliver the following unauthenticated and generally available endpoints, in accordance with [DATARIGHTPLUS-REDOCLY-ID1]:

Table 12
Resource Server Endpoint x-v
GET /energy/plans 1
GET /energy/plans/{planId} 1

3.2.1. Electricity Authority Resource Bridge

In order to deliver information requested by the Initiator the Provider SHALL provide a back-to-back relay of resource server requests between the Provider and Electricity Authority as follows:

Table 13
Provider Resource Server Endpoint Electricity Authority Resource Server Endpoint
GET /energy/electricity/servicepoints/{servicePointId}/usage GET /secondary/energy/electricity/servicepoints/{servicePointId}/usage
GET /energy/electricity/servicepoints/usage GET /secondary/energy/electricity/servicepoints/usage
POST /energy/electricity/servicepoints/usage POST /secondary/energy/electricity/servicepoints/usage
GET /energy/electricity/servicepoints GET /secondary/energy/electricity/servicepoints
GET /energy/electricity/servicepoints/{servicePointId} GET /secondary/energy/electricity/servicepoints/{servicePointId}
GET /energy/electricity/servicepoints/der GET /secondary/energy/electricity/servicepoints/der
POST /energy/electricity/servicepoints/der POST /secondary/energy/electricity/servicepoints/der

Note: Refer to the Provider Resource Server and Electricity Authority Resource Server sections for the appropriate API mappings.

4. Initiators

Initiators SHALL describe the requested scope values using the same Data Set Language as Providers, as outlined in Authorisation Scopes.

5. Electricity Authority

The Electricity Authority SHALL deliver the electricity asset and usage information to the Provider.

5.1. Authorisation Server

The Electricity Authority SHALL authorise Providers using existing information security protocols. The specific details of this are outside the scope of this document.

5.2. Resource Server

The Electricity Authority SHALL make the following restricted endpoints available to Providers, using existing authentication and authorisation channels, and in accordance with [DATARIGHTPLUS-REDOCLY-ID1]:

Table 14
Resource Server Endpoint Valid x-v
GET /secondary/energy/electricity/servicepoints/{nationalMeteringId}/usage 1
POST /secondary/energy/electricity/servicepoints/usage 1
POST /secondary/energy/electricity/servicepoints 1
GET /secondary/energy/electricity/servicepoints/{nationalMeteringId} 1
GET /secondary/energy/electricity/servicepoints/{nationalMeteringId}/der 1
POST /secondary/energy/electricity/servicepoints 1

6. Electricity Plan Website

The Electricity Plan Website SHALL deliver the following unauthenticated and generally available endpoints, in accordance with [DATARIGHTPLUS-REDOCLY-ID1]:

Table 15
Resource Server Endpoint Valid x-v
GET /energy/plans 1
GET /energy/plans/{planId} 1

7. Acknowledgement

The following people contributed to this document:

We acknowledge the contribution to the [CDS] of the following individuals:

8. Normative References

[CDS]
Data Standards Body (Treasury), "Consumer Data Standards (CDS)", <https://consumerdatastandardsaustralia.github.io/standards>.
[DATARIGHTPLUS-REDOCLY-ID1]
Low, S., Kolera, B., and W. Cai, "DataRight+: Redocly (ID1)", <https://datarightplus.github.io/datarightplus-redocly/?v=ID1>.
[DATARIGHTPLUS-ROSETTA]
Low, S., "DataRight+ Rosetta Stone", <https://datarightplus.github.io/datarightplus-specs/main/datarightplus-rosetta.html>.
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC6749]
Hardt, D., "The OAuth 2.0 Authorization Framework", , <https://datatracker.ietf.org/doc/html/rfc6749>.

Author's Address

Stuart Low
Biza.io