Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Energy transaction fields should be conditional #677

Open
nils-work opened this issue Nov 17, 2024 · 1 comment
Open

Energy transaction fields should be conditional #677

nils-work opened this issue Nov 17, 2024 · 1 comment
Labels
Documentation Improvements, additions or queries related to documentation Energy Non-breaking change A change that is not expected to result in a new endpoint version. Schema Issues related to schema.

Comments

@nils-work
Copy link
Member

Description

The demand and otherCharges fields in EnergyBillingTransactionV3 are currently marked as 'optional', but should be 'conditional'.
image

Intention and Value of Change

Align the requirements to support the intended schema.

Area Affected

Energy APIs: EnergyBillingTransactionV3.

Change Proposed

Change the 'optional' fields to 'conditional'.

@mattyp
Copy link

mattyp commented Feb 11, 2025

As part of the working group's action items for MI22 (ConsumerDataStandardsAustralia/standards#364), I support this proposal and would urge considering this proposed change from optional to conditional as non-breaking because:

  • The field behaviour isn't actually changing; these fields are already effectively conditional in practice. The demand field is mandatory when transactionUType equals demand, and otherCharges is mandatory when transactionUType equals otherCharges. This was already documented in the description field, so existing implementations following the documentation would already be treating these fields as conditional rather than purely optional.

  • The current schema already contains explicit conditional statements in the descriptions, which aligns with the formal definition requiring that conditional fields "MUST have an associated conditional statement." The current optional designation is technically incorrect since these fields don't match the definition of optional fields that "MAY be present but this is not guaranteed."

  • This change simply aligns the formal schema requirements with the existing behavioural requirements that were already specified in the field descriptions. No implementation properly following the existing documentation would need to change their code, as they would already be handling these fields according to their conditional nature.

In fact, this change could be viewed as a documentation improvement that reduces potential confusion by making the requirements more explicit and consistent across all specification elements. It helps prevent future implementations from misinterpreting these fields as purely optional when they have always had conditional requirements based on the transactionUType value.

@nils-work nils-work added Documentation Improvements, additions or queries related to documentation Schema Issues related to schema. Non-breaking change A change that is not expected to result in a new endpoint version. labels Feb 13, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation Improvements, additions or queries related to documentation Energy Non-breaking change A change that is not expected to result in a new endpoint version. Schema Issues related to schema.
Projects
Status: Iteration Candidates
Development

No branches or pull requests

2 participants