Modify Energy concessions structure to allow non-fixed (e.g. daily, monthly etc.) concessions

[CDR-API-Stream]

Description

Energy concessions can be fixed (based on fixed % or frequency such as daily, monthly or annually) or derived (based on some calculation, for e.g service to property charge concession. The energy concession schema currently only caters for fixed concessions.

Area Affected

Energy Concession API

Change Proposed

The change request is being proposed to modify the schema to accommodate non-fixed concession. Pptions will be consulted on during the maintenance iteration.

[CDR-API-Stream]

Background:

The current energy concession endpoint allows representation of concessions that are applied at a fixed amount or rate. However, concessions in energy can be calculated based on variable parameters (see example in the original comment) and the concession structure does not allow representation of such scenarios.

Proposed Changes

The DSB would like to propose and elicit community feedback on the following changes to the EnergyConcessionsResponse schema to allow representation of concessions that are calculated based on variable parameters:

"concessions": [
  {
    "type" : ["FIXED_AMOUNT", "FIXED_PERCENTAGE" "VARIABLE"], //new attribute describing type of concession calculation
    "displayName": "string", 
    "additionalInfo": "string",
    "additionalInfoUri": "string",
    "startDate": "string",
    "endDate": "string",
    "discountFrequency": "string", //conditional attribute for frequency at which a discount is applied - mandatory if type is FIXED_AMOUNT or FIXED_PERCENTAGE. Formatted according to ISO 8601 Durations
    "amount": "AmountString", //conditional attribute for the amount of discount for the concession- required if type is FIXED_AMOUNT
    "percentage": "RateSTring", //conditional attribute for the percentage of discount of concession - required if type is FIXED_PERCENTAGE
    "additionalValue" : "string" //conditional attribute, a generic field containing additional information relevant to variable concession- mandatory if type is VARIABLE
  }
]

Summary of proposed changes

1. Introduce a type enum which allows specifying how the concession is calculated (e.g. based on fixed or variable factors)
2. Decouple the discount period and amount/percentage applicable to a fixed concession to allow more flexibility in representation. The Duration will be formatted according to ISO 8601 Durations (excludes recurrence syntax)
3. Introduce additionalValue attribute that allows provision of additional information regarding variable concessions (for e.g. how the concession is calculated/derived)

[Kingson-EA]

Please find below our feedback on proposed structure.

Concessions are not always pre-fixed. Some of the concessions are calculated in Energy based on the usage amount and other parameters. Some examples are,
• Annual Electricity Concession: 17.5% off usage and supply charge all year, less the daily deduction of $0.0823. We assume, we are expected to map both Daily Amount and % for this concession type. Current proposed structure wouldn’t support this. Refer https://services.dffh.vic.gov.au/annual-electricity-concession for more details
• Controlled Load Concession: 13% of Controlled load Usage amount. Assuming we are expected to map type as “FIXED_PERCENTAG” type. Is the Controlled load usage interpreted as variable? Refer https://services.dffh.vic.gov.au/controlled-load-electricity-concession for more details

Thanks,
Kingson
EnergyAustralia

[CDR-API-Stream]

@Kingson-EA thank you for your feedback.

The DSB would like to propose the following three options based on assessment of the above comment:

Option 1

Keep the current proposed structure and define “fixed” to only be a fixed $ or rate concession as below

• FIXED_AMOUNT : A fixed amount of concession applied over a duration - $5/month
• FIXED_PERCENTAGE: A fixed percentage of concession applied over a duration – 5%/month
• VARIABLE: A concession that is derived based on variable parameters – 13% of usage load – variable based on usage load.

This option, whilst simplest of the three, is also the most restrictive as it doesn’t provide the ability to specify what the concession is applied to (e.g. usage charges, controlled load rates, etc.)

Option 2 (recommended)

Add an attribute that allows specifying what the concession applies to and extend the definition as below

• FIXED_AMOUNT : A fixed amount of concession applied to one or more items over a duration - $5 off controlled load charges over a month
• FIXED_PERCENTAGE: A fixed percentage of concession applied to one or more items over a duration – 5% of usage charges over a month
• VARIABLE: A concession that is derived based on combination of various parameters with complex formulas e.g. concession = [17.5% x (B – C)] – (D x 0.0823) (https://services.dffh.vic.gov.au/annual-electricity-concession)

This is recommended as it provides a simple structure to cater for most scenarios and allows specificity to what a concession applies to. The categories to what a concession applies to can also be extended by adding more ENUM values. See example below:

  "concessions": [
    {
      "type" : ["FIXED_AMOUNT", "FIXED_PERCENTAGE" "VARIABLE"], //new attribute to capture method of concession calculation
      "displayName": "string", 
      "additionalInfo": "string",
      "additionalInfoUri": "string",
      "startDate": "string",
      "endDate": "string",
      "discountFrequency": "string", //conditional attribute for frequency at which a concession is applied. Required if type is FIXED_AMOUNT or FIXED_PERCENTAGE. Formatted according to ISO 8601 Durations (excludes recurrence syntax)
      "amount": "AmountString", //conditional attribute for the amout of discount for the concession- required if type is FIXED_AMOUNT
      "percentage": "RateSTring", //conditional attribute for the percentage of discount of concession - required if type is FIXED_PERCENTAGE
      "additionalValue" : "string", //conditional attribute, a deneric field containing additional information relevant to variable concession- mandatory  if type is VARIABLE
      "appliedTo": // Array of ENUM's to specify what the concession applies to. Feedback on the enum values is welcome 
      {
        "type": "array",
        "items": {
            "type": "string",
            "enum": ["INVOICE, USAGE, SERVICE_CHARGE, CONTROLLED_LOAD"]
        }
      },
    }
  ]

Note: The "appliedTo" field is an array of ENUMs that allows specifying multiple values from the list of ENUMs in a response.

Option 3

Refine the schema to precisely articulate concessions with complex formulas. This is not preferred as it could make the schema very restrictive to future enhancements.

Feedback is welcome on the above options.

[CDR-API-Stream]

As per the action captured during MI 10 meeting on 30th March, below is the updated option 2 with the following changes:

• removed "additionalValue" attribute
• updated "additionalInfo" attribute to be conditionally mandatory if type is "VARIABLE"

Updated Option 2 (recommended)

  "concessions": [
    {
      "type" : ["FIXED_AMOUNT", "FIXED_PERCENTAGE" "VARIABLE"], //new attribute to capture method of concession calculation
      "displayName": "string", 
      "additionalInfo": "string", //conditional attribute to capture text providing more information about the variable concession - mandatory  if type is VARIABLE- mandatory if type is VARIABLE
      "additionalInfoUri": "URIString",
      "startDate": "DateString",
      "endDate": "DateString",
      "discountFrequency": "string", //conditional attribute for frequency at which a concession is applied. Required if type is FIXED_AMOUNT or FIXED_PERCENTAGE. Formatted according to ISO 8601 Durations (excludes recurrence syntax)
      "amount": "AmountString", //conditional attribute for the amount of discount for the concession- required if type is FIXED_AMOUNT
      "percentage": "RateString", //conditional attribute for the percentage of discount of concession - required if type is FIXED_PERCENTAGE
      "appliedTo": // Array of ENUM's to specify what the concession applies to. Feedback on the enum values is welcome 
      {
        "type": "array",
        "items": {
            "type": "string",
            "enum": ["INVOICE, USAGE, SERVICE_CHARGE, CONTROLLED_LOAD"]
        }
      },
    }
  ]

The above option will be updated with any feedback received within MI 10 and will be recommend to the Chair as agreed during the call.

[perlboy]

RateString needs to stop referencing interest rates.

[CDR-API-Stream]

This change was incorporated into release v1.17.0. Refer to ConsumerDataStandardsAustralia/standards#237 for further details.