Data formats - schemas

Introduction

Data for REST requests, responses and other purposes is in JSON (JavaScript Object Notation) format. The schemas describe data formats for requests and responses. 

General requirements for field names and values are described in CDS, Payload Conventions.

Since CDS version 1.13.0, schemas are displayed in the section with their corresponding APIs. 

See:

• DCR API Schemas
• Registry API Schemas
• Common API Schemas
• Admin API Schemas

Some complex schemas have many parts, some of which require their own schema. For example, the BankingProductDetailV3 schema contains arrays of BankingProductBundles, BankingProductFeatures, and other components.

Different participants may have widely varying ways in which they describe their products and services and present them to customers. The Consumer Data Standards (CDS) attempt to cover common aspects of products and services. 

Participants may find that the schemas do not cover all the data they wish to provide, or alternatively that the schema requires data they cannot provide. 

Information not covered by the standards - additionalInfo and additionalInfoUri

Where the standards do not cover some area, it is often up to the participant to determine how to use the data format to present the required information. In many schemas there are additionalInfo and additionalInfoUri fields. These provide flexibility to cover issues and details not already represented by existing data fields. The additionalInfo field allows participants to add further text information. The additionalInfoUri field allows participants to provide a link to further information.

Required fields: Mandatory, Optional or Conditional

In the CDS Schemas,  the Required column indicates whether the value of a field must be provided or can be omitted. The overall intent of the CDR is that data must be supplied when available. See CDS, Payload Conventions.

• Mandatory: a mandatory field must be provided. If the data for the field is unavailable, and the field is omitted, the result is non-compliant.
• Optional: an optional field can be omitted only if the data for the field is unavailable. If the data is available it must be supplied. If data is available but is not supplied, the result is non-compliant.
• Conditional: whether a field is required depends on values in other fields. If the requirement conditions are met, the field must be supplied. The field description indicates what conditions apply. 

Fields for which data is unavailable

If data is unavailable for an Optional field, there is a choice between either setting the field to null, or omitting the field. Filling the field with arbitrary data, or an out of range value is not appropriate. 

A JSONnullvalue indicates that the value is not held and no assumption can be made about the value. Omitting the field from the payload is equivalent to including the field with a JSONnullvalue.

For string fields, an empty string and a null value are not equivalent. An empty string ("") indicates that the value is known and is an empty string. This might occur if an empty string was explicitly entered as the value for some field.

If the Data Holder (DH) system holds an empty string corresponding to a schema field, it is up to the DH to determine whether this indicates the value is unknown. An empty string should be returned in the response only if the value is known to be an empty string. 

For array fields, an empty array indicates that no values are available to populate the array. When a request requires a response with an array of values, and there are no values to provide in the array, an empty array should be returned. 

Responses with omitted or null optional fields, or with empty arrays, may be associated with a successful API call. In cases where no data requested is available, it is at the discretion of the DH to determine whether the appropriate response is a 200 Ok status code or a 400 Bad Request error status code.

For example, if an ADR calls Get Scheduled Payments for Account and there are no scheduled payments, the DH may respond with status code 200 Ok and an empty array in the ResponseBankingScheduledPaymentsList schema response.

If data is unavailable for a Mandatory field, it is not acceptable to return an empty string, unless otherwise indicated in the field description. 

For some mandatory fields, an empty string is an acceptable value.

For example, in the  BankingTransaction schema, in response to the Get Transactions For Account API, some transactions may have no value for the BankingTransaction reference field. Although the reference field is mandatory, its value can be an empty string. This is noted in the CDS field description.

If data marked as mandatory is likely to be unavailable, participants are encouraged to submit a change request suggesting changes to the standards.

Empty or Null Fields

The CDS payload conventions section discusses this issue. See Mandatory/Optional Fields and Empty/Null Fields.

An empty string and a null value are not considered equivalent. See CDS Guide, Data formats - schemas, Fields for which data is unavailable.

If in an optional field the value is not known, then the field should be  null or absent.

UType

UType fields are described in CDS, Payload Conventions, Object conventions. In some schemas, a set of data can be represented by objects of different types. In the schema, the specific object type is indicated by a field with suffix UType. Many examples are provided in the CDS examples column. 
For an example in the CDS Guide, see Payees, BankingScheduledPaymentToV2, and the BankingScheduledPaymentToV2 schema.

DateTimeString

The DateTimeString field type is formatted according to RFC3339 date-time. A full time format is required. This applies to transaction dates and many other date-time fields.

Time Zone

RCF3339 requires time zone to be specified as an offset relative to UTC.

For example:

• Australian Eastern Standard Time (AEST) is offset by +10 hours.
• Australian Eastern Daylight Time (AEDT) is offset by +11 hours.

The time zone component cannot be omitted from the value.

Time value unavailable for DateTimeString type field

The time and time zone components cannot be omitted from the DateTimeString field type.

