DataRight+: Energy Resource Set
draft-authors-datarightplus-resource-set-energy-00
| Document | Type | Active Internet-Draft (individual) | |
|---|---|---|---|
| Author | Stuart Low | ||
| Last updated | 2024-04-01 | ||
| RFC stream | (None) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-authors-datarightplus-resource-set-energy-00
datarightplus S. Low
Internet-Draft Biza.io
Intended status: Experimental 1 April 2024
Expires: 3 October 2024
DataRight+: Energy Resource Set
draft-authors-datarightplus-resource-set-energy-00
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.
Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the
document authors. All rights reserved.
Low Expires 3 October 2024 [Page 1]
Internet-Draft DataRight+: Energy Resource Set April 2024
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document.
Table of Contents
1. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2
3. Providers . . . . . . . . . . . . . . . . . . . . . . . . . . 2
3.1. Authorisation Server . . . . . . . . . . . . . . . . . . 2
3.1.1. Authorisation Scopes . . . . . . . . . . . . . . . . 3
3.2. Resource Server . . . . . . . . . . . . . . . . . . . . . 6
3.2.1. Electricity Authority Resource Bridge . . . . . . . . 10
4. Initiators . . . . . . . . . . . . . . . . . . . . . . . . . 11
5. Electricity Authority . . . . . . . . . . . . . . . . . . . . 11
5.1. Authorisation Server . . . . . . . . . . . . . . . . . . 11
5.2. Resource Server . . . . . . . . . . . . . . . . . . . . . 11
6. Electricity Plan Website . . . . . . . . . . . . . . . . . . 12
7. Acknowledgement . . . . . . . . . . . . . . . . . . . . . . . 12
8. Normative References . . . . . . . . . . . . . . . . . . . . 13
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13
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:
Low Expires 3 October 2024 [Page 2]
Internet-Draft DataRight+: Energy Resource Set April 2024
1. Support the [RFC6749] scope parameter with possible values
outlined within Authorisation Scopes (#name-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:
+==============================================+==================+
| 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 |
Low Expires 3 October 2024 [Page 3]
Internet-Draft DataRight+: Energy Resource Set April 2024
| | 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; |
+----------------------------------------------+------------------+
Low Expires 3 October 2024 [Page 4]
Internet-Draft DataRight+: Energy Resource Set April 2024
| 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; |
+----------------------------------------------+------------------+
Table 1
3.1.1.1. Overlapping Scope Optimisation
Alternative Data Cluster Language SHALL be used when pairs of scope
value are used as follows:
Low Expires 3 October 2024 [Page 5]
Internet-Draft DataRight+: Energy Resource Set April 2024
+==============================================+==================+
| 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 | *Electricity |
| and | connection and |
| | meter* |
+----------------------------------------------+------------------+
| energy:electricity.servicepoints.detail:read | National Meter |
| | Identifier |
| | (NMI); |
+----------------------------------------------+------------------+
| | Supply address; |
+----------------------------------------------+------------------+
| | Customer type; |
+----------------------------------------------+------------------+
| | Connection point |
| | details; |
+----------------------------------------------+------------------+
| | Meter details; |
+----------------------------------------------+------------------+
| | Associated |
| | service |
| | providers; |
+----------------------------------------------+------------------+
Table 2
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:
Low Expires 3 October 2024 [Page 6]
Internet-Draft DataRight+: Energy Resource Set April 2024
+==========================+===========+
| Resource Server Endpoint | Valid x-v |
+==========================+===========+
| GET /energy/accounts | 2 |
+--------------------------+-----------+
Table 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.detail:read scope value:
+==================================+===========+
| Resource Server Endpoint | Valid x-v |
+==================================+===========+
| GET /energy/accounts/{accountId} | 2, 3 |
+----------------------------------+-----------+
Table 4
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:
+==============================================+===========+
| Resource Server Endpoint | Valid x-v |
+==============================================+===========+
| GET /energy/accounts/{accountId}/concessions | 1 |
+----------------------------------------------+-----------+
Table 5
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:
+===================================================+===========+
| Resource Server Endpoint | Valid x-v |
+===================================================+===========+
| GET /energy/accounts/{accountId}/payment-schedule | 1 |
+---------------------------------------------------+-----------+
Table 6
Low Expires 3 October 2024 [Page 7]
Internet-Draft DataRight+: Energy Resource Set April 2024
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:
+===========================================+===========+
| 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 |
+-------------------------------------------+-----------+
Table 7
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:
+=========================================+===========+
| Resource Server Endpoint | Valid x-v |
+=========================================+===========+
| GET /energy/electricity/ | 1 |
| servicepoints/{servicePointId}/usage | |
+-----------------------------------------+-----------+
| GET /energy/electricity/servicepoints/ | 1 |
| usage | |
+-----------------------------------------+-----------+
| POST /energy/electricity/servicepoints/ | 1 |
| usage | |
+-----------------------------------------+-----------+
Table 8
Low Expires 3 October 2024 [Page 8]
Internet-Draft DataRight+: Energy Resource Set April 2024
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:
+=======================================+===========+
| Resource Server Endpoint | Valid x-v |
+=======================================+===========+
| GET /energy/electricity/servicepoints | 1 |
+---------------------------------------+-----------+
Table 9
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:
+================================+===========+
| Resource Server Endpoint | Valid x-v |
+================================+===========+
| GET /energy/electricity/ | 1 |
| servicepoints/{servicePointId} | |
+--------------------------------+-----------+
Table 10
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:
+============================================+===========+
| Resource Server Endpoint | Valid x-v |
+============================================+===========+
| GET /energy/electricity/servicepoints/der | 1 |
+--------------------------------------------+-----------+
| POST /energy/electricity/servicepoints/der | 1 |
+--------------------------------------------+-----------+
Table 11
In addition, the Provider MAY deliver the following unauthenticated
and generally available endpoints, in accordance with
[DATARIGHTPLUS-REDOCLY-ID1]:
Low Expires 3 October 2024 [Page 9]
Internet-Draft DataRight+: Energy Resource Set April 2024
+============================+=====+
| Resource Server Endpoint | x-v |
+============================+=====+
| GET /energy/plans | 1 |
+----------------------------+-----+
| GET /energy/plans/{planId} | 1 |
+----------------------------+-----+
Table 12
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:
+====================================+============================================+
|Provider Resource Server Endpoint |Electricity Authority Resource Server |
| |Endpoint |
+====================================+============================================+
|GET /energy/electricity/ |GET /secondary/energy/electricity/ |
|servicepoints/{servicePointId}/usage|servicepoints/{servicePointId}/usage |
+------------------------------------+--------------------------------------------+
|GET |GET |
|/energy/electricity/servicepoints/ |/secondary/energy/electricity/servicepoints/|
|usage |usage |
+------------------------------------+--------------------------------------------+
|POST |POST |
|/energy/electricity/servicepoints/ |/secondary/energy/electricity/servicepoints/|
|usage |usage |
+------------------------------------+--------------------------------------------+
|GET /energy/electricity/ |GET /secondary/energy/electricity/ |
|servicepoints |servicepoints |
+------------------------------------+--------------------------------------------+
|GET /energy/electricity/ |GET /secondary/energy/electricity/ |
|servicepoints/{servicePointId} |servicepoints/{servicePointId} |
+------------------------------------+--------------------------------------------+
|GET |GET |
|/energy/electricity/servicepoints/ |/secondary/energy/electricity/servicepoints/|
|der |der |
+------------------------------------+--------------------------------------------+
|POST |POST |
|/energy/electricity/servicepoints/ |/secondary/energy/electricity/servicepoints/|
|der |der |
+------------------------------------+--------------------------------------------+
Table 13
Low Expires 3 October 2024 [Page 10]
Internet-Draft DataRight+: Energy Resource Set April 2024
_Note:_ Refer to the Provider Resource Server (#resource-server) and
Electricity Authority Resource Server (#resource-server-1) 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
(#name-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]:
Low Expires 3 October 2024 [Page 11]
Internet-Draft DataRight+: Energy Resource Set April 2024
+===================================================+===========+
| Resource Server Endpoint | Valid x-v |
+===================================================+===========+
| GET /secondary/energy/electricity/ | 1 |
| servicepoints/{nationalMeteringId}/usage | |
+---------------------------------------------------+-----------+
| POST /secondary/energy/electricity/servicepoints/ | 1 |
| usage | |
+---------------------------------------------------+-----------+
| POST /secondary/energy/electricity/servicepoints | 1 |
+---------------------------------------------------+-----------+
| GET /secondary/energy/electricity/ | 1 |
| servicepoints/{nationalMeteringId} | |
+---------------------------------------------------+-----------+
| GET /secondary/energy/electricity/ | 1 |
| servicepoints/{nationalMeteringId}/der | |
+---------------------------------------------------+-----------+
| POST /secondary/energy/electricity/servicepoints | 1 |
+---------------------------------------------------+-----------+
Table 14
6. Electricity Plan Website
The Electricity Plan Website SHALL deliver the following
unauthenticated and generally available endpoints, in accordance with
[DATARIGHTPLUS-REDOCLY-ID1]:
+============================+===========+
| Resource Server Endpoint | Valid x-v |
+============================+===========+
| GET /energy/plans | 1 |
+----------------------------+-----------+
| GET /energy/plans/{planId} | 1 |
+----------------------------+-----------+
Table 15
7. Acknowledgement
The following people contributed to this document:
* Stuart Low (Biza.io) - Editor
We acknowledge the contribution to the [CDS] of the following
individuals:
Low Expires 3 October 2024 [Page 12]
Internet-Draft DataRight+: Energy Resource Set April 2024
* James Bligh (Data Standards Body) - Lead Architect for the
Consumer Data Right
* Mark Verstege (Data Standards Body) - Lead Architect, Banking &
Information Security for the Consumer Data Right
* Ivan Hosgood (formerly Data Standards Body & ACCC) - Solutions
Architect
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, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework",
October 2012,
<https://datatracker.ietf.org/doc/html/rfc6749>.
Author's Address
Stuart Low
Biza.io
Email: stuart@biza.io
Low Expires 3 October 2024 [Page 13]