Allow lists terms and conditions URIs in additionalInformation for the Product APIs

[WestpacOpenBanking]

Description

It’s feasible that a product may have multiple terms and condition documents (for example for the account and the card associated with that account).

Area Affected

BankingProductV3 object definition

Change Proposed

Add an additionalTermsUris field containing a list of URIString objects. Update the termsURI field description to signify that it is for primary terms and conditions document applicable to the product. This approach ensures that the change is non-breaking for data recipients. Consider making a similar change for other provided URIs (for example the fees and charges URI).

[CDR-API-Stream]

This issue was discussed in the Maintenance Iteration call.

The discussion identified the following requirements and options.

Requirements

• Products can have one or more (list) Terms & Conditions URIs (e.g. travel insurance T&Cs for a credit card)
• Product references should denote which document is the primary or secondary document for a given document type is important
  *Products may also have other document types with one or more documents (e.g., bundleUri)

Options

Option 1: Add new AdditionalTermsUri list

This option would add a new field which supports a list of additional (secondary) terms and conditions URIs.

/***********************
 * Proposal (Option 1):  
 ***********************/

    "BankingProductV4_additionalInformationV2": {
      "type": "object",
      "properties": {
        "overviewUri": {
          "type": "string",
          "description": "General overview of the product",
          "x-cds-type": "URIString"
        },
        "termsUri": {
          "type": "string",
          "description": "The primary terms and conditions for the product",
          "x-cds-type": "URIString"
        },
        "additionalTermsUri": {
          "type": "array",
          "description": "An array of additional terms and conditions for the product, if applicable",
          "items": {
            "type": "string",
            "x-cds-type": "URIString"
          }
        },
        /* ... */
      },
      "description": "Object that contains links to additional information on specific topics"
    }

/***********************
 * Example (Option 1):  
 ***********************/

"additionalInformation": {
    "overviewUri": "string",
    "termsUri": "string",
    "eligibilityUri": "string",
    "feesAndPricingUri": "string",
    "bundleUri": "string",
    "additionalTermsUri": [
      "https://bank.com.au/terms-and-conditions/travel-insurance-terms-and-conditions.pdf",
      "https://bank.com.au/terms-and-conditions/loyalty-rewards-terms-and-conditions.pdf"
    ]
}

Option 2: Support an array of additional information URIs.

/***********************
 * Proposal (Option 2):  
 ***********************/

    "BankingProductV4_additionalInformationV2": {
      "type": "array",
      "description": "Object that contains links to additional information on specific topics",
      "items": {
        "$ref": "#/definitions/BankingProductV4_additionalInformationV2_Uri"
      }
    },

    "BankingProductV4_additionalInformationV2_Uri": {
      "type": "object",
      "required": ["type", "uri"],
      "properties": {
        "isPrimaryUri": {
          "type": "boolean",
          "description": "Indicates whether the URI is the primary additional information document for the given type. Defaults to `true`. One one primary document URI for each document `type` is allowed.",
          "x-cds-type": "Boolean"
        },
        "type": {
          "type": "string",
          "description": "The type of additonal information document described",
          "enum": [
            "OVERVIEW", /* General overview of the product */
            "TERMS_AND_CONDITIONS", /* Terms and conditions for the product */
            "FEES_AND_RATES",
            "ELIGIBILITY",
            "BUNDLE"
          ]
        },
        "description": {
          "type": "string",
          "description": "Display text providing more information on the document"
        },
        "uri": {
          "type": "array",
          "description": "The URI describing the additional information",
          "items": {
            "type": "string",
            "x-cds-type": "URIString"
          }
        }
      }
    }

/***********************
 * Example (Option 2):  
 ***********************/

"additionalInformation": [
  {
    "isPrimaryUri": true,
    "type": "OVERVIEW",
    "uri": "https://bank.com.au/products/Travel-Credit-Card/"
  },
  {
    "additionalInfoType": "FEES_AND_RATES",
    "additionalInfoUri": "https://bank.com.au/products/Travel-Credit-Card/Fees.html"
  },
  {
    "type": "ELIGIBILITY",
    "uri": "https://bank.com.au/products/Travel-Credit-Card/Eligibility"
  },
  {
    "type": "TERMS_AND_CONDITIONS",
    "uri": "https://bank.com.au/products/Travel-Credit-Card/primary-terms-and-conditions.pdf"
  },
  {
    "type": "TERMS_AND_CONDITIONS",
    "description": "Terms and conditions for complementary travel insurance when the Platinum Advantage card is used to book flights and accommodation.",
    "isPrimaryUri": false,
    "uri": "https://bank.com.au/terms-and-conditions/travel-insurance-terms-and-conditions.pdf"
  },
  {
    "type": "TERMS_AND_CONDITIONS",
    "description": "Terms and conditions for the Platinum Advantage loyalty rewards scheme.",
    "isPrimaryUri": false,
    "uri": "https://bank.com.au/terms-and-conditions/loyalty-rewards-terms-and-conditions.pdf"
  }
}

Option 3: Add new Additional...Uri list

This option would add a new field for each document type which supports a list of additional (secondary) document URIs.

/***********************
 * Proposal (Option 3):  
 ***********************/

    "BankingProductV4_additionalInformationV2": {
      "type": "object",
      "properties": {
        "overviewUri": {
          "type": "string",
          "description": "General overview of the product",
          "x-cds-type": "URIString"
        },
        "termsUri": {
          "type": "string",
          "description": "The primary terms and conditions for the product",
          "x-cds-type": "URIString"
        },
        "additionalOverviewUri": {
          "type": "array",
          "description": "An array of additional general overviews for the product or features of the product, if applicable",
          "items": {
            "type": "string",
            "x-cds-type": "URIString"
          }
        },
        "additionalTermsUri": {
          "type": "array",
          "description": "An array of additional terms and conditions for the product, if applicable",
          "items": {
            "type": "string",
            "x-cds-type": "URIString"
          }
        },
       "additionalEligibilityUri": {
          "type": "array",
          "description": "An array of additional eligibility rules and criteria for the product, if applicable",
          "items": {
            "type": "string",
            "x-cds-type": "URIString"
          }
        },
        "additionalFeesAndPricingUri": {
          "type": "array",
          "description": "An array of additional fees, pricing, discounts, exemptions and bonuses for the product, if applicable",
          "items": {
            "type": "string",
            "x-cds-type": "URIString"
          }
        },
        /* ... */
      },
      "additionalBundleUri": {
          "type": "array",
          "description": "An array of additional bundles for the product, if applicable",
          "items": {
            "type": "string",
            "x-cds-type": "URIString"
          }
        },
        /* ... */
      },
      "description": "Object that contains links to additional information on specific topics"
    }

/***********************
 * Example (Option 3):  
 ***********************/

"additionalInformation": {
    "overviewUri": "string",
    "termsUri": "string",
    "eligibilityUri": "string",
    "feesAndPricingUri": "string",
    "bundleUri": "string",
    "additionalOverviewUri": [
      "https://bank.com.au/overview/elevate-travel-insurance-overview.pdf",
      "https://bank.com.au/overview/BankSavers-loyalty-rewards-overview.pdf"
    ],
    "additionalTermsUri": [
      "https://bank.com.au/terms-and-conditions/travel-insurance-terms-and-conditions.pdf",
      "https://bank.com.au/terms-and-conditions/loyalty-rewards-terms-and-conditions.pdf"
    ],
    "additionalEligibilityUri": [
      "https://bank.com.au/eligibility/travel-insurance-eligibility.pdf",
      "https://bank.com.au/eligibility/loyalty-rewards-eligibility.pdf"
    ],
    "additionalFeesAndPricingUri": [
      "https://bank.com.au/terms-and-conditions/travel-insurance-fees-and-pricing.pdf",
      "https://bank.com.au/terms-and-conditions/loyalty-rewards-terms-and-conditions.pdf"
    ],
    "additionalBundleUri": [
      "https://bank.com.au/terms-and-conditions/family-home-savers-bundle-info.pdf",
      "https://bank.com.au/terms-and-conditions/business-package-bundle-info.pdf"
    ]
}

Implementation Considerations

Option 1:

• No breaking change to ADRs.
• No change to the endpoint versioning
• Less future-proof or flexible
• Only addresses additional terms and conditions. Similar pattern could be adopted for secondary overview/bundle/entitlements/fees & rates document URIs

Option 2:

• Creates breaking changes for ADRs and DHs
• Creates a v4 for PRD endpoints
• Future-proof and extensible: if new document types are added, this is easy to extend

Option 3:

• No breaking change to ADRs.
• No change to the endpoint versioning
• Less future-proof or flexible
• Deals with all additional information

[commbankoss]

CBA is supportive of Option 3 to add additional flexibility for multiple documents for each document type whilst ensuring a non-breaking change for CDR participants.

[CDR-API-Stream]

Based on feedback in the 03/11 maintenance iteration call, the proposal has been revised. Option 3 was supported with changes to allow the additional information proposed in Option 2. This would still mean the change is non-breaking and would not result in a future obligation date. Any Data Holder that has additional documents they want to present could do so at any time after the standards change is made.

Two revised options are presented for review and feedback.

Option 2b:

Adopts the non-breaking representation of existing URIs and permits a type-defined array of additional documents (type, URI and an optional description).

/***********************
 * Proposal (Option 2b):  
 ***********************/

  "BankingProductV3_additionalInformationV2": {
      "type": "object",
      "properties": {
        "overviewUri": {
          "type": "string",
          "description": "General overview of the product",
          "x-cds-type": "URIString"
        },
        "termsUri": {
          "type": "string",
          "description": "Terms and conditions for the product",
          "x-cds-type": "URIString"
        },
        "eligibilityUri": {
          "type": "string",
          "description": "Eligibility rules and criteria for the product",
          "x-cds-type": "URIString"
        },
        "feesAndPricingUri": {
          "type": "string",
          "description": "Description of fees, pricing, discounts, exemptions and bonuses for the product",
          "x-cds-type": "URIString"
        },
        "bundleUri": {
          "type": "string",
          "description": "Description of a bundle that this product can be part of",
          "x-cds-type": "URIString"
        },
        "additionalInformationUri": {
          "type": "array",
          "description": "Object that contains links to additional information on specific topics",
          "items": {
            "$ref": "#/definitions/BankingProductV3_additionalInformationV2_additionalInformationUri"
          }
        }
      },
      "description": "Object that contains links to additional information on specific topics"
    }

    "BankingProductV3_additionalInformationV2_additionalInformationUri": {
        "type": "object",
        "required": ["type", "uri"],
        "properties": {
          "type": {
            "type": "string",
            "description": "The type of additional information document described",
            "enum": [
              "OVERVIEW", /* General overview of the product */
              "TERMS_AND_CONDITIONS", /* Terms and conditions for the product */
              "FEES_AND_RATES",
              "ELIGIBILITY",
              "BUNDLE"
            ]
          },
          "description": {
            "type": "string",
            "description": "Display text providing more information on the document"
          },
          "uri": {
            "type": "array",
            "description": "The URI describing the additional information",
            "items": {
              "type": "string",
              "x-cds-type": "URIString"
            }
          }
       }
    }

/***********************
 * Example (Option 2b):  
 ***********************/

"additionalInformation": {
    "overviewUri": "string",
    "termsUri": "string",
    "eligibilityUri": "string",
    "feesAndPricingUri": "string",
    "bundleUri": "string",
    "additionalInformationUri": [
      {
        "type": "OVERVIEW",
        "uri": "https://bank.com.au/products/Travel-Credit-Card/"
      },
      {
        "additionalInfoType": "FEES_AND_RATES",
        "additionalInfoUri": "https://bank.com.au/products/Travel-Credit-Card/Fees.html"
      },
      {
        "type": "ELIGIBILITY",
        "uri": "https://bank.com.au/products/Travel-Credit-Card/Eligibility"
      },
      {
        "type": "TERMS_AND_CONDITIONS",
        "uri": "https://bank.com.au/products/Travel-Credit-Card/primary-terms-and-conditions.pdf"
      },
      {
        "type": "TERMS_AND_CONDITIONS",
        "description": "Terms and conditions for complementary travel insurance when the Platinum Advantage card is used to book flights and accommodation.",
        "uri": "https://bank.com.au/terms-and-conditions/travel-insurance-terms-and-conditions.pdf"
      },
      {
        "type": "TERMS_AND_CONDITIONS",
        "description": "Terms and conditions for the Platinum Advantage loyalty rewards scheme.",
        "uri": "https://bank.com.au/terms-and-conditions/loyalty-rewards-terms-and-conditions.pdf"
      }
    ]
}

Option 3b: Named additional document lists