If a Data Holder is unable to provide the time component for any DateTimeString field, an indicative or default time may be specified for that field, such as T04:00:00+10:00 (which represents 4AM in the '+10' time zone).

Where a default time component is specified, that same default value does not need to be specified for all DateTimeString fields. Data Holders should ensure that any indicative or default time and time zone represents a close approximation of the moment that the field should represent in the context of the associated schema. This may also require adjusting the specified time zone to accommodate daylight saving changes in the locale of the Data Holder to ensure any default provided would be translated in alignment with any actual times being specified for other related fields, if this would affect the associated date or interpretation of the data by more than the daylight saving time difference.

Application of indicative or default times in Banking transactions where actual time values are unavailable

The BankingTransaction schema incorporated into the Get Transactions For Account and Get Transaction Detail endpoints includes the following three related DateTimeString fields.

Where one or more of these fields requires an indicative or default time to be specified, the following convention and values may be applied to determine appropriate values that will maintain a typical transaction event sequence that use cases may expect:

executionDateTime <= valueDateTime <= postingDateTime

1. executionDateTime
   The time component may be specified as 00:00:00* (the first moment, or an indicative time on the date* the transaction was first executed/initiated, to ensure it is first in the sequence).
2. valueDateTime
   The time component should be specified as any time* equal to or greater than the executionDateTime, and less than or equal to the postingDateTime. As a general rule, it may be practical to specify 00:00:00* (or the same time as the indicative time used for executionDateTime) to indicate that the available balance was updated as soon as the transaction was received by the Data Holder, i.e., the executionDateTime, if applicable for the transaction type.
3. postingDateTime
   The time component should be specified as -
   1. any indicative time* equal to or greater than the valueDateTime. For example, where posting is expected to occur after a typical amount of time after the valueDateTime, or
   2. a fixed time aligned to the standard posting/settlement processes of the data holder, for example, for transactions that aren't posted/settled on the same day:
      1. 00:00:00* - representing the first moment of the day after the valueDateTime, or
      2. 02:00:00* - representing 2AM, for processing that typically occurs at 2AM of the next day.

* All times should be specified in the time zone that the Data Holder would normally apply to any other transactions and reflect the experience of other channels where applicable, noting that the context of CDR data and the level of detail it provides may differ to what is presented in other channels.

For example:

• A data holder headquartered in Sydney, disclosing transactions according to their Sydney-based processing times in the +10 time zone may present their indicative 'midnight' processing as 00:00:00+10:00, and '2AM' as 02:00:00+10:00 (both in the next day in the case of postingDateTime, if applicable). For a transaction on 1 May 2025 without source time values for any of these fields, an alignment to midnight may appear as:
  • "executionDateTime": "2025-05-01T00:00:00+10:00" (first moment of 1 May in +10/AEST)
  • "valueDateTime: "2025-05-01T00:00:00+10:00" (same as executionDateTime, if indicative)
  • "postingDateTime": "2025-05-02T00:00:00+10:00" (first moment of 2 May in +10/AEST, where being settled the next day)
• Another data holder in Melbourne, also operating at +10, but following a convention of disclosing transaction time detail in the UTC time zone, may present their 'midnight' as 14:00:00Z and '2AM' as 16:00:00Z, while still ensuring the date aligns to the correct day (typically next day for postingDateTime) according to the local processing procedures of the data holder (+10 in this case), and the expected sequence of transaction events.
  For example, the same transaction as above, also representing processes at midnight may appear as:
  • "executionDateTime": "2025-04-30T14:00:00Z" (first moment of 1 May in +10/AEST, which is 2PM on 30 April in UTC)
  • "valueDateTime": "2025-04-30T14:00:00Z" (same as executionDateTime, if indicative)
  • "postingDateTime": "2025-05-01T14:00:00Z" (first moment of 2 May in +10/AEST, which is 2PM on 1 May in UTC, assuming the transaction settled the day after the executionDateTime).

According to the above convention and examples, it should not be expected for a data holder in Sydney or Melbourne to specify a default time component of T00:00:00Z (midnight at UTC) for postingDateTime, unless transactions are being settled at 10AM local Standard Time.

See CDS, Common Field Types.

Data conventions

A number of data and schema related conventions have been proposed. These include:

• Entities that cannot be represented using standard schemata
• Excluding VARIABLE fees where they cannot be represented accurately
• Representing VARIABLE fee in BankingProductFee

Check the conventions page for a full list.

Subsections

---

Article version history

• 26 August 2025
  • Updated the "Time value unavailable for DateTimeString type field" section. For details refer to #173 - Behaviour where posted transactions only have an associated date.
  • Original text:

    • If the Data Holder is unable to provide the time value for the field, the DH can supply a suitable time value of their choosing, such as 00:00:00. The time value cannot be omitted. 

      For example, a DH unable to supply a time value could choose to supply 00:00:00, and the full DateTimeString value, in AEST, might be: 2024-07-30T00:00:00+10:00