From 7a1a631d0ca376a80d39436afdc9fcc73f016916 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 4 Sep 2026 22:54:28 +0000 Subject: [PATCH] docs(spec): railSelectionMode is an optional enum, not a nullable one MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two fixes to `OutgoingTransaction.railSelectionMode`. The description claimed "Null when no rail is resolved." That is not how the value is chosen: MANUAL means the caller specified a paymentRail on the destination and AUTO means Lightspark selects one, and that is settled when the payment is quoted, before any rail has been resolved. An auto-routed payment therefore reports AUTO while paymentRail is still null — the combination the sentence said would not occur. The field was also `anyOf: [RailSelectionMode, 'null']` while absent from `required`, making it both optional and nullable. Optional and nullable are independent: optional allows the key to be absent, nullable allows it to be present as `null`. Nothing needs the null here — absent and null carry the same meaning — so only the nullability is dropped and the field stays optional. A bare `$ref` alongside a `description` is valid in OpenAPI 3.1, and `reconciliationInstructions` in this schema already uses that form. Generated clients that emit an explicit null for nullable-and-set fields will now omit the key instead. The generated type is unchanged: an optional `$ref` and an optional nullable `$ref` both produce an optional enum. Co-Authored-By: Claude Opus 5 --- mintlify/openapi.yaml | 6 ++---- openapi.yaml | 6 ++---- .../schemas/transactions/OutgoingTransaction.yaml | 7 ++----- 3 files changed, 6 insertions(+), 13 deletions(-) diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index edd1c5018..de388280b 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -23534,10 +23534,8 @@ components: - type: 'null' description: The payment rail used to settle this transaction (e.g. ACH, WIRE, NEFT, FASTER_PAYMENTS). Uses the same values as the PaymentRail sent on quote requests. Null when no external rail is used (e.g. instant or intra-network transfers, or non-direct-destination transactions) or before a rail is resolved. railSelectionMode: - anyOf: - - $ref: '#/components/schemas/RailSelectionMode' - - type: 'null' - description: How the rail was chosen — MANUAL when the platform specified a paymentRail on the destination, AUTO when Lightspark selects it. Null when no rail is resolved. + $ref: '#/components/schemas/RailSelectionMode' + description: How the rail was chosen — MANUAL when the platform specified a paymentRail on the destination, AUTO when Lightspark selects it. expectedSettlementAt: type: - string diff --git a/openapi.yaml b/openapi.yaml index edd1c5018..de388280b 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -23534,10 +23534,8 @@ components: - type: 'null' description: The payment rail used to settle this transaction (e.g. ACH, WIRE, NEFT, FASTER_PAYMENTS). Uses the same values as the PaymentRail sent on quote requests. Null when no external rail is used (e.g. instant or intra-network transfers, or non-direct-destination transactions) or before a rail is resolved. railSelectionMode: - anyOf: - - $ref: '#/components/schemas/RailSelectionMode' - - type: 'null' - description: How the rail was chosen — MANUAL when the platform specified a paymentRail on the destination, AUTO when Lightspark selects it. Null when no rail is resolved. + $ref: '#/components/schemas/RailSelectionMode' + description: How the rail was chosen — MANUAL when the platform specified a paymentRail on the destination, AUTO when Lightspark selects it. expectedSettlementAt: type: - string diff --git a/openapi/components/schemas/transactions/OutgoingTransaction.yaml b/openapi/components/schemas/transactions/OutgoingTransaction.yaml index 19919cc2e..e6b3b1c24 100644 --- a/openapi/components/schemas/transactions/OutgoingTransaction.yaml +++ b/openapi/components/schemas/transactions/OutgoingTransaction.yaml @@ -82,13 +82,10 @@ allOf: or intra-network transfers, or non-direct-destination transactions) or before a rail is resolved. railSelectionMode: - anyOf: - - $ref: ../common/RailSelectionMode.yaml - - type: 'null' + $ref: ../common/RailSelectionMode.yaml description: >- How the rail was chosen — MANUAL when the platform specified a - paymentRail on the destination, AUTO when Lightspark selects it. Null - when no rail is resolved. + paymentRail on the destination, AUTO when Lightspark selects it. expectedSettlementAt: type: - string