From c82fa99d331a8e0ed97b50458d640c21d47260b6 Mon Sep 17 00:00:00 2001 From: Peng Ying Date: Tue, 24 Feb 2026 21:57:47 -0800 Subject: [PATCH 1/2] fix: remove remaining title/$ref siblings and add missing titles - Remove title lines from ExternalAccountInfoOneOf.yaml oneOf entries (titles as $ref siblings are ignored per OpenAPI spec) - Remove title/$ref siblings from CadExternalAccountInfo and NgnExternalAccountInfo beneficiary oneOf entries - Add missing titles to CadBeneficiary.yaml and NgnBeneficiary.yaml Co-Authored-By: Claude Opus 4.6 --- mintlify/openapi.yaml | 80 +++++++------------ openapi.yaml | 80 +++++++------------ .../schemas/common/CadBeneficiary.yaml | 1 + .../schemas/common/NgnBeneficiary.yaml | 1 + .../CadExternalAccountInfo.yaml | 6 +- .../ExternalAccountInfoOneOf.yaml | 66 +++++---------- .../NgnExternalAccountInfo.yaml | 6 +- 7 files changed, 84 insertions(+), 156 deletions(-) diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 13522163..81b424b9 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -5733,6 +5733,7 @@ components: INDIVIDUAL: '#/components/schemas/BrlBeneficiary' BUSINESS: '#/components/schemas/BusinessBeneficiary' CadBeneficiary: + title: Individual Beneficiary type: object required: - beneficiaryType @@ -5776,10 +5777,8 @@ components: properties: beneficiary: oneOf: - - title: Individual Beneficiary - $ref: '#/components/schemas/CadBeneficiary' - - title: Business Beneficiary - $ref: '#/components/schemas/BusinessBeneficiary' + - $ref: '#/components/schemas/CadBeneficiary' + - $ref: '#/components/schemas/BusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: @@ -6202,6 +6201,7 @@ components: INDIVIDUAL: '#/components/schemas/MyrBeneficiary' BUSINESS: '#/components/schemas/BusinessBeneficiary' NgnBeneficiary: + title: Individual Beneficiary type: object required: - beneficiaryType @@ -6245,10 +6245,8 @@ components: properties: beneficiary: oneOf: - - title: Individual Beneficiary - $ref: '#/components/schemas/NgnBeneficiary' - - title: Business Beneficiary - $ref: '#/components/schemas/BusinessBeneficiary' + - $ref: '#/components/schemas/NgnBeneficiary' + - $ref: '#/components/schemas/BusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: @@ -6571,50 +6569,28 @@ components: - $ref: '#/components/schemas/BaseWalletInfo' ExternalAccountInfoOneOf: oneOf: - - title: BRL Account - $ref: '#/components/schemas/BrlExternalAccountInfo' - - title: CAD Account - $ref: '#/components/schemas/CadExternalAccountInfo' - - title: DKK Account - $ref: '#/components/schemas/DkkExternalAccountInfo' - - title: EUR Account - $ref: '#/components/schemas/EurExternalAccountInfo' - - title: GBP Account - $ref: '#/components/schemas/GbpExternalAccountInfo' - - title: HKD Account - $ref: '#/components/schemas/HkdExternalAccountInfo' - - title: IDR Account - $ref: '#/components/schemas/IdrExternalAccountInfo' - - title: INR Account - $ref: '#/components/schemas/InrExternalAccountInfo' - - title: MXN Account - $ref: '#/components/schemas/MxnExternalAccountInfo' - - title: MYR Account - $ref: '#/components/schemas/MyrExternalAccountInfo' - - title: NGN Account - $ref: '#/components/schemas/NgnExternalAccountInfo' - - title: PHP Account - $ref: '#/components/schemas/PhpExternalAccountInfo' - - title: SGD Account - $ref: '#/components/schemas/SgdExternalAccountInfo' - - title: THB Account - $ref: '#/components/schemas/ThbExternalAccountInfo' - - title: USD Account - $ref: '#/components/schemas/UsdExternalAccountInfo' - - title: VND Account - $ref: '#/components/schemas/VndExternalAccountInfo' - - title: Spark Wallet - $ref: '#/components/schemas/SparkWalletExternalAccountInfo' - - title: Lightning - $ref: '#/components/schemas/LightningExternalAccountInfo' - - title: Solana Wallet - $ref: '#/components/schemas/SolanaWalletExternalAccountInfo' - - title: Tron Wallet - $ref: '#/components/schemas/TronWalletExternalAccountInfo' - - title: Polygon Wallet - $ref: '#/components/schemas/PolygonWalletExternalAccountInfo' - - title: Base Wallet - $ref: '#/components/schemas/BaseWalletExternalAccountInfo' + - $ref: '#/components/schemas/BrlExternalAccountInfo' + - $ref: '#/components/schemas/CadExternalAccountInfo' + - $ref: '#/components/schemas/DkkExternalAccountInfo' + - $ref: '#/components/schemas/EurExternalAccountInfo' + - $ref: '#/components/schemas/GbpExternalAccountInfo' + - $ref: '#/components/schemas/HkdExternalAccountInfo' + - $ref: '#/components/schemas/IdrExternalAccountInfo' + - $ref: '#/components/schemas/InrExternalAccountInfo' + - $ref: '#/components/schemas/MxnExternalAccountInfo' + - $ref: '#/components/schemas/MyrExternalAccountInfo' + - $ref: '#/components/schemas/NgnExternalAccountInfo' + - $ref: '#/components/schemas/PhpExternalAccountInfo' + - $ref: '#/components/schemas/SgdExternalAccountInfo' + - $ref: '#/components/schemas/ThbExternalAccountInfo' + - $ref: '#/components/schemas/UsdExternalAccountInfo' + - $ref: '#/components/schemas/VndExternalAccountInfo' + - $ref: '#/components/schemas/SparkWalletExternalAccountInfo' + - $ref: '#/components/schemas/LightningExternalAccountInfo' + - $ref: '#/components/schemas/SolanaWalletExternalAccountInfo' + - $ref: '#/components/schemas/TronWalletExternalAccountInfo' + - $ref: '#/components/schemas/PolygonWalletExternalAccountInfo' + - $ref: '#/components/schemas/BaseWalletExternalAccountInfo' discriminator: propertyName: accountType mapping: diff --git a/openapi.yaml b/openapi.yaml index 13522163..81b424b9 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -5733,6 +5733,7 @@ components: INDIVIDUAL: '#/components/schemas/BrlBeneficiary' BUSINESS: '#/components/schemas/BusinessBeneficiary' CadBeneficiary: + title: Individual Beneficiary type: object required: - beneficiaryType @@ -5776,10 +5777,8 @@ components: properties: beneficiary: oneOf: - - title: Individual Beneficiary - $ref: '#/components/schemas/CadBeneficiary' - - title: Business Beneficiary - $ref: '#/components/schemas/BusinessBeneficiary' + - $ref: '#/components/schemas/CadBeneficiary' + - $ref: '#/components/schemas/BusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: @@ -6202,6 +6201,7 @@ components: INDIVIDUAL: '#/components/schemas/MyrBeneficiary' BUSINESS: '#/components/schemas/BusinessBeneficiary' NgnBeneficiary: + title: Individual Beneficiary type: object required: - beneficiaryType @@ -6245,10 +6245,8 @@ components: properties: beneficiary: oneOf: - - title: Individual Beneficiary - $ref: '#/components/schemas/NgnBeneficiary' - - title: Business Beneficiary - $ref: '#/components/schemas/BusinessBeneficiary' + - $ref: '#/components/schemas/NgnBeneficiary' + - $ref: '#/components/schemas/BusinessBeneficiary' discriminator: propertyName: beneficiaryType mapping: @@ -6571,50 +6569,28 @@ components: - $ref: '#/components/schemas/BaseWalletInfo' ExternalAccountInfoOneOf: oneOf: - - title: BRL Account - $ref: '#/components/schemas/BrlExternalAccountInfo' - - title: CAD Account - $ref: '#/components/schemas/CadExternalAccountInfo' - - title: DKK Account - $ref: '#/components/schemas/DkkExternalAccountInfo' - - title: EUR Account - $ref: '#/components/schemas/EurExternalAccountInfo' - - title: GBP Account - $ref: '#/components/schemas/GbpExternalAccountInfo' - - title: HKD Account - $ref: '#/components/schemas/HkdExternalAccountInfo' - - title: IDR Account - $ref: '#/components/schemas/IdrExternalAccountInfo' - - title: INR Account - $ref: '#/components/schemas/InrExternalAccountInfo' - - title: MXN Account - $ref: '#/components/schemas/MxnExternalAccountInfo' - - title: MYR Account - $ref: '#/components/schemas/MyrExternalAccountInfo' - - title: NGN Account - $ref: '#/components/schemas/NgnExternalAccountInfo' - - title: PHP Account - $ref: '#/components/schemas/PhpExternalAccountInfo' - - title: SGD Account - $ref: '#/components/schemas/SgdExternalAccountInfo' - - title: THB Account - $ref: '#/components/schemas/ThbExternalAccountInfo' - - title: USD Account - $ref: '#/components/schemas/UsdExternalAccountInfo' - - title: VND Account - $ref: '#/components/schemas/VndExternalAccountInfo' - - title: Spark Wallet - $ref: '#/components/schemas/SparkWalletExternalAccountInfo' - - title: Lightning - $ref: '#/components/schemas/LightningExternalAccountInfo' - - title: Solana Wallet - $ref: '#/components/schemas/SolanaWalletExternalAccountInfo' - - title: Tron Wallet - $ref: '#/components/schemas/TronWalletExternalAccountInfo' - - title: Polygon Wallet - $ref: '#/components/schemas/PolygonWalletExternalAccountInfo' - - title: Base Wallet - $ref: '#/components/schemas/BaseWalletExternalAccountInfo' + - $ref: '#/components/schemas/BrlExternalAccountInfo' + - $ref: '#/components/schemas/CadExternalAccountInfo' + - $ref: '#/components/schemas/DkkExternalAccountInfo' + - $ref: '#/components/schemas/EurExternalAccountInfo' + - $ref: '#/components/schemas/GbpExternalAccountInfo' + - $ref: '#/components/schemas/HkdExternalAccountInfo' + - $ref: '#/components/schemas/IdrExternalAccountInfo' + - $ref: '#/components/schemas/InrExternalAccountInfo' + - $ref: '#/components/schemas/MxnExternalAccountInfo' + - $ref: '#/components/schemas/MyrExternalAccountInfo' + - $ref: '#/components/schemas/NgnExternalAccountInfo' + - $ref: '#/components/schemas/PhpExternalAccountInfo' + - $ref: '#/components/schemas/SgdExternalAccountInfo' + - $ref: '#/components/schemas/ThbExternalAccountInfo' + - $ref: '#/components/schemas/UsdExternalAccountInfo' + - $ref: '#/components/schemas/VndExternalAccountInfo' + - $ref: '#/components/schemas/SparkWalletExternalAccountInfo' + - $ref: '#/components/schemas/LightningExternalAccountInfo' + - $ref: '#/components/schemas/SolanaWalletExternalAccountInfo' + - $ref: '#/components/schemas/TronWalletExternalAccountInfo' + - $ref: '#/components/schemas/PolygonWalletExternalAccountInfo' + - $ref: '#/components/schemas/BaseWalletExternalAccountInfo' discriminator: propertyName: accountType mapping: diff --git a/openapi/components/schemas/common/CadBeneficiary.yaml b/openapi/components/schemas/common/CadBeneficiary.yaml index c3b5722d..c3941bc0 100644 --- a/openapi/components/schemas/common/CadBeneficiary.yaml +++ b/openapi/components/schemas/common/CadBeneficiary.yaml @@ -1,3 +1,4 @@ +title: Individual Beneficiary type: object required: - beneficiaryType diff --git a/openapi/components/schemas/common/NgnBeneficiary.yaml b/openapi/components/schemas/common/NgnBeneficiary.yaml index c3b5722d..c3941bc0 100644 --- a/openapi/components/schemas/common/NgnBeneficiary.yaml +++ b/openapi/components/schemas/common/NgnBeneficiary.yaml @@ -1,3 +1,4 @@ +title: Individual Beneficiary type: object required: - beneficiaryType diff --git a/openapi/components/schemas/external_accounts/CadExternalAccountInfo.yaml b/openapi/components/schemas/external_accounts/CadExternalAccountInfo.yaml index 916c0015..7d92d348 100644 --- a/openapi/components/schemas/external_accounts/CadExternalAccountInfo.yaml +++ b/openapi/components/schemas/external_accounts/CadExternalAccountInfo.yaml @@ -8,10 +8,8 @@ allOf: properties: beneficiary: oneOf: - - title: Individual Beneficiary - $ref: ../common/CadBeneficiary.yaml - - title: Business Beneficiary - $ref: ../common/BusinessBeneficiary.yaml + - $ref: ../common/CadBeneficiary.yaml + - $ref: ../common/BusinessBeneficiary.yaml discriminator: propertyName: beneficiaryType mapping: diff --git a/openapi/components/schemas/external_accounts/ExternalAccountInfoOneOf.yaml b/openapi/components/schemas/external_accounts/ExternalAccountInfoOneOf.yaml index 5569873b..8878b747 100644 --- a/openapi/components/schemas/external_accounts/ExternalAccountInfoOneOf.yaml +++ b/openapi/components/schemas/external_accounts/ExternalAccountInfoOneOf.yaml @@ -1,48 +1,26 @@ oneOf: -- title: BRL Account - $ref: ./BrlExternalAccountInfo.yaml -- title: CAD Account - $ref: ./CadExternalAccountInfo.yaml -- title: DKK Account - $ref: ./DkkExternalAccountInfo.yaml -- title: EUR Account - $ref: ./EurExternalAccountInfo.yaml -- title: GBP Account - $ref: ./GbpExternalAccountInfo.yaml -- title: HKD Account - $ref: ./HkdExternalAccountInfo.yaml -- title: IDR Account - $ref: ./IdrExternalAccountInfo.yaml -- title: INR Account - $ref: ./InrExternalAccountInfo.yaml -- title: MXN Account - $ref: ./MxnExternalAccountInfo.yaml -- title: MYR Account - $ref: ./MyrExternalAccountInfo.yaml -- title: NGN Account - $ref: ./NgnExternalAccountInfo.yaml -- title: PHP Account - $ref: ./PhpExternalAccountInfo.yaml -- title: SGD Account - $ref: ./SgdExternalAccountInfo.yaml -- title: THB Account - $ref: ./ThbExternalAccountInfo.yaml -- title: USD Account - $ref: ./UsdExternalAccountInfo.yaml -- title: VND Account - $ref: ./VndExternalAccountInfo.yaml -- title: Spark Wallet - $ref: ./SparkWalletExternalAccountInfo.yaml -- title: Lightning - $ref: ./LightningExternalAccountInfo.yaml -- title: Solana Wallet - $ref: ./SolanaWalletExternalAccountInfo.yaml -- title: Tron Wallet - $ref: ./TronWalletExternalAccountInfo.yaml -- title: Polygon Wallet - $ref: ./PolygonWalletExternalAccountInfo.yaml -- title: Base Wallet - $ref: ./BaseWalletExternalAccountInfo.yaml +- $ref: ./BrlExternalAccountInfo.yaml +- $ref: ./CadExternalAccountInfo.yaml +- $ref: ./DkkExternalAccountInfo.yaml +- $ref: ./EurExternalAccountInfo.yaml +- $ref: ./GbpExternalAccountInfo.yaml +- $ref: ./HkdExternalAccountInfo.yaml +- $ref: ./IdrExternalAccountInfo.yaml +- $ref: ./InrExternalAccountInfo.yaml +- $ref: ./MxnExternalAccountInfo.yaml +- $ref: ./MyrExternalAccountInfo.yaml +- $ref: ./NgnExternalAccountInfo.yaml +- $ref: ./PhpExternalAccountInfo.yaml +- $ref: ./SgdExternalAccountInfo.yaml +- $ref: ./ThbExternalAccountInfo.yaml +- $ref: ./UsdExternalAccountInfo.yaml +- $ref: ./VndExternalAccountInfo.yaml +- $ref: ./SparkWalletExternalAccountInfo.yaml +- $ref: ./LightningExternalAccountInfo.yaml +- $ref: ./SolanaWalletExternalAccountInfo.yaml +- $ref: ./TronWalletExternalAccountInfo.yaml +- $ref: ./PolygonWalletExternalAccountInfo.yaml +- $ref: ./BaseWalletExternalAccountInfo.yaml discriminator: propertyName: accountType mapping: diff --git a/openapi/components/schemas/external_accounts/NgnExternalAccountInfo.yaml b/openapi/components/schemas/external_accounts/NgnExternalAccountInfo.yaml index 0109b2b9..dd992964 100644 --- a/openapi/components/schemas/external_accounts/NgnExternalAccountInfo.yaml +++ b/openapi/components/schemas/external_accounts/NgnExternalAccountInfo.yaml @@ -8,10 +8,8 @@ allOf: properties: beneficiary: oneOf: - - title: Individual Beneficiary - $ref: ../common/NgnBeneficiary.yaml - - title: Business Beneficiary - $ref: ../common/BusinessBeneficiary.yaml + - $ref: ../common/NgnBeneficiary.yaml + - $ref: ../common/BusinessBeneficiary.yaml discriminator: propertyName: beneficiaryType mapping: From 8531eac0e2ffbd5ef50b29bf1729f355ed97b7f6 Mon Sep 17 00:00:00 2001 From: Peng Ying Date: Tue, 24 Feb 2026 22:34:49 -0800 Subject: [PATCH 2/2] docs: add title placement and discriminator location guidelines to README Document two common pitfalls when defining oneOf schemas: - Discriminators must only exist on the OneOf wrapper, not base schemas - Titles must be inside referenced schema files, not as $ref siblings Co-Authored-By: Claude Opus 4.6 --- openapi/README.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/openapi/README.md b/openapi/README.md index c2e6f03e..5426ce2f 100644 --- a/openapi/README.md +++ b/openapi/README.md @@ -275,6 +275,72 @@ discriminator: BUSINESS: '#/components/schemas/BusinessCustomer' ``` +#### Discriminator placement: OneOf wrapper only + +The `discriminator` block must only appear on the **OneOf wrapper** schema, never on the base schema. If both the base and wrapper define a discriminator, Mintlify renders duplicate type options in the UI. + +```yaml +# ✅ Correct — discriminator on the OneOf wrapper only +# ExternalAccountInfoOneOf.yaml +oneOf: + - $ref: ./UsdExternalAccountInfo.yaml + - $ref: ./EurExternalAccountInfo.yaml +discriminator: + propertyName: accountType + mapping: + USD_ACCOUNT: ./UsdExternalAccountInfo.yaml + EUR_ACCOUNT: ./EurExternalAccountInfo.yaml + +# BaseExternalAccountInfo.yaml — NO discriminator here +type: object +properties: + accountType: + type: string +``` + +```yaml +# ❌ Wrong — discriminator on both base and wrapper causes duplicate rendering +# BaseExternalAccountInfo.yaml +type: object +properties: + accountType: + type: string +discriminator: # ← remove this + propertyName: accountType + mapping: ... +``` + +#### Titles must be inside the schema, not next to `$ref` + +In OpenAPI, properties that are siblings to `$ref` are ignored. A `title:` placed next to `$ref:` in a `oneOf` entry will be silently dropped, so Mintlify won't display it. + +Instead, place `title:` as the **first line** of the referenced schema file. + +```yaml +# ✅ Correct — title inside the referenced schema +# CustomerOneOf.yaml +oneOf: + - $ref: ./IndividualCustomer.yaml + - $ref: ./BusinessCustomer.yaml + +# IndividualCustomer.yaml +title: Individual Customer # ← title goes here +allOf: + - $ref: ./Customer.yaml + - ... +``` + +```yaml +# ❌ Wrong — title as $ref sibling is ignored by OpenAPI parsers +oneOf: + - title: Individual Customer # ← ignored + $ref: ./IndividualCustomer.yaml + - title: Business Customer # ← ignored + $ref: ./BusinessCustomer.yaml +``` + +When adding a new variant schema to a `oneOf`, always add a `title:` as the first line of the variant file. + #### Three-layer discriminator pattern We use a three-layer pattern for discriminated unions: