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. The time zone cannot be omitted. 

Time value unavailable for DateTimeString type field

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

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