In addition to option 3, this option would add a new field which supports a list of additional (secondary) terms and conditions URIs. It continues to present the additional documents in named objects rather than the type-defined enumerated array in Option 2b

/***********************
 * Proposal (Option 3b):  
 ***********************/

    "BankingProductV4_additionalInformationV2": {
      "type": "object",
      "properties": {
        "overviewUri": {
          "type": "string",
          "description": "General overview of the product",
          "x-cds-type": "URIString"
        },
        "termsUri": {
          "type": "string",
          "description": "The primary terms and conditions for the product",
          "x-cds-type": "URIString"
        },
        /***************** NEW CHANGES ****************/
        "additionalOverviewUri": {
          "type": "array",
          "description": "An array of additional general overviews for the product or features of the product, if applicable",
          "items": {
            "$ref": "#/definitions/BankingProductV3_additionalInformationV2_additionalInformationUri"
          }
        },
        "additionalTermsUri": {
          "type": "array",
          "description": "An array of additional terms and conditions for the product, if applicable",
          "items": {
            "$ref": "#/definitions/BankingProductV3_additionalInformationV2_additionalInformationUri"
          }
        },
       "additionalEligibilityUri": {
          "type": "array",
          "description": "An array of additional eligibility rules and criteria for the product, if applicable",
          "items": {
            "$ref": "#/definitions/BankingProductV3_additionalInformationV2_additionalInformationUri"
          }
        },
        "additionalFeesAndPricingUri": {
          "type": "array",
          "description": "An array of additional fees, pricing, discounts, exemptions and bonuses for the product, if applicable",
          "items": {
            "$ref": "#/definitions/BankingProductV3_additionalInformationV2_additionalInformationUri"
          }
        },
        /* ... */
      },
      "additionalBundleUri": {
          "type": "array",
          "description": "An array of additional bundles for the product, if applicable",
          "items": {
            "type": "string",
            "x-cds-type": "URIString"
          }
        },
        /* ... */
      },
      "description": "Object that contains links to additional information on specific topics"
    }

    "BankingProductV3_additionalInformationV2_additionalInformationUri": {
        "type": "object",
        "required": [uri"],
        "properties": {
          "description": {
            "type": "string",
            "description": "Display text providing more information on the document"
          },
          "uri": {
            "type": "array",
            "description": "The URI describing the additional information",
            "items": {
              "type": "string",
              "x-cds-type": "URIString"
            }
          }
       }
    }

/***********************
 * Example (Option 3b):  
 ***********************/

"additionalInformation": {
    "overviewUri": "string",
    "termsUri": "string",
    "eligibilityUri": "string",
    "feesAndPricingUri": "string",
    "bundleUri": "string",
    "additionalOverviewUri": [
      "https://bank.com.au/overview/elevate-travel-insurance-overview.pdf",
      "https://bank.com.au/overview/BankSavers-loyalty-rewards-overview.pdf"
    ],
    "additionalTermsUri": [
      {
        "description": "Terms and conditions for complementary travel insurance when the Platinum Advantage card is used to book flights and accommodation.",
        "uri": "https://bank.com.au/terms-and-conditions/travel-insurance-terms-and-conditions.pdf"
      },
      {
        "description": "Terms and conditions for the Platinum Advantage loyalty rewards scheme.",
        "uri": "https://bank.com.au/terms-and-conditions/loyalty-rewards-terms-and-conditions.pdf"
      }
    ],
    "additionalEligibilityUri": [
      {
        "uri": "https://bank.com.au/eligibility/travel-insurance-eligibility.pdf
      },
      {
        "uri": "https://bank.com.au/eligibility/loyalty-rewards-eligibility.pdf"
      }
    ],
    "additionalFeesAndPricingUri": [
      {
        "description": "Fees related to complementary insurance and claims",
        "uri": "https://bank.com.au/terms-and-conditions/travel-insurance-fees-and-pricing.pdf"
      },
      {
        "description": "Fees related to the exchange of rewards points for goods and services"
        "uri": "https://bank.com.au/terms-and-conditions/loyalty-rewards-terms-and-conditions.pdf"
      }
    ],
    "additionalBundleUri": [
      {
        "uri": "https://bank.com.au/terms-and-conditions/family-home-savers-bundle-info.pdf"
      },
      {
        "uri": "https://bank.com.au/terms-and-conditions/business-package-bundle-info.pdf"
      }
    ]
}

[WestpacOpenBanking]

Westpac recommends either option 2b or 3b, with a preference for 3b because it is simpler to use, albeit less flexible. Westpac does not recommend any option which introduces a breaking change.

[CDR-API-Stream]

This change has been staged for review: ConsumerDataStandardsAustralia/standards-staging@release/1.15.0...maintenance/402

[perlboy]

The staged change only includes a swagger update in swagger-gen which the DSB has previously stated is not an authoritative representation of the Standards and for which no functioning/documented build method is available. Consequently, please publish the resultant markdowns.

The proposed change has altered the definition from an inline object definition to a $ref. This is fine (and previously recommended but rejected by the DSB) however the object name of BankingProductV3_additionalInformationV2 is now non-compliant and likely confusing in the future if there is a BankingProductV4 for which additional information is unchanged. Suggest instead naming this object as BankingProductAdditionalInformationV2 and would expect it now to appear in the schemas list. The same applies to BankingProductV3_additionalInformationV2_additionalInformationUris although moving this back to an inline definition may be appropriate since its versioning seems bound to Additional Information.

On versioning, while it may be acceptable for an endpoint version to be unchanged overwriting the existing BankingProductV3 model definition implicitly causes issues with those attempting to use code generation (ie. most actual implementers). This has been an issue in both directions. Would suggest the DSB introduce BankingProductV4 even if it is leaving the endpoint version at 3.

Regarding property naming, while not a reserved keyword the use of uri as a property name seems "risky" in a codegen environment as it is often a reserved keyword in output languages. It may be worthwhile calling these something else (websiteUri for instance).

Finally, x-conditional has been used for these additional fields but no condition has been published in the changeset. Is this an error or is there missing documentation in the proposed changeset?

[CDR-API-Stream]

Hi @perlboy thanks for the feedback.

The staged change only includes a swagger update in swagger-gen which the DSB has previously stated is not an authoritative representation of the Standards and for which no functioning/documented build method is available. Consequently, please publish the resultant markdowns.

The generated markdown will be created as part of the build and release process. All stages changes show the standards code files only.

The proposed change has altered the definition from an inline object definition to a $ref. This is fine (and previously recommended but rejected by the DSB) however the object name of BankingProductV3_additionalInformationV2 is now non-compliant and likely confusing in the future if there is a BankingProductV4 for which additional information is unchanged. Suggest instead naming this object as BankingProductAdditionalInformationV2 and would expect it now to appear in the schemas list. The same applies to BankingProductV3_additionalInformationV2_additionalInformationUris although moving this back to an inline definition may be appropriate since its versioning seems bound to Additional Information.

Noted. This is a good suggestion and the change has been updated to reflect this feedback.

On versioning, while it may be acceptable for an endpoint version to be unchanged overwriting the existing BankingProductV3 model definition implicitly causes issues with those attempting to use code generation (ie. most actual implementers). This has been an issue in both directions. Would suggest the DSB introduce BankingProductV4 even if it is leaving the endpoint version at 3.

This is a good suggestion and the change has been updated to reflect this feedback.

Regarding property naming, while not a reserved keyword the use of uri as a property name seems "risky" in a codegen environment as it is often a reserved keyword in output languages. It may be worthwhile calling these something else (websiteUri for instance).

This is a good suggestion. To remain consistent with the additional information, the field has been changed to additionalInformationUri

Finally, x-conditional has been used for these additional fields but no condition has been published in the changeset. Is this an error or is there missing documentation in the proposed changeset?

The conditionality is specified in the description of the additional details. This has been correctly to assign the conditionality to the primary information document URIs. For example, the condition for the termsUris is "Mandatory if additionalTermsUris includes one or more supporting documents.".

"termsUri": {
    "type": "string",
    "description": "Terms and conditions for the product. Mandatory if `additionalTermsUris` includes one or more supporting documents.",
    "x-cds-type": "URIString"
},
"additionalTermsUris": {
    "type": "array",
    "description": "An array of additional terms and conditions for the product, if applicable. To be treated as secondary documents to the `termsUri`. Only to be used if there is a primary `termsUri`.",
    "items": {
        "$ref": "#/definitions/BankingProductV4_additionalInformationV2_additionalInformationUris"
    }
}

[CDR-API-Stream]

This change was incorporated into release v1.15.0. Refer to Decision 212 for further details